企业 AI 项目 Wiki · 环境、版本与上线

版本号

也常写作Version number · 软件版本号 · 版本标识 · Release version

定义

版本号是按照一套约定规则分配给某个可变对象状态的标识，用来区分、引用、排序或说明它与其他状态的关系。一个有效的项目版本号必须能回查到明确的对象和变更记录；如果同一个号码可以指向不同内容，或者号码变化却无法说明对应对象，版本号就只能充当展示文字，不能可靠支持部署、验收、回滚和故障定位。

版本号首先是标识，不是质量结论

版本号解决的是“我们正在讨论哪一个状态”。客户报告问题、测试人员记录结果、流水线部署产物、运维团队执行回退时，都需要引用同一对象。没有稳定标识，同一句“最新版本”在不同时间、环境和人员那里可能指向完全不同的内容。

数字大小本身不证明新版本更稳定、更安全或已经验收。`2.0.0` 可能只是一个尚未测试的候选，`1.8.12` 也可能是当前正式生产版本。是否可发布、可验收、可投入生产，需要另外的测试、批准和环境记录。

版本号的含义来自版本策略。看起来都是 `X.Y.Z` 的两个产品，可能一个遵循公开 API 兼容性的语义化版本，另一个只是内部里程碑编号。没有先说明规则，就不能仅凭三段数字推断改动大小。

常见版本方案怎样理解

语义化版本（SemVer）

在已声明公共 API 的前提下使用 `MAJOR.MINOR.PATCH`：不兼容 API 变更增加主版本，向后兼容功能增加次版本，向后兼容修复增加补丁版本；可附预发布标识和不参与优先级的构建元数据。

递增发布号

使用 `v17`、`release-42` 等单调递增编号，容易判断先后，却不表达兼容性或变更类型，需要配合变更记录。

日期或周期版本

用年份、月份、季度或迭代标识，例如 `2026.08`。它表达计划周期或发布时间，不自动表示两个版本的兼容程度，也要规定补发和同日多次构建怎样编号。

四段或平台特定版本

某些运行时使用主版本、次版本、构建、修订等结构。.NET 同时存在包版本、程序集版本、文件版本和信息版本，它们的使用者与运行时作用并不相同。

预发布标识

`alpha`、`beta`、`rc.1` 等通常说明尚未成为普通稳定版。若采用 SemVer，同一主次补丁号的预发布版本优先级低于正式版本；团队还要定义预发布能进入哪些环境。

组合或产品版本

面向客户的产品版本可以统领多个组件，但必须有清单把它映射到实际前端、后端、数据库、模型和配置版本，不能假定所有组件号码相同。

版本号与其他标识分别证明什么

标识	能说明和不能说明的内容
版本号	按声明规则命名某个状态，便于沟通与比较；只有绑定到对象后才能证明具体内容。
构建号	区分一次 CI/CD 构建或流水线运行，适合追踪生成过程；同一产品版本可以有多次构建。
Git 提交 ID	标识源代码仓库中的不可变提交及其历史；不包含构建环境、依赖解析、配置、数据库和外部模型状态。
制品摘要	内容寻址摘要可校验取得的二进制、镜像或清单是否为同一字节内容；它难读，也不直接表达业务兼容性。
标签或别名	`latest`、`stable`、`production` 等是可移动引用，方便选择当前目标；移动后同一名称会指向新对象，不能单独作为历史证据。
发布日期或发布名称	说明一次对外发布事件或市场名称，可能覆盖多个版本，也可能同一构建从未正式发布。

一套可执行的版本规则要写清什么

版本对象是什么？
明确编号给产品、服务、API、数据库结构、配置包、移动应用还是模型；不同生命周期的对象不要强行共用一个号码。
记录：对象名称、所有者、存储位置和作用范围。
格式和递增含义是什么？
定义字段、允许字符、排序方法、主次补丁或日期字段的含义，以及零版本、分支版本和紧急修复规则。
记录：版本策略，以及有效与无效写法。
何时分配和冻结？
说明开发中、候选、验收、正式发布各阶段何时生成号码，修改内容后是否必须换号。
记录：生成事件、冻结门禁和修改规则。
怎样绑定不可变对象？
版本记录包含源码提交、构建运行、依赖锁定文件、制品 URI 与摘要、数据库迁移和配置基线。
记录：可机器读取的版本清单或发布清单。
怎样表达兼容和支持？
若号码承诺 API、数据格式或客户端兼容性，要定义兼容面、弃用周期、升级路径和支持期限，而不是只写“向下兼容”。
记录：兼容矩阵、破坏性变更和支持政策。
谁可以发布或移动标签？
限制创建正式版本、重打标签、覆盖制品和移动 `stable` 别名的权限，并保留审计。
记录：仓库保护、签名、审批和标签变更日志。
用户在哪里能看到？
页面、API、日志、健康端点和支持材料应能报告足够版本信息，但不暴露内部路径、密钥或不必要的攻击面信息。
记录：版本查询方法和客户问题定位步骤。

项目里怎样使用版本号

确定产品与组件层级
先决定客户沟通使用哪个产品版本，再列出必须独立追踪的应用、服务、数据库、配置和内容组件。
自动生成关联记录
构建时写入版本、提交、构建号、依赖和制品摘要，避免人工在文档中复制后失去同步。
同一制品跨环境提升
测试、UAT、预发布和生产尽量提升已经构建的同一不可变制品；若重新构建，即使版本文字相同也要产生新的构建与摘要记录。
把测试证据绑定版本
用例、缺陷、性能报告、安全扫描和验收结论都记录适用版本、构建和环境，修复后形成新对象并复测。
把部署记录绑定版本
每个环境保存何时由谁部署哪个产品和组件版本，以及配置、迁移和摘要；“已上线最新版”不是可审计记录。
为回退保留旧对象
旧版本的制品、配置、迁移兼容条件和恢复说明按保留策略保存，不能只有号码却无法重新取得内容。

企业 AI 项目的版本号为什么必须是组合清单

应用与编排版本

记录前后端、工作流、智能体图、工具定义和业务规则。应用代码不变，工具参数或编排变化也可能改变业务结果。

模型版本或快照

记录供应商、模型 ID、固定快照或托管注册表版本、区域和部署名称。`latest`、`default`、`stable` 等别名可移动，只能同时记录当时解析到的具体版本。

提示词与安全策略

系统提示词、模板、结构化输出模式、内容过滤、Guardrail 和人工批准规则分别版本化，不能只存最后一份文本。

知识与检索版本

记录源文件批次、权限快照、清洗、切分、嵌入模型、索引构建、检索和重排配置；文件名或索引名称不足以复现知识状态。

评测集与评分版本

测试样本、参考答案、量表、评审人校准和自动评测器也会变化。结果必须同时报告系统版本和评测版本，否则前后分数不可比。

外部服务与运行参数

模型参数、工具 API 版本、第三方规则、功能开关和关键环境配置纳入清单。无法固定的托管依赖要记录观察时间、已知变更政策和重新验证触发条件。

版本号容易与什么混淆

相关概念	与版本号的区别
版本	版本是对象在某一时刻的具体状态；版本号是赋给该状态的标识。一个版本还应包含内容和元数据。
构建	构建是从源码和依赖生成制品的过程或结果。同一版本号可能因重试、平台不同或依赖变化产生不同构建。
发布	发布是让指定版本可供某类用户使用的业务与技术事件；有版本号不表示已经发布。
验收版本	验收版本是被指定为正式验收对象的完整版本基线；版本号只是其中一个标识，不能单独证明验收范围。
生产版本	生产版本是当前在生产环境实际运行的对象，必须从部署状态确认，不能由版本号大小推断。
变更记录	变更记录说明两个版本之间改了什么、为什么改和影响什么；版本号只提供引用入口。

依据与适用边界

本文解释用于标识软件、服务、配置或其他可变对象状态的版本号。它不规定所有项目必须采用语义化版本，也不把版本号默认等同于构建号、发布日期、Git 提交、镜像摘要、标签、发布名称、验收版本或当前生产版本。具体格式和递增含义只有在团队声明并持续执行同一套版本规则时才成立。