wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 7 软件包 项目 发布 百科 活动

R79 收口公网部署与治理事实源

浏览代码
这个提交包含在：
wangsli
2026-05-05 16:36:27 +08:00
父节点 449489d2e0
当前提交 6eaee753d7
共修改 12 个文件，包含 136 行新增和 59 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
deploy/trialrun/checklist.md
+14 -10
查看文件
@@ -6,18 +6,20 @@
- [ ] 已确认官网继续走 `hyinda.com / www.hyinda.com`，OA 使用独立二级域名（建议 `oa.hyinda.com`）
- [ ] 服务器已执行 `bash deploy/trialrun/setup-server.sh`
- [ ] 已在服务器创建 OA 目录（默认 `/opt/hyb-oa-trialrun`）
- [ ] 已确认常规 SSH 用户为 `deploy`，系统配置用户为 `root`；当前不依赖 `shunli` 登录
- [ ] 已准备 `deploy/trialrun/.env`，并将 `APP_ORIGIN` 改为 OA 公网域名
- [ ] 已将 `COOKIE_SECURE` 设为 `true`
- [ ] 已确认 `deploy/trialrun/.env` 作为部署事实源，新增环境变量优先补到该文件
- [ ] 已尽量使用无引号 env 值；历史带引号值当前兼容，但建议逐步清理
- [ ] 已将 OA Nginx 配置放到 `/etc/nginx/sites-available/hyb-oa`
- [ ] 已上传 OA 域名证书到 `/etc/nginx/ssl/<oa-domain>/`
- [ ] 已执行 `nginx -t && systemctl reload nginx`
- [ ] 已将 OA `Caddyfile` 站点块配置到 `/etc/caddy/Caddyfile`
- [ ] 已确认 `oa.hyinda.com { reverse_proxy 127.0.0.1:3000 }` 生效
- [ ] 已执行 `systemctl reload caddy`
- [ ] 已从本地执行 `bash scripts/qa/run-release-gate.sh all` 或至少执行 `bash deploy/trialrun/deploy.sh`
- [ ] 已通过 `https://<oa-domain>/ready` 或首页登录完成最小探活
- [ ] 首次上线先执行系统初始化（migration + seed），不要直接导入旧库整库备份
- [ ] 若要导数据，仅准备最小主数据：部门、员工、角色、在用资产、活跃项目、合同元数据
- [ ] 不导入历史审批单、通知历史、审计日志、聊天记录和涉密正文附件
- [ ] 已确认远端部署目录 `/opt/hyb-oa-trialrun` 不是 git 工作树，发布优先走 `bash deploy/trialrun/deploy.sh`
## A. 发布前（Pre-flight）
- [ ] 确认当前版本已打 tag：`git tag -a trialrun-YYYYMMDD-NN -m "trialrun release"`
@@ -32,16 +34,18 @@
- [ ] `./scripts/backup-storage.sh`（记录输出文件名）
## B. 发布（Deploy）
- [ ] `git checkout <tag>`
- [ ] 在本地仓库切到目标版本：`git checkout <tag>`，然后执行 `bash deploy/trialrun/deploy.sh`
- [ ] 构建并启动：
- [ ] `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`
- [ ] `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`
- [ ] 探活：
- [ ] `curl -fsS http://127.0.0.1:3000/ready`
- [ ] Runtime smoke：
- [ ] `docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js`
- [ ] `docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js`
- [ ] 若 runtime smoke 报 `announcements_v1` 或 `global_search_v1` 为 `force_off`，已记录为发布阻塞，不忽略通过
- [ ] external deps smoke：
- [ ] `docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-external-deps.js`
- [ ] `docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-external-deps.js`
- [ ] 若 external deps smoke 通过，已确认通过前提不是“企微关闭 + OCR mock”误通过
- [ ] 登录验证已由 live smoke 与 release gate 覆盖；仅首次接入或第三方后台配置变更时补做人工确认
## C. 发布后（Post-check）
@@ -56,12 +60,12 @@
## D. 回滚（Rollback）
> 原则：如果涉及迁移，最快回滚通常是 “恢复备份 + 回到上个 tag”。
- [ ] 停止 server：`docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server`
- [ ] 停止 server：`docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server`
- [ ] 恢复 DB：`./scripts/restore-db.sh <db.dump>`
- [ ] 恢复存储：`./scripts/restore-storage.sh <storage.tar.gz> deploy/trialrun/data/storage`
- [ ] 回到上个版本：`git checkout <previous-tag>`
- [ ] 重启并探活：
- [ ] `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 up -d --build server`
- [ ] `curl -fsS http://127.0.0.1:3000/ready`
deploy/trialrun/deploy.sh
+2 -2
查看文件
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# ============================================================
# hyb-oa - 同机部署脚本（本地执行）
# hyb-oa - 远端单机部署脚本（本地执行，rsync 同步）
# ============================================================
set -euo pipefail
@@ -191,4 +191,4 @@ echo " 远端目录: ${REMOTE_DIR}"
echo " 环境文件: ${REMOTE_ENV_FILE}"
echo " 已自动执行：契约校验 + /ready + external deps smoke + runtime smoke"
echo " 若本地已配置 LIVE_SMOKE_*，部署后会自动补跑网页 live smoke"
echo " 请确认 Nginx 已把 OA 域名反代到 127.0.0.1:3000"
echo " 请确认 Caddy 或等效反向代理已把 OA 域名反代到 127.0.0.1:3000"
deploy/trialrun/runbook.md
+32 -19
查看文件
@@ -6,15 +6,26 @@
- 官网继续保持 `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)`。
- OA 推荐访问方式：`Caddy(443) -> 127.0.0.1:3000 -> docker-compose(server)`。
- 首次初始化时：
1. 服务器以 root 执行 `bash deploy/trialrun/setup-server.sh`
2. 手工创建 `deploy/trialrun/.env`
3. 手工放置 OA 的 Nginx 站点配置和证书
3. 手工更新 OA 的 `Caddyfile` 站点块并确认 TLS 正常
4. 本地执行 `bash scripts/qa/run-release-gate.sh all`（或至少执行 `bash deploy/trialrun/deploy.sh`）
## 0B. 当前已核实的 `118.89.77.218` 部署基线（2026-05-04）
- SSH 用户：
- 常规部署：`[email protected]`
- 系统配置：`[email protected]`
- `shunli` 当前不可免密登录
- 反向代理：`caddy` 正在运行，`oa.hyinda.com` 已反代到 `127.0.0.1:3000`
- 部署目录：`/opt/hyb-oa-trialrun`
- 远端目录当前不是 git 工作树；发布应优先从本地执行 `bash deploy/trialrun/deploy.sh`，由脚本 `rsync` 到服务器
- 远端容器编排当前实际为 `docker-compose 1.29.2`；本 runbook 命令以 `docker-compose` 为准
- 当前公网 `.env` 已确认：`APP_ORIGIN=https://oa.hyinda.com`、`COOKIE_SECURE=true`、`PUBLIC_SECURITY_HARDENING_ENABLED=true`，但 `WECOM_*` 仍为 `false`，`OCR_PROVIDER=mock`
## 0. 前置条件
- Docker + Docker Compose（v2）
- Docker + Docker Compose（v1/v2 任一可用）
- 机器时间正确（影响 token / cron / OCR）
## 1. 首次启动（推荐：单域托管）
@@ -48,14 +59,14 @@ cp deploy/trialrun/.env.example deploy/trialrun/.env
```bash
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
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
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env --profile minio up -d minio minio_init
```
可选：启用 Worker 进程（推荐在试运行/多进程模式使用）：
@@ -63,13 +74,13 @@ docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/
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
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
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init
```
说明：
@@ -84,7 +95,7 @@ docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/
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
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js
```
说明：
@@ -92,6 +103,7 @@ docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/
- 若本地存在完整 `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 形成单一放行链。
- 若再出现“数据库开了但功能被环境硬关”的情况，部署会直接失败，不再等到手工点页面才发现。
- 2026-05-04 公网只读巡检显示：`smoke-external-deps.js` 可以通过，但前提是 `WECOM_*` 未启用且 `OCR_PROVIDER=mock`；`smoke-trialrun-runtime.js` 当前会因 `announcements_v1` 为 `force_off` 失败。
浏览器访问：
- `http://127.0.0.1:3000`（单域托管前端）
@@ -116,7 +128,7 @@ set +a
### 1.5.2 恢复（到同一台机器或新机器）
1) 先停止 server：
```bash
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
```
2) 恢复 DB：
@@ -135,7 +147,7 @@ set +a
4) 重启并验收：
```bash
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d server
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
```
@@ -174,11 +186,11 @@ curl -fsS http://127.0.0.1:3000/ready
步骤：
1) 先做备份（见 E14 脚本）
2) 拉取代码：`git pull` / `git checkout <tag>`
2) 从本地仓库执行 `bash deploy/trialrun/deploy.sh`（推荐）；该脚本会把当前工作树 `rsync` 到 `/opt/hyb-oa-trialrun`，不依赖远端 `git pull`
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
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：
@@ -189,14 +201,15 @@ docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/
### 3.1 仅回滚代码
```bash
git checkout <previous-tag>
docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
# 远端目录不是 git 工作树，推荐在本地切到目标 tag 后重新执行 deploy.sh
# 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
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
```
2) 按 E14 恢复 DB + 文件存储备份
3) 启动服务并验收 `/ready` 与登录
@@ -210,7 +223,7 @@ docker logs -f hyb-oa-trialrun-server
## 5. 优雅停机（E21）
说明：
- `docker compose stop server` 会发送 `SIGTERM`，server 会尝试在 10s 内完成：
- `docker-compose stop server` 会发送 `SIGTERM`，server 会尝试在 10s 内完成：
- 停止 OCR/委派回收定时任务
- 关闭 HTTP 监听
- 断开 Prisma/PG 连接
@@ -325,7 +338,7 @@ npm run test:e2e -- tests/e2e/manual/live-invoice-ocr-batch.spec.ts
- `OPENAPI_DOCS_ENABLED=false`
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 up -d --build server
```
4. 验证浏览器和企业微信 WebView 都能正常登录、刷新 token 与退出登录。
deploy/trialrun/setup-server.sh
+18 -10
查看文件
@@ -1,14 +1,14 @@
#!/usr/bin/env bash
# ============================================================
# hyb-oa - 同机部署服务器初始化脚本（在服务器上执行）
# 适用：官网 hyb-web 已在同机运行，现新增 OA 子域名
# 适用：官网 hyb-web 已在同机运行，现新增 OA 子域名；默认使用 Caddy 做反向代理
# ============================================================
set -euo pipefail
DEPLOY_USER="${DEPLOY_USER:-deploy}"
REMOTE_DIR="${REMOTE_DIR:-/opt/hyb-oa-trialrun}"
OA_HOST="${OA_HOST:-oa.hyinda.com}"
NGINX_SITE_NAME="${NGINX_SITE_NAME:-hyb-oa}"
CADDY_CONFIG_PATH="${CADDY_CONFIG_PATH:-/etc/caddy/Caddyfile}"
need_cmd() {
command -v "$1" >/dev/null 2>&1 || {
@@ -22,11 +22,17 @@ if [[ "$(id -u)" -ne 0 ]]; then
exit 1
fi
echo ">>> 1. 安装 Docker / Compose 插件 / rsync"
echo ">>> 1. 安装 Docker / Compose 插件 / rsync / Caddy"
export DEBIAN_FRONTEND=noninteractive
apt-get update -y
apt-get install -y docker.io rsync
if apt-cache show caddy >/dev/null 2>&1; then
apt-get install -y caddy
else
echo "[WARN] 未在当前软件源找到 caddy，请后续手工安装。" >&2
fi
if apt-cache show docker-compose-plugin >/dev/null 2>&1; then
apt-get install -y docker-compose-plugin
elif apt-cache show docker-compose-v2 >/dev/null 2>&1; then
@@ -38,6 +44,10 @@ else
fi
systemctl enable docker
systemctl start docker
if systemctl list-unit-files caddy.service >/dev/null 2>&1; then
systemctl enable caddy || true
systemctl start caddy || true
fi
echo ">>> 2. 让 ${DEPLOY_USER} 可运行 Docker"
id "${DEPLOY_USER}" >/dev/null 2>&1 || {
@@ -50,13 +60,11 @@ echo ">>> 3. 创建 OA 目录"
mkdir -p "${REMOTE_DIR}/deploy/trialrun/data/postgres"
mkdir -p "${REMOTE_DIR}/deploy/trialrun/data/storage"
mkdir -p "${REMOTE_DIR}/deploy/trialrun/data/minio"
mkdir -p "/etc/nginx/ssl/${OA_HOST}"
chown -R "${DEPLOY_USER}:${DEPLOY_USER}" "${REMOTE_DIR}"
echo ">>> 4. 初始化完成，后续手工操作："
echo " 1) 把 OA Nginx 配置放到 /etc/nginx/sites-available/${NGINX_SITE_NAME}"
echo " 2) ln -sf /etc/nginx/sites-available/${NGINX_SITE_NAME} /etc/nginx/sites-enabled/${NGINX_SITE_NAME}"
echo " 3) 上传证书到 /etc/nginx/ssl/${OA_HOST}/server.crt 和 server.key"
echo " 4) 在 ${REMOTE_DIR}/deploy/trialrun/.env 写入 OA 环境变量"
echo " 5) 切换到 deploy 用户后，从本地执行 deploy/trialrun/deploy.sh"
echo " 6) 执行 nginx -t && systemctl reload nginx"
echo " 1) 在 ${CADDY_CONFIG_PATH} 增加站点块：${OA_HOST} { reverse_proxy 127.0.0.1:3000 }"
echo " 2) 执行 systemctl reload caddy"
echo " 3) 在 ${REMOTE_DIR}/deploy/trialrun/.env 写入 OA 环境变量"
echo " 4) 切换到 deploy 用户后，从本地执行 deploy/trialrun/deploy.sh"
echo " 5) 用 curl -I https://${OA_HOST}/ready 或首页访问做最小探活"