# Fzx项目版本自动化管控优化落地文档（对标大厂规范·全配置整合版）
**文档版本**: V1.4
**更新日期**: 2026-06-22
**方案说明**: 基于VERSION文件单一版本源 + Python脚本自动化方案
---
## 📋 文档修订记录
| 版本 | 日期 | 修改内容 | 作者 |
|----------|---------|--------------------------------------------------|------|
| V1.0 | 2026-05 | 初始版本 | 技术团队 |
| V1.1 | 2026-06 | 完善项目实际配置、补充大厂最佳实践 | 技术团队 |
| V1.2 | 2026-06 | 更新实际配置文件、验证构建成功 | 技术团队 |
| V1.3 | 2026-06 | 修复构建问题、配置dependency-check离线模式、创建标准正式标签v1.1.0 | 技术团队 |
| **V1.4** | 2026-06 | **更新为VERSION文件+Python脚本方案（已实际落地实施）** | 技术团队 |
---
## 1 整体方案概述
### 1.1 核心思路（已废弃jgitver方案）
> ⚠️ **重要更新 (V1.4)**：原文档描述的jgitver方案未实际实施。当前项目使用**VERSION文件单一版本源 + Python脚本自动化**方案，已落地实施。
**实际实施的方案**：
| 方案要素 | 说明 |
|--------------|------------------------------------------|
| 单一版本源 | `VERSION`文件作为唯一版本基准 |
| 版本同步 | `update_version.py`自动同步到pom.xml、前端配置 |
| 版本校验 | `version_check.py`独立安全门禁 |
| CI/CD集成 | Jenkins Pipeline Pre-Build阶段集成 |
| Python兼容性 | 兼容Python 3.6+（Jenkins节点可能使用Python 3.6） |
### 1.2 版本编号规则
| 构建场景 | 版本格式示例 | 说明 |
|-------------------|--------------------------------------|----------|
| 后端pom | `1.1.1-SNAPSHOT` | Maven使用 |
| 完整版本号 | `1.1.1-develop-d30fcd0c-526` | 包含元数据 |
| 前端package.json | `1.1.1-develop-d30fcd0c-526` | Web前端 |
| Flutter pubspec | `1.1.1+526` | 移动端 |
| 镜像标签 | `v1.1.1` / `v1.1.1-526` | 容器镜像 |
### 1.3 方案优势
| 优势 | 说明 |
|-----------|------------------------------------------|
| **简单直观** | 版本号配置一目了然，无需复杂计算 |
| **可靠同步** | 单一版本源 + 自动同步，杜绝版本不一致 |
| **双重保障** | 自动同步 + 独立校验，任何一步失败都能拦截 |
| **广泛兼容** | Python 3.6+ 兼容，适配各种环境 |
| **易于维护** | 纯Python实现，无额外Maven插件依赖 |
---
## 2 核心配置文件
### 2.1 VERSION文件（单一版本源）
**位置**: 项目根目录 `VERSION`
```bash
BASE_VERSION=1.1.1
BUILD_NUMBER=526
LAST_UPDATED=2026-06-22 10:30:00
```
**说明**：
- `BASE_VERSION`: 基础版本号，修改版本只需改这个值
- `BUILD_NUMBER`: Jenkins BUILD_NUMBER，自动更新
- `LAST_UPDATED`: 最后更新时间
### 2.2 父pom.xml配置
**位置**: 项目根目录 `pom.xml`
```xml
1.1.1-SNAPSHOT
21
21
21
UTF-8
```
### 2.3 子服务pom.xml配置
**说明**: 子服务使用 `${revision}` 占位符继承父pom版本，无需单独配置
```xml
com.fzx
fzx-platform
${revision}
../../pom.xml
api-gateway
${revision}
```
---
## 3 核心脚本说明
### 3.1 update_version.py（版本同步脚本）
**位置**: `scripts/update_version.py`
| 功能 | 说明 | 命令行参数 |
|----------|--------------|-----------|
| 完整同步 | 校验+自动修复+同步 | (无参数) |
| 仅校验 | 仅检查不一致不修复 | `--check` |
| 校验+修复 | 校验并自动修复不一致 | `--fix` |
| 单服务更新 | 仅更新指定服务版本 | `--single 服务名` |
**使用示例**：
```bash
# 完整同步流程（默认）
python scripts/update_version.py
# 仅校验版本一致性
python scripts/update_version.py --check
# 校验+自动修复
python scripts/update_version.py --fix
# 更新单个服务
python scripts/update_version.py --single auth-service
```
### 3.2 version_check.py（版本校验脚本）
**位置**: `scripts/version_check.py`
| 校验项 | 说明 |
|---------------|------------------------------------------|
| 版本格式校验 | pom revision格式X.Y.Z或X.Y.Z-SNAPSHOT |
| 分支版本绑定校验 | release分支无SNAPSHOT，develop必须有SNAPSHOT |
| VERSION一致性校验 | pom版本与VERSION文件BASE_VERSION一致 |
| 工作区清洁度校验 | 非develop分支不能有未提交变更 |
| Commit哈希校验 | 8位commit hash正常读取 |
### 3.3 Python兼容性处理
```python
# 设置标准输出为UTF-8编码（兼容Python 3.6）
try:
sys.stdout.reconfigure(encoding='utf-8')
except AttributeError:
# Python 3.6 不支持reconfigure，使用默认编码
pass
```
---
## 4 Jenkins Pipeline集成
### 4.1 Pre-Build阶段
```groovy
stage('Pre-Build') {
steps {
script {
echo '🔄 同步版本号（VERSION文件 -> pom.xml）'
sh "python scripts/update_version.py --fix"
// 计算完整版本号
def pomVersion = sh(script: 'mvn help:evaluate -Dexpression=project.version -q -DforceStdout', returnStdout: true).trim()
def branch = sh(script: 'git rev-parse --abbrev-ref HEAD', returnStdout: true).trim()
def commitHash = sh(script: 'git rev-parse --short=8 HEAD', returnStdout: true).trim()
def buildNum = env.BUILD_NUMBER ?: new Date().format('yyyyMMddHHmmss')
def baseVersion = pomVersion.replace('-SNAPSHOT', '')
def cleanBranch = branch.replace('/', '-')
env.POM_VERSION = pomVersion
env.BASE_VERSION = baseVersion
env.BRANCH_NAME = branch
env.COMMIT_HASH = commitHash
env.BUILD_NUM = buildNum
if (!env.FULL_VERSION) {
env.FULL_VERSION = "${baseVersion}-${cleanBranch}-${commitHash}-${buildNum}"
}
echo "📊 完整版本号: ${env.FULL_VERSION}"
}
}
}
```
### 4.2 版本合规校验阶段
```groovy
stage('版本合规校验') {
steps {
echo '🔍 执行版本合规校验（大厂标准）'
sh "python scripts/version_check.py"
}
post {
success {
echo '✅ 版本合规校验通过'
}
failure {
echo '❌ 版本合规校验失败'
error('版本不合规，终止构建')
}
}
}
```
---
## 5 版本管理完整流程
```
┌─────────────────────────────────────────────────────────────────────┐
│ 版本管理完整流程（已落地实现） │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 唯一入口：修改VERSION文件中的BASE_VERSION │
│ ↓ │
│ 2. Pre-Build阶段 │
│ └── 执行 python scripts/update_version.py --fix │
│ └── 自动同步VERSION到pom.xml(revision) │
│ └── 自动更新前端package.json/pubspec.yaml │
│ └── 自动生成version.json │
│ ↓ │
│ 3. 版本合规校验（独立安全门禁） │
│ └── 执行 python scripts/version_check.py │
│ └── 检测版本格式、分支绑定、一致性、工作区清洁度 │
│ ↓ │
│ 4. 构建阶段 │
│ └── Maven使用pom.xml中的${revision} │
│ └── 子服务自动继承父pom版本 │
│ ↓ │
│ 5. 镜像/制品发布 │
│ └── 使用FULL_VERSION环境变量 │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 6 常见问题排查
| 问题 | 原因 | 解决方案 |
|-----------------------|------------------------------|-----------------------------|
| `AttributeError: '_io.TextIOWrapper' object has no attribute 'reconfigure'` | Jenkins节点Python版本为3.6，不支持reconfigure() | 脚本已添加try-except兼容处理（V1.4+） |
| 版本号不一致 | pom.xml与VERSION文件不同步 | 执行 `python scripts/update_version.py --fix` |
| 子服务版本未更新 | 子服务使用${revision}占位符，无需单独更新 | 这是正常设计，Maven自动解析 |
| 构建失败 | 版本校验脚本检测到版本不合规 | 检查分支与版本绑定规则 |
| 前端版本未同步 | 前端项目路径不存在或package.json不存在 | 检查前端项目目录结构 |
---
## 7 与旧方案(jgitver)的区别
| 对比项 | jgitver方案（未实施） | VERSION+Python方案（已实施） |
|-------------|---------------------------|------------------------|
| 依赖 | 需要Maven扩展jgitver | 仅Python脚本 |
| 配置复杂度 | 高（需要配置XML） | 低（简单的配置文件） |
| 版本控制 | 基于Git标签自动计算 | 手动修改VERSION文件 |
| 灵活性 | 低（受限于jgitver规则） | 高（完全自定义） |
| Python兼容性 | 无要求 | 需要Python 3.6+ |
| 实际使用情况 | ❌ 未实施 | ✅ 已落地实施 |
---
**维护记录**：
| 版本 | 日期 | 变更人 | 变更内容 |
|-----|-------------|-------|----------------------------------------|
| V1.4 | 2026-06-22 | 技术团队 | 更新为VERSION文件+Python脚本方案，反映实际落地实施情况 |