audio_codebuddy/.qoder/repowiki/zh/content/开发指南/版本管理.md

版本管理

本文引用的文件

• README.md
• DEPLOY.md
• DEPLOY_PROD.md
• AUTO_DEPLOY.md
• deploy-prod.sh
• server/webhook-deploy.py
• server/package.json
• my-uniapp-vue3/package.json
• .codebuddy/rules/harness.mdc
• FEATURE_CHECKLIST.md

目录

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

简介

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

项目结构

• 前端采用 uniapp + Vue3 + TypeScript，构建产物用于静态托管。
• 后端采用 Node.js + Koa，使用 Prisma 管理数据库迁移。
• 部署与运维脚本集中在仓库根目录与 server 目录，支持一键部署与自动部署。

• 开发流程包含功能清单、Agent 协作规则与前端检查清单，确保功能交付质量。

  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
• server/webhook-deploy.py:1-139
• DEPLOY_PROD.md:1-393
• server/package.json:1-60
• my-uniapp-vue3/package.json:1-65

章节来源

• README.md:1-168
• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393
• AUTO_DEPLOY.md:1-142
• deploy-prod.sh:1-171
• server/webhook-deploy.py:1-139
• server/package.json:1-60
• my-uniapp-vue3/package.json:1-65

核心组件

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

章节来源

• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393
• AUTO_DEPLOY.md:1-142
• deploy-prod.sh:1-171
• server/webhook-deploy.py:1-139
• .codebuddy/rules/harness.mdc:1-98
• FEATURE_CHECKLIST.md:1-150

架构总览

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

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
• server/webhook-deploy.py:1-139
• deploy-prod.sh:1-171
• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393

详细组件分析

Git 分支管理模型

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

章节来源

• .codebuddy/rules/harness.mdc:1-98

版本号规范与发布规则

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

章节来源

• server/package.json:1-60
• my-uniapp-vue3/package.json:1-65
• FEATURE_CHECKLIST.md:1-150

合并策略与代码审查

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

章节来源

• .codebuddy/rules/harness.mdc:1-98
• FEATURE_CHECKLIST.md:1-150

发布流程（打包、部署前检查、回滚）

• 版本打包
  • 前端：H5 构建产物。
  • 后端：编译产物与依赖安装。
• 部署前检查
  • 健康检查：/api/health。
  • 数据库迁移：Prisma migrate deploy。
  • Nginx 配置：宝塔面板管理，SSL 证书与代理配置。

• 回滚机制

  • 备份目录：/data/ai/audio/backup_YYYYMMDD_HHMMSS。
  • PM2：pm2 restart 与 pm2 save。

  • 一键回滚：恢复备份目录并重启服务。

    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
• DEPLOY_PROD.md:1-393
• deploy-prod.sh:1-171

章节来源

• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393
• deploy-prod.sh:1-171

持续集成/持续部署（CI/CD）

• 自动部署架构
  • Git 推送 → Gogs Webhook → 服务器 Webhook 接收器 → 自动部署脚本 → PM2 重启。
• Webhook 服务
  • Python HTTP 服务，支持签名验证与日志记录。
  • systemd 服务自启动，Nginx 反向代理转发。

• 多环境部署

  • 开发/测试/生产环境分离，配置文件与端口隔离。

  • 生产环境使用宝塔面板管理 Nginx。

    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
• server/webhook-deploy.py:1-139

章节来源

• AUTO_DEPLOY.md:1-142
• server/webhook-deploy.py:1-139

发布日志与变更管理

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

章节来源

• FEATURE_CHECKLIST.md:1-150
• server/package.json:1-60
• my-uniapp-vue3/package.json:1-65

依赖分析

• 技术栈与版本管理
  • 前端：uniapp + Vue3 + TypeScript，构建脚本由 package.json 管理。
  • 后端：Node.js + Koa，依赖与脚本由 package.json 管理。
  • 数据库：Prisma 管理迁移与客户端生成。

• 部署脚本与服务

  • deploy-prod.sh：统一打包、上传、安装、迁移与重启。
  • webhook-deploy.py：Webhook 接收与部署触发。
  • PM2：进程守护与自动重启。

  • Nginx：反向代理与静态资源服务。

    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
• server/package.json:1-60
• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393

章节来源

• my-uniapp-vue3/package.json:1-65
• server/package.json:1-60
• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393

性能考虑

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

故障排查指南

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

章节来源

• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393
• AUTO_DEPLOY.md:1-142
• server/webhook-deploy.py:1-139

结论

本版本管理文档以仓库现有部署与自动化脚本为基础，建立了从分支模型、版本号规范到发布与回滚的完整闭环。通过 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