wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动
文件
e39e41287e6ee7209c5e727a3f9b624421a5afb5
hyb-oa/deploy/trialrun/runbook.md
T
wangsli e39e41287e feat(P25-1/P25-5/P26-1/P26-3/P24-1/P29-4): 落地内部OA够用版后端与试运行能力 
关联 Issue: P25-1, P25-2, P25-3, P25-4, P25-5, P26-1, P26-3, P24-1, P24-2, P29-1, P29-2, P29-3, P29-4
2026-03-21 18:03:20 +08:00

7.1 KiB
原始文件 Blame 文件历史

hyb-oa 试运行 Runbook（单机）

目标：按本文档在一台新机器完成 启动 → 迁移 → 初始化管理员 → 验收 → 备份 → 恢复 → 回滚 演练。

0. 前置条件

  • Docker + Docker Compose（v2）
  • 机器时间正确（影响 token / cron / OCR）

1. 首次启动（推荐：单域托管）

1.1 准备环境变量

cd /path/to/hyb-oa
cp deploy/trialrun/.env.example deploy/trialrun/.env

必须修改：

  • JWT_SECRET
  • APP_ORIGIN（建议与对外域名一致，例如 https://oa.example.com）

作业系统建议：

  • 试运行默认 JOB_DRIVER=pgboss（基于 Postgres 的队列调度，单机/多进程语义更稳）
  • 如需快速回滚作业调度：将 JOB_DRIVER 改回 cron
  • 可选 Worker 拆分（F20）：将 JOBS_ENABLED=false 并启用 --profile worker（worker 进程会强制跑作业）

存储建议：

  • 默认 STORAGE_DRIVER=local（票据文件落到 deploy/trialrun/data/storage）
  • 可选启用 MinIO（F21）：STORAGE_DRIVER=s3 并启用 --profile minio

1.2 启动数据库与服务

cd /path/to/hyb-oa
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d db
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server

可选：启用 MinIO（对象存储，F21）：

cd /path/to/hyb-oa
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env --profile minio up -d minio minio_init

可选：启用 Worker 进程（推荐在试运行/多进程模式使用）：

cd /path/to/hyb-oa
# 1) 在 deploy/trialrun/.env 中设置：JOBS_ENABLED="false"
# 2) 启用 worker profile（会额外启动 worker 容器）
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env --profile worker up -d --build server worker

1.3 初始化（迁移 + 配置 seed + 试运行管理员）

cd /path/to/hyb-oa
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init

说明：

  • init 是一次性任务：migrate:deploy + seed:config + seed:trialrun。
  • 若 TRIALRUN_ADMIN_PASSWORD 为空，seed 会生成一次性口令并输出到控制台（请立刻保存）。

1.4 验收

curl -fsS http://127.0.0.1:3000/health
curl -fsS http://127.0.0.1:3000/ready
curl -fsS http://127.0.0.1:3000/metrics | head

浏览器访问：

  • http://127.0.0.1:3000（单域托管前端）

1.5 备份与恢复演练（强烈建议至少做一次）

备份建议做到“DB + 文件存储（票据上传目录）”双份齐全。

1.5.1 备份

cd /path/to/hyb-oa
set -a
source deploy/trialrun/.env
set +a

./scripts/backup-db.sh
./scripts/backup-storage.sh

输出默认在：

  • deploy/trialrun/backups/

1.5.2 恢复（到同一台机器或新机器）

  1. 先停止 server：
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
  1. 恢复 DB：
set -a
source deploy/trialrun/.env
set +a

./scripts/restore-db.sh deploy/trialrun/backups/<hyb-oa-db-*.dump>
  1. 恢复文件存储：
./scripts/restore-storage.sh deploy/trialrun/backups/<hyb-oa-storage-*.tar.gz> deploy/trialrun/data/storage
  1. 重启并验收：
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d server
curl -fsS http://127.0.0.1:3000/ready

2. 升级流程（试运行）

建议版本化方式：

  • 每次发布打 tag，例如 trialrun-2026-02-08-01

步骤：

  1. 先做备份（见 E14 脚本）
  2. 拉取代码：git pull / git checkout <tag>
  3. 构建并重启：
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init

发布/回滚 Checklist：

  • deploy/trialrun/checklist.md

3. 回滚流程（试运行）

回滚分两类：仅回滚代码（无迁移），或需要 DB 回滚（恢复备份）。

3.1 仅回滚代码

git checkout <previous-tag>
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server

3.2 需要 DB 回滚（推荐做法）

  1. 停止服务：
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
  1. 按 E14 恢复 DB + 文件存储备份
  2. 启动服务并验收 /ready 与登录

4. 日志与排障

  • server 容器日志：
docker logs -f hyb-oa-trialrun-server
  • /ready 失败通常为 DB 不可达或连接串错误。

5. 优雅停机（E21）

说明：

  • docker compose stop server 会发送 SIGTERM，server 会尝试在 10s 内完成：
    • 停止 OCR/委派回收定时任务
    • 关闭 HTTP 监听
    • 断开 Prisma/PG 连接
  • 超时会强制退出（避免卡死导致升级失败）。

6. R12-lite 试点切换 Runbook

6.1 打开本轮功能前置条件

  • 执行 cd server && DATABASE_URL=postgresql://hyboa_user:[email protected]:5432/hyb_oa_r12?schema=public npm run seed:config，确保 R12-lite 开关与默认配置落库。
  • 在运行环境启用对应 env：BUDGET_PRECHECK_ENABLED=true、PAYMENT_BATCH_ENABLED=true、PORTAL_HOME_ENABLED=true、GLOBAL_SEARCH_ENABLED=true、ANNOUNCEMENTS_ENABLED=true、WORKFLOW_DEFINITION_ADMIN_ENABLED=true、CUTOVER_CONSOLE_ENABLED=true。
  • 登录系统后在“功能开关”页将对应开关切到 inherit 或 force_on；仅设置 env 不会自动放开 DB 中的 force_off 记录。

6.2 旧 OA 主数据导出与 dry-run

  1. 从旧 OA 导出人员、部门、预算或主数据 CSV。
  2. 进入“切换控制台”，按 employees | departments | budgets | masterdata_validation 上传 CSV 执行 dry-run。
  3. 只接受 dry_run_ok 结果进入下一步；若为 dry_run_failed，先修正列头和差异。
  4. 以 docs/migration-mapping.md 为准完成人工差异核对。

6.3 试点切换步骤

  1. 确认旧 OA 未完结事项已人工清空或冻结。
  2. 在旧 OA 宣布“新单停用时间点”。
  3. 在新系统创建 CutoverScope，粒度仅允许 department | legal_entity | domain。
  4. 按试点范围打开对应 CutoverScope，先开 portal，再按域逐步打开 expense / leave / procurement / travel / asset。
  5. 观察 Portal、待办、支付批次、AP 运营和消息深链是否正常。

6.4 验收证据

  • 保留 dry-run 结果截图或导出记录。
  • 保留切换范围配置、启停时间和操作人审计。
  • 保留回归结果：server/scripts/regression-all.sh、client npm run build、client npm run test:e2e（如环境可用）。
  • 保留试点部门首批新单在新系统流转与付款的样例单据编号。

6.5 回退步骤

  1. 在“切换控制台”关闭目标 CutoverScope。
  2. 恢复旧 OA 对应入口并重新开放新单。
  3. 若需要代码/数据回退，按本文第 3 节恢复到最近备份。
  4. 新系统中试点期间新建单据保留审计，不做 destructive 回写到旧 OA。
在新工单中引用 查看 Git Blame 复制永久链接