wangsli
55924c8ff8
- 新增 worker 进程入口（npm run worker）只跑作业不监听端口 - trialrun compose 增加 worker profile（server 可 JOBS_ENABLED=false） - 更新 runbook/.env.example/README 说明与 v3 CSV 状态推进
150 行
4.5 KiB
Markdown
150 行
4.5 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 进程会强制跑作业）
|
||
|
||
### 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
|
||
```
|
||
|
||
可选：启用 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
|
||
```
|
||
|
||
浏览器访问：
|
||
- `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 连接
|
||
- 超时会强制退出（避免卡死导致升级失败）。
|