229 行
8.7 KiB
Markdown
229 行
8.7 KiB
Markdown
# hyb-oa 试运行 Runbook（单机）
|
||
|
||
> 目标：按本文档在一台新机器完成 **启动 → 迁移 → 初始化管理员 → 验收 → 备份 → 恢复 → 回滚** 演练。
|
||
|
||
## 0. 前置条件
|
||
- Docker + Docker Compose（v2）
|
||
- 机器时间正确（影响 token / cron / OCR）
|
||
|
||
## 1. 首次启动（推荐：单域托管）
|
||
|
||
### 1.1 准备环境变量
|
||
```bash
|
||
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 启动数据库与服务
|
||
```bash
|
||
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）：
|
||
```bash
|
||
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 进程（推荐在试运行/多进程模式使用）：
|
||
```bash
|
||
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 + 试运行管理员）
|
||
```bash
|
||
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 验收
|
||
```bash
|
||
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 备份
|
||
```bash
|
||
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：
|
||
```bash
|
||
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
|
||
```
|
||
|
||
2) 恢复 DB：
|
||
```bash
|
||
set -a
|
||
source deploy/trialrun/.env
|
||
set +a
|
||
|
||
./scripts/restore-db.sh deploy/trialrun/backups/<hyb-oa-db-*.dump>
|
||
```
|
||
|
||
3) 恢复文件存储：
|
||
```bash
|
||
./scripts/restore-storage.sh deploy/trialrun/backups/<hyb-oa-storage-*.tar.gz> deploy/trialrun/data/storage
|
||
```
|
||
|
||
4) 重启并验收：
|
||
```bash
|
||
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) 构建并重启：
|
||
```bash
|
||
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 仅回滚代码
|
||
```bash
|
||
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) 停止服务：
|
||
```bash
|
||
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
|
||
```
|
||
2) 按 E14 恢复 DB + 文件存储备份
|
||
3) 启动服务并验收 `/ready` 与登录
|
||
|
||
## 4. 日志与排障
|
||
- server 容器日志：
|
||
```bash
|
||
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` 填写每周结论与阻塞。
|
||
- 若连续两周无人使用某入口，考虑继续降级模块可见性。
|