feat(server): 试运行部署与运营基线（E13/E14/E17/E19/E20/E21）

- 增加 deploy/trialrun：Docker Compose + env 模板 + runbook + 发布/回滚 checklist - 新增 DB/文件存储备份恢复脚本（backup/restore） - 新增 system.users 运营接口：创建/启用禁用/重置密码/分配角色 + 审计 - 新增 seed:trialrun 引导管理员账号（一次性口令） - 补齐 SIGTERM/SIGINT 优雅停机（关闭 job/HTTP/DB）
2026-02-09 01:12:49 +08:00
@@ -0,0 +1,136 @@
+# 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`）
+
+### 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
+```
+
+### 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 连接
+- 超时会强制退出（避免卡死导致升级失败）。