wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 6 软件包 项目 发布 百科 活动
文件
a15bbcbadb89e75392eaebcb8558487c904b6d34
hyb-oa/deploy/trialrun/runbook.md
T

16 KiB
原始文件 Blame 文件历史

hyb-oa 试运行 Runbook（单机）

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

0A. 如果官网 hyb-web 已在同机运行（推荐方案）

  • 官网继续保持 hyinda.com / www.hyinda.com 静态托管，不要改官网目录和配置。
  • OA 新增独立二级域名，例如 oa.hyinda.com。
  • OA 推荐部署目录：/opt/hyb-oa-trialrun。
  • OA 推荐访问方式：Nginx(443) -> 127.0.0.1:3000 -> docker compose(server)。
  • 首次初始化时：
    1. 服务器以 root 执行 bash deploy/trialrun/setup-server.sh
    2. 手工创建 deploy/trialrun/.env
    3. 手工放置 OA 的 Nginx 站点配置和证书
    4. 本地执行 bash scripts/qa/run-release-gate.sh all（或至少执行 bash deploy/trialrun/deploy.sh）

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）

环境变量约束：

  • deploy/trialrun/.env 现在是 trialrun 部署事实源，server / worker / init 统一通过 env_file 注入。
  • 推荐使用无引号值，例如 COOKIE_SECURE=true、PORT=3000。
  • 历史上已经写成带引号的 .env 当前仍兼容，但建议后续逐步改成无引号。
  • 正式部署前可先执行 node deploy/trialrun/validate-env-contract.js 做静态契约检查。

作业系统建议：

  • 试运行默认 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
node deploy/trialrun/validate-env-contract.js
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 会生成一次性口令并输出到控制台（请立刻保存）。
  • 正式启用前，推荐先保持“空基线 + 默认种子”，不要直接导入开发库、测试库或旧 OA 整库备份。
  • 如确需导入，仅导入最小必要主数据：部门、员工、角色、在用资产、活跃项目、合同元数据。
  • 历史审批单、通知历史、审计日志、聊天记录以及涉密正文/附件继续保留在原系统、文件盘或离线档案中。

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
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js

说明：

  • deploy/trialrun/deploy.sh 现已自动执行 validate-env-contract.js、/ready 探活、smoke-external-deps.js 与 smoke-trialrun-runtime.js。
  • 若本地存在完整 LIVE_SMOKE_* 环境变量，部署脚本会继续执行 client npm run test:e2e:live，用于公网只读 smoke。
  • 推荐直接执行 bash scripts/qa/run-release-gate.sh all，让 static / local smoke / full-local / deploy / live smoke 形成单一放行链。
  • 若再出现“数据库开了但功能被环境硬关”的情况，部署会直接失败，不再等到手工点页面才发现。

浏览器访问：

  • 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

1.5.3 R66 小团队上线前演练记录

上线前至少记录一次演练结果：

  • 演练日期：
  • 执行人：
  • DB 备份文件：
  • 文件存储备份文件：
  • 恢复目标机器或目录：
  • 恢复后 /ready 结果：
  • 上个可回滚 tag：
  • 回滚负责人：

需要人工配合的事项：

  • 提供或确认真实 deploy/trialrun/.env，特别是 JWT_SECRET、APP_ORIGIN、COOKIE_SECURE、OPENAPI_DOCS_ENABLED。
  • 确认备份文件保存位置和保留周期。
  • 准备独立 smoke 账号，避免使用老板、管理员或真实员工账号跑自动化。

2. 升级流程（试运行）

建议版本化方式：

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

2.1 网页自动化门禁（R28）

发布前后统一使用三层网页自动化：

  • bash scripts/qa/run-web-gates.sh smoke-local：本地/PR 快速门禁，只覆盖登录、Portal、导航、企微入口 UI。
  • bash scripts/qa/run-web-gates.sh full-local：本地/main/夜间全量门禁，串联 server 回归、client build 与全部 Playwright E2E。
  • bash scripts/qa/run-web-gates.sh smoke-live：发布后公网只读 smoke，只检查 /ready、登录、Portal、团队、请假、项目、公告、个人设置、管理页只读入口与企微配置状态。

约束：

  • live smoke 必须使用独立账号：smoke-admin、smoke-employee。
  • live smoke 禁止新建报销、提交审批、付款、导入、资产流转、项目写操作。
  • 若本地已配置完整 LIVE_SMOKE_*，bash deploy/trialrun/deploy.sh 会在远端部署完成后自动补跑 live smoke。

步骤：

  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。

7. R17 小团队内部管理上线 Runbook

7.1 默认目标形态

  • 工作区模式：small_team_internal
  • 主导航：Portal、团队、请假、报销、资产、周报、待办、公告
  • 入口策略：账号密码主入口，站内通知主通道，桌面优先

7.2 推荐环境开关

  • 建议打开：PORTAL_HOME_ENABLED=true、GLOBAL_SEARCH_ENABLED=true、ANNOUNCEMENTS_ENABLED=true、PRESENCE_BOARD_ENABLED=true、WEEKLY_REPORT_ENABLED=true、EMPLOYEE_LIFECYCLE_ENABLED=true、TODO_BOARD_ENABLED=true
  • 建议保留备用：PAYMENT_BATCH_ENABLED=false、CUTOVER_CONSOLE_ENABLED=false
  • OCR 回归环境建议：OCR_PROVIDER=mock

7.3 上线前整理事项

  1. 补齐员工账号、部门、直属上级与员工档案。
  2. 核对资产卡片与实际领用关系。
  3. 为老板 / 管理员 / 主管 / 员工分配推荐角色预设。
  4. 在 工作区设置 确认模块显隐，收敛主导航。
  5. 准备一条公告，验证全员登录后 Portal 可见。

7.4 首周启用顺序

  1. 打开 Portal + 公告 + 团队状态
  2. 第二天开始要求全员更新今日状态
  3. 当周启用 周报 + 待办
  4. 同步启用 入职 / 离职 / 资产交接
  5. 报销和请假保持可用，但不再作为首页主叙事

7.5 4 周观测建议

  • 每周记录：
    • 周报提交人数
    • 团队状态更新人数
    • 公告阅读反馈
    • 入职/离职/资产交接演练情况
  • 建议统一使用 deploy/trialrun/observation-template.md 填写每周结论与阻塞。
  • 可执行 cd server && npm run report:small-team-observation -- --out ../deploy/trialrun/observations/week-01.md 导出当周快照，再补充人工结论。
  • 若连续两周无人使用某入口，考虑继续降级模块可见性。

R18-R22 公网 + 企微 + 项目域上线补充

A. 公网安全基线

  1. 为 OA 准备 HTTPS 域名并反向代理到 server。
  2. 在 deploy/trialrun/.env 中至少设置：
    • APP_ORIGIN=https://oa.example.com
    • COOKIE_SECURE=true
    • PUBLIC_SECURITY_HARDENING_ENABLED=true
    • OPENAPI_DOCS_ENABLED=false
  3. 重新执行：
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
  1. 验证浏览器和企业微信 WebView 都能正常登录、刷新 token 与退出登录。

B. 企业微信工作台入口

  1. 在企业微信自建应用中配置工作台地址，默认落到：https://oa.example.com/portal。
  2. 在 deploy/trialrun/.env 中补齐：
    • WECOM_ENABLED=true
    • WECOM_ENTRY_ENABLED=true
    • WECOM_CORP_ID
    • WECOM_AGENT_ID
    • WECOM_AGENT_SECRET
    • WECOM_OAUTH_ENABLED=true
    • WECOM_REDIRECT_URI=https://oa.example.com/api/auth/wecom/callback
    • WECOM_ALLOWED_RETURN_HOSTS=oa.example.com
  3. 管理员先在个人设置页完成企微绑定，再拉试点用户验证免登。
  4. 企微消息只用于提醒与打开 OA，不新增第二套录入页面。

C. 项目与合同最小导入

  1. 先整理项目台账、项目成员、里程碑、风险、合同登记 CSV。
  2. 按 docs/migration-mapping.md 的最小列准备字段。
  3. 先在测试环境做 dry-run，再在试点环境 apply。
  4. 涉密正文、附件、报价成本继续保留在内网资料库或离线档案。

D. 试点验收新增观察点

  • 企业微信进入 OA 的成功率
  • 项目任务与里程碑更新率
  • 报销 / 差旅 / 周报挂项目覆盖率
  • 是否还存在第二套项目台账或 Excel 主表
  • 企业微信通知是否发生敏感字段泄露

7. R23 试点收口准入步骤

  1. 打开以下功能开关并确认 DB 记录不是 force_off：
    • project_domain_v1
    • project_linking_v1
    • project_communication_log_v1
    • project_closure_checklist_v1
    • confidential_doc_refs_v1
    • global_search_v1
  2. 抽样创建或选择 1 个真实项目，验证：
    • 可以新增客户沟通回填
    • 项目收口清单会自动生成
    • 项目改为 completed/archived 时出现软告警而非硬阻断
  3. 抽样验证 1 条涉密合同或资料引用：
    • 敏感摘要关键字无法通过全局搜索命中
    • 合同编号或资料编号可以命中
    • 企业微信消息只发“有项目待跟进 / 有项目待收口”脱敏提醒
  4. 向全员宣导两条试点纪律：
    • 客户沟通影响项目时 24h 内回填
    • 私聊可继续发生，但项目状态不能只留在聊天里
  5. 进入真实 4 周试点前，至少保留一次通过记录：后端测试、前端 build、E2E 全绿截图或日志。

8. R29 前端设计系统与工作台体验验收

8.1 视觉与交互核对顺序

  1. 登录页：先确认当前场景只有一个主 CTA，并验证错误提示、企微回退文案可理解。
  2. Portal：确认员工与管理员两套第一屏都先回答“今天要做什么”。
  3. 导航：确认主导航 9 项稳定、管理入口独立、备用模块默认折叠。
  4. 个人设置：确认只展示员工可理解的信息，企微绑定卡状态清晰。

8.2 自动化建议

  • 本地快速验收：bash scripts/qa/run-web-gates.sh smoke-local
  • 发版前完整验收：bash scripts/qa/run-web-gates.sh full-local
  • 公网只读验收：bash scripts/qa/run-web-gates.sh smoke-live

8.3 设计 QA 口径

  • 一个场景只允许一个主 CTA。
  • 首页先动作，后报表；公告与最近访问降到第二阅读层。
  • 空状态必须给下一步建议，不只显示“暂无数据”。
  • 移动 / WebView 首屏避免横向滚动和过宽表格。
  • 状态色只表达语义，不把品牌色滥用成所有强调色。
在新工单中引用 查看 Git Blame 复制永久链接