blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
29ce31f00efff3dae2b1b06b57fec95ff6a5e58a
railwaysystem/docs/_meta/deployment-gate-checklist.md
T

9.8 KiB
Raw Blame History

RailwaySystem 最终部署门禁与运行时验收清单 (Deployment Gate Checklist)

当前正式开发基线： integration/wave2-20260914
当前 Integration HEAD： d162954cd1e26c6948408a8304ca333ba9fe7a40
最终发布版本 HEAD 标记： FINAL_HEAD_PENDING
目标发布分支： origin/feat/cicd-pipeline
部署目标环境： 服务器别名 sict，根目录 /data2/wzb/deploy，后端 8092，前端 8082
使用说明： 本清单规范了发布前门禁、标准化部署动作序列、基于精准三态判定的运行时验收，以及基于归档制品的应急回滚方案。

一、发布前门禁 (Pre-Deployment Gates)

Gate 1: Git 版本与基线门禁

  • G1.1 分支合并状态确认：确认 origin/feat/cicd-pipeline 目前落后当前基线 2 个 commit（e2d7e63d, d162954c）。最终发版提交标注为 FINAL_HEAD_PENDING，待所有并行任务（Legacy Analytics V2 Contract 与 Business Scenario Test Pack）并入后统一核准。
  • G1.2 仓库状态审查：保持本地工作区未残留临时变更，HOLD COMMIT，未获发版审批前严禁随意提交。
  • G1.3 远端推送许可确认：严格遵守发版纪律，保持 DO NOT PUSH。

Gate 2: 数据库 Migration 分类与增量门禁

  • G2.1 目标库 Schema 版本判定：在执行部署前，首先判定目标库是否已处于 V2 基线。
    • 若目标库已是 V2 基线： 仅需且仅允许执行当前 Release Delta migration（RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql）。
    • 历史 V2 脚本隔离： 历史 V2 脚本（sql/train/v2/* 及 sql/generator/kingbase/*）已从常规发布执行清单中移除，严禁在已有 V2 库上重复执行历史备份、重建与删表操作。
  • G2.2 001_sys_oper_log_cost_time.sql 准备度：确认目标库已执行补齐 cost_time 字段；若未补齐，后端启动前必须执行（具备 IF NOT EXISTS 幂等保护）。
  • G2.3 零破坏纪律：严禁执行 007_dicts.sql (DO NOT EXECUTE)；严禁执行任何 DROP TABLE 操作。

Gate 3: CI/CD 构建与依赖门禁

  • G3.1 Kingbase JDBC 8.6.0 Preflight：
    • 依赖文件：${HOME}/.m2/repository/com/kingbase/kingbase8/8.6.0/kingbase8-8.6.0.jar
    • SHA256 强校验：346d5602477ed472b19c5e25729fff5a58b1d83cec56162a56ac4b86d9546c32 匹配无误。
  • G3.2 后端编译与打包：mvn clean package 成功，生成 RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar。
  • G3.3 前端构建：npm run build:prod 成功，生成 build_ui/dist/。
  • G3.4 运行时安全环境变量就绪：
    • 导出 TRAIN_STUDENT_IDENTITY_ENCRYPTION_KEY
    • 导出 TRAIN_STUDENT_IDENTITY_HASH_KEY
    • 导出 SPRING_REDIS_PASSWORD

二、标准化部署执行步骤 (Deployment Steps)

步骤编号 操作名称 责任操作与说明 验证方法
DEPLOY_STEP_01 环境与凭据预检 确认目标机 sict 上 JDK 8、Maven、Nginx 可用，三大敏感环境变量已导出 执行 echo 检查变量存在且非空
DEPLOY_STEP_02 Schema 判定与 Delta 补丁 判定目标库当前 Schema 版本。若已是 V2，仅执行当前 Release Delta migration (001_sys_oper_log_cost_time.sql)；严禁重跑历史 V2 脚本 确认 sys_oper_log.cost_time 存在
DEPLOY_STEP_03 现网制品备份 备份已有后端 Jar 与前端静态文件：
cp ruoyi-admin.jar ruoyi-admin.jar.bak
cp -r frontend frontend.bak		 检查备份文件生成成功
DEPLOY_STEP_04 CI 构建物拉取/生成 运行流水线或获取当前版本产物 ruoyi-admin.jar 与 dist/ 校验产物 MD5/SHA256 与构建日志
DEPLOY_STEP_05 前端静态资源更新 清理并覆盖部署：
rm -rf /data2/wzb/deploy/frontend/*
cp -r build_ui/dist/* /data2/wzb/deploy/frontend/		 确认 frontend/index.html 存在
DEPLOY_STEP_06 后端 Jar 包发布 将新构建 Jar 拷贝到发布目录：
cp ruoyi-admin.jar /data2/wzb/deploy/backend/		 确认物理文件更新且大小正常
DEPLOY_STEP_07 执行平滑重启调度 赋予权限并调用统一调度脚本：
chmod +x deploy/restart-all.sh && bash deploy/restart-all.sh		 脚本流程不抛出语法或环境异常
DEPLOY_STEP_08 后端进程平滑切换 脚本向旧进程发送 kill -15，超时发送 kill -9；以端口 8092 启动新进程并记录 app.pid ps -ef | grep ruoyi-admin.jar 确认新 PID
DEPLOY_STEP_09 健康自检探针断言 脚本自动轮询 http://127.0.0.1:8092/captchaImage（最多 35 次，每 2s 一次），断言返回 "code":200 脚本输出 后端健康检查通过！
DEPLOY_STEP_10 前端 Nginx 平滑重载 验证 /data2/wzb/deploy/nginx/nginx.conf 语法，执行 nginx -s reload 或拉起服务 检查端口 8082 处于 LISTEN 状态

三、部署后运行时验收清单 (Runtime Verification Checklist)

审计状态规范说明：

  • VERIFIED_ON_CURRENT_HEAD: 在当前 Integration HEAD (d162954c) 上重新执行并通过验收的项；
  • PREVIOUSLY_VERIFIED_ON_PRIOR_RC: 在先前发布版本/分支上已完成真实执行验证，但当前 HEAD 尚未重新运行部署验收的项；
  • PENDING_FINAL_GATE: 等待最终集成发版门禁在完整部署后执行验收的项；
  • PENDING_CODEX: 依赖并行 Codex Agent 交付的专项模块。

1. 基础连通性与平台 API

验收编号 检验项 验证端点 / 方式 当前状态判定 状态说明
RTC-01 Backend Health GET http://127.0.0.1:8092/captchaImage PREVIOUSLY_VERIFIED_ON_PRIOR_RC 先前发布版本自检通过，当前 HEAD 待最终部署验证
RTC-02 Kingbase Connectivity 启动连接池与元数据读取 PREVIOUSLY_VERIFIED_ON_PRIOR_RC 历史实测通过，当前 HEAD 待最终部署验证
RTC-03 Redis Connectivity Captcha 缓存与 Token 存取 PREVIOUSLY_VERIFIED_ON_PRIOR_RC 历史实测通过，当前 HEAD 待最终部署验证
RTC-04 User Login POST /prod-api/login PREVIOUSLY_VERIFIED_ON_PRIOR_RC 历史实测通过，当前 HEAD 待最终部署验证
RTC-05 OperLog 耗时字段查询 GET /prod-api/monitor/operlog/list PREVIOUSLY_VERIFIED / DB_FIX_VALIDATED cost_time 补丁在测试库实测通过，当前 integration 待部署验证

2. Wave 2 业务模块核心验收 (纠正 UI 入口与 API 路由)

验收编号 业务模块 正确 UI 入口导航 对应核心 API 契约 当前状态判定
RTC-06 培训计划 (Plan) 课程管理 → 开班计划 /train/plan/* PENDING_FINAL_GATE
RTC-07 参训人员 (Enrollment) 课程管理 → 开班计划 → 参训人员 (内部Tab) POST/GET /train/plans/{planId}/enrollments... PENDING_FINAL_GATE
RTC-08 排课课表 (Scheduling) 课程管理 → 开班计划 → 排课课表 (内部Tab) /train/lessons/*
/train/plans/{planId}/timetable		 PENDING_FINAL_GATE
RTC-09 电子班牌 (Board) 设施设备 → 电子班牌 (正式路径: /train/board) /train/board/* PENDING_FINAL_GATE

3. Legacy Analytics 分析模块 (并行交付项)

验收编号 业务模块 UI 路由入口 当前状态判定 说明
RTC-10 培训总评分析 (Class Report) 教学评估 → 培训总评分析 (/analysis/report) PENDING_CODEX 等待 Codex Agent 交付 V2 契约
RTC-11 学员打卡记录 (Student Checkin) 考勤与打卡 → 学员打卡记录 (/analysis/checkin) PENDING_CODEX 等待 Codex Agent 交付 V2 契约
RTC-12 学习时长统计 (Study Duration) 学习监控 → 学习时长统计 (/analysis/duration) PENDING_CODEX 等待 Codex Agent 交付 V2 契约
RTC-13 学员画像分析 (Student Portrait) 学员画像 → 画像分析 (/portrait) PENDING_CODEX 等待 Codex Agent 交付 V2 契约

4. 综合体验与全站质量门禁

验收编号 检验项 验证内容 当前状态判定
RTC-14 Frontend Entry 8082 访问 http://192.168.139.230:8082，前端路由与静态资源无 404 PENDING_FINAL_GATE
RTC-15 全站 Network 500 = 0 完整业务端到端流转中，网络请求 500 报错数量严格为 0 PENDING_FINAL_GATE

四、回滚预案与应急处置 (Rollback Gate)

1. 触发条件

  • 部署后 /captchaImage 健康自检连续 35 次超时失败；
  • 系统日志或核心功能持续出现 HTTP 500 异常；
  • 出现严重影响主业务的未预期缺陷。

2. 执行回滚操作规范

  • 严禁通过重新执行旧 V2 脚本来进行回滚；
  • 统一使用上一个已归档制品执行回退： 
    # 1. 恢复后端稳定 Jar
cp /data2/wzb/deploy/backend/ruoyi-admin.jar.bak /data2/wzb/deploy/backend/ruoyi-admin.jar

# 2. 恢复前端稳定静态资源
rm -rf /data2/wzb/deploy/frontend/*
cp -r /data2/wzb/deploy/frontend.bak/* /data2/wzb/deploy/frontend/

# 3. 触发平滑重启脚本
bash /data2/wzb/deploy/restart-all.sh

3. 数据库 Migration 回滚安全准则

  • 001_sys_oper_log_cost_time.sql 属于**向前兼容（Backward-Compatible）**字段；
  • 旧版本后端代码在不读取该字段的情况下完全可以正常运行；
  • 回滚代码时严禁对数据库执行 ALTER TABLE ... DROP COLUMN cost_time，以避免锁表与元数据不可逆破坏。
Reference in new issue View Git Blame Copy Permalink