# 版本管理

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [DEPLOY.md](file://DEPLOY.md)
- [DEPLOY_PROD.md](file://DEPLOY_PROD.md)
- [AUTO_DEPLOY.md](file://AUTO_DEPLOY.md)
- [deploy-prod.sh](file://deploy-prod.sh)
- [server/webhook-deploy.py](file://server/webhook-deploy.py)
- [server/package.json](file://server/package.json)
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [.codebuddy/rules/harness.mdc](file://.codebuddy/rules/harness.mdc)
- [FEATURE_CHECKLIST.md](file://FEATURE_CHECKLIST.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为 AI 有声书生成平台提供系统化的版本管理文档，覆盖 Git 分支模型、版本号规范、合并策略、发布流程、CI/CD 与自动化部署、发布日志与变更管理，以及向后兼容性保障策略。文档以仓库现有部署与自动化脚本为基础，结合项目技术栈与开发流程，形成可落地的版本管理实践。

## 项目结构
- 前端采用 uniapp + Vue3 + TypeScript，构建产物用于静态托管。
- 后端采用 Node.js + Koa，使用 Prisma 管理数据库迁移。
- 部署与运维脚本集中在仓库根目录与 server 目录，支持一键部署与自动部署。
- 开发流程包含功能清单、Agent 协作规则与前端检查清单，确保功能交付质量。

```mermaid
graph TB
subgraph "前端"
FE_PKG["my-uniapp-vue3/package.json"]
FE_BUILD["H5 构建产物"]
end
subgraph "后端"
BE_PKG["server/package.json"]
BE_SRC["Koa 应用"]
PRISMA["Prisma 迁移与客户端"]
end
subgraph "部署与运维"
SH["部署脚本<br/>deploy-prod.sh"]
PY["Webhook 部署<br/>webhook-deploy.py"]
NGINX["Nginx 反向代理"]
PM2["PM2 进程管理"]
end
FE_PKG --> FE_BUILD
BE_PKG --> BE_SRC
BE_SRC --> PRISMA
FE_BUILD --> NGINX
BE_SRC --> NGINX
NGINX --> PM2
SH --> PM2
PY --> SH
```

图表来源
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)

章节来源
- [README.md:1-168](file://README.md#L1-L168)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)

## 核心组件
- 分支与版本管理
  - 采用 Git 分支模型：主分支保护、功能分支、热修复分支。
  - 版本号采用语义化版本（SemVer），发布遵循“版本标签 + 变更日志 + 回滚预案”。
- 合并策略
  - Pull Request（PR）流程：功能开发 → 代码审查 → 自动化测试 → 合并主分支 → 自动化部署。
  - 代码审查要求：覆盖率、可读性、兼容性与安全性。
- 发布流程
  - 版本打包：前端构建 + 后端编译 + 依赖安装。
  - 部署前检查：健康检查、数据库迁移、Nginx 配置校验。
  - 回滚机制：PM2 与备份目录，支持一键回滚。
- CI/CD 与自动化
  - 自动部署：Webhook 接收 → 部署脚本执行 → PM2 重启。
  - 多环境部署：开发、测试、生产环境分离，配置文件隔离。
- 发布日志与变更管理
  - 变更日志：按功能模块与版本聚合，支持快速检索。
  - 版本标签：遵循 SemVer，发布后打 Tag 并推送。

章节来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [.codebuddy/rules/harness.mdc:1-98](file://.codebuddy/rules/harness.mdc#L1-L98)
- [FEATURE_CHECKLIST.md:1-150](file://FEATURE_CHECKLIST.md#L1-L150)

## 架构总览
本项目的版本管理与发布架构由“分支模型 + 版本号 + 合并策略 + 自动化部署 + 回滚机制”组成，贯穿开发、测试、上线与运维全生命周期。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Repo as "Git 仓库"
participant CI as "CI/CD/Webhook"
participant Server as "部署服务器"
participant PM2 as "PM2 进程管理"
Dev->>Repo : 提交功能分支并发起 PR
Repo->>CI : 触发自动化测试与构建
CI-->>Dev : 测试结果与构建产物
Dev->>Repo : 代码审查通过后合并主分支
Repo->>CI : 推送主分支触发自动部署
CI->>Server : 执行部署脚本备份/安装/迁移
Server->>PM2 : 重启后端服务
PM2-->>Server : 服务就绪
Server-->>CI : 健康检查通过
CI-->>Dev : 发布完成通知
```

图表来源
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)

## 详细组件分析

### Git 分支管理模型
- 主分支保护
  - master/main 仅允许通过 PR 合并，禁止直接推送。
  - 强制代码审查与自动化测试通过。
- 功能分支策略
  - 命名规范：feature/模块名/功能描述。
  - 合并与清理：功能完成后删除分支，保留提交历史。
- 热修复分支
  - 命名规范：hotfix/修复主题。
  - 从 release/版本标签创建，修复后同时合并回 main 与 develop。

章节来源
- [.codebuddy/rules/harness.mdc:1-98](file://.codebuddy/rules/harness.mdc#L1-L98)

### 版本号规范与发布规则
- 版本号规范
  - 采用语义化版本（SemVer）：主版本.次版本.修订号。
  - 修订号：修复补丁，不破坏兼容。
  - 次版本：向下兼容的新功能。
  - 主版本：破坏性变更。
- 发布规则
  - 发布前：完成功能清单、自动化测试、前端验收检查。
  - 发布时：打 Tag → 推送 → 自动化部署 → 健康检查。
  - 发布后：更新变更日志，通知相关方。

章节来源
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [FEATURE_CHECKLIST.md:1-150](file://FEATURE_CHECKLIST.md#L1-L150)

### 合并策略与代码审查
- Pull Request 流程
  - 功能开发 → 提交 PR → 代码审查 → 自动化测试 → 合并。
- 代码审查要求
  - 功能完整性、可读性、安全性、兼容性与性能。
  - 前端页面测试：Playwright 自动化测试，禁止用 curl 替代。
- 冲突解决
  - 优先 rebase 保持线性历史；冲突时及时沟通与评审。

章节来源
- [.codebuddy/rules/harness.mdc:1-98](file://.codebuddy/rules/harness.mdc#L1-L98)
- [FEATURE_CHECKLIST.md:1-150](file://FEATURE_CHECKLIST.md#L1-L150)

### 发布流程（打包、部署前检查、回滚）
- 版本打包
  - 前端：H5 构建产物。
  - 后端：编译产物与依赖安装。
- 部署前检查
  - 健康检查：/api/health。
  - 数据库迁移：Prisma migrate deploy。
  - Nginx 配置：宝塔面板管理，SSL 证书与代理配置。
- 回滚机制
  - 备份目录：/data/ai/audio/backup_YYYYMMDD_HHMMSS。
  - PM2：pm2 restart 与 pm2 save。
  - 一键回滚：恢复备份目录并重启服务。

```mermaid
flowchart TD
Start(["开始发布"]) --> BuildFE["前端构建 H5"]
BuildFE --> BuildBE["后端编译与依赖安装"]
BuildBE --> Backup["创建备份目录"]
Backup --> Install["安装与迁移"]
Install --> Health["健康检查 /api/health"]
Health --> |通过| Restart["PM2 重启服务"]
Health --> |失败| Rollback["回滚到备份"]
Restart --> Done(["发布完成"])
Rollback --> Done
```

图表来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)

章节来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)

### 持续集成/持续部署（CI/CD）
- 自动部署架构
  - Git 推送 → Gogs Webhook → 服务器 Webhook 接收器 → 自动部署脚本 → PM2 重启。
- Webhook 服务
  - Python HTTP 服务，支持签名验证与日志记录。
  - systemd 服务自启动，Nginx 反向代理转发。
- 多环境部署
  - 开发/测试/生产环境分离，配置文件与端口隔离。
  - 生产环境使用宝塔面板管理 Nginx。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Gogs as "Gogs 仓库"
participant Nginx as "Nginx"
participant Py as "webhook-deploy.py"
participant Sh as "deploy.sh"
participant PM2 as "PM2"
Dev->>Gogs : 推送代码
Gogs->>Nginx : 触发 Webhook
Nginx->>Py : 转发请求
Py->>Sh : 执行部署脚本
Sh->>PM2 : 重启后端服务
PM2-->>Sh : 服务就绪
```

图表来源
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)

章节来源
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)

### 发布日志与变更管理
- 发布日志
  - 按版本聚合，记录新增功能、修复问题与注意事项。
  - 与 PR/Issue 关联，便于溯源。
- 变更日志生成
  - 基于 Git 提交与 PR 描述，自动生成变更摘要。
- 向后兼容性保证
  - 严格遵循 SemVer，破坏性变更提升主版本。
  - 发布前进行兼容性测试与回归验证。

章节来源
- [FEATURE_CHECKLIST.md:1-150](file://FEATURE_CHECKLIST.md#L1-L150)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)

## 依赖分析
- 技术栈与版本管理
  - 前端：uniapp + Vue3 + TypeScript，构建脚本由 package.json 管理。
  - 后端：Node.js + Koa，依赖与脚本由 package.json 管理。
  - 数据库：Prisma 管理迁移与客户端生成。
- 部署脚本与服务
  - deploy-prod.sh：统一打包、上传、安装、迁移与重启。
  - webhook-deploy.py：Webhook 接收与部署触发。
  - PM2：进程守护与自动重启。
  - Nginx：反向代理与静态资源服务。

```mermaid
graph LR
FE_PKG["my-uniapp-vue3/package.json"] --> FE_BUILD["H5 构建"]
BE_PKG["server/package.json"] --> BE_COMPILE["编译产物"]
BE_COMPILE --> PM2
FE_BUILD --> NGINX
PM2 --> NGINX
NGINX --> CLIENT["客户端访问"]
```

图表来源
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)

章节来源
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)

## 性能考虑
- 构建与部署性能
  - 前端构建产物缓存与增量构建，减少重复编译。
  - 后端编译与依赖安装在生产环境使用 --production 优化。
- 运行时性能
  - PM2 进程管理与自动重启，保障服务可用性。
  - Nginx 静态资源缓存与 SSL 加速，提升访问性能。

## 故障排查指南
- 后端无法启动
  - 检查端口占用、环境变量与日志。
  - 使用 pm2 logs server 查看错误。
- 前端无法访问
  - 检查文件权限、Nginx 配置与日志。
- 数据库连接失败
  - 检查 MySQL 服务状态与连接配置。
- Webhook 部署异常
  - 检查 webhook 服务状态、日志与签名配置。
  - 使用 curl 测试端点与日志监控。

章节来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)

## 结论
本版本管理文档以仓库现有部署与自动化脚本为基础，建立了从分支模型、版本号规范到发布与回滚的完整闭环。通过 PR 流程、代码审查与自动化测试，确保发布质量；通过 Webhook 与 PM2 实现一键部署与快速回滚，保障线上稳定性。建议在后续实践中补充 CI/CD 流水线与自动化测试覆盖率指标，持续优化发布效率与可靠性。

## 附录
- 快速参考
  - 健康检查：/api/health
  - 前端构建：npm run build:h5
  - 后端编译：npm run build
  - PM2 管理：pm2 status/restart/save/startup
  - Nginx 管理：nginx -t && systemctl reload nginx