版本与兼容
1分钟内可阅读完
本次文档依据
本轮文档于 2026-10-04 对以下源码快照核对。VERSION、模板依赖和已发布 Release 是不同的信息；下表不表示三个仓库已发布同号版本，也不表示全部组合通过运行验证。
| 仓库 | 源码 VERSION | 本轮依据 | 职责 |
|---|---|---|---|
| pkg | v0.5.1 | 855aac0 | 运行时及生成后的公共 API |
| api | v0.4.1 | 4424ef8 | 公共 Proto、Gateway 与 OpenAPI 契约 |
| cli | 0.5.1 | 09d8a25 | 生成器、服务模板与迁移命令 |
模板依赖基线
当前 CLI 的服务模板 go.mod.tmpl 指定 Go 1.25.13，并固定以下主要依赖。已有项目应以自身 go.mod 与 go.sum 为准。
| 组件 | 模板版本 |
|---|---|
| grpc-kit/pkg | v0.5.1 |
| gRPC Go | v1.83.2 |
| Protobuf Go | v1.36.11 |
| grpc-gateway | v2.30.0 |
| OpenTelemetry | v1.45.0 |
| ent | v0.14.5 |
| MCP Go SDK | v1.7.0 |
模板的 scripts/binaries.sh 使用 protoc 21.12、protoc-gen-go v1.36.11、protoc-gen-go-grpc v1.6.2 与 gateway/OpenAPI 插件 v2.30.0。运行库升级不意味着编译器也自动升级。
CLI 仓库自身的模板兼容测试流水线仍引用 API v0.3.1，与 API 仓库 VERSION v0.4.1 不一致。因此 API v0.4.1 与当前模板的完整兼容性不能仅凭版本号断言；更新 include 来源时应固定 commit 并完成生成、单测、构建和 E2E。
升级路径
- 保存当前 Git commit、CLI 版本、模块依赖和数据库备份。
- 阅读项目迁移，预览托管文件 diff。
- 分别升级用户维护的
go.mod、业务代码和契约 include；不要把模板迁移当作依赖升级。 - 按部署检查执行验证，再发布应用。
本轮验证覆盖文档构建与站内链接；未在此环境运行 Go、数据库、MCP 客户端或容器验证。正式发布版本请到各仓库 Releases 核实，不使用 @latest 代替兼容矩阵。