zkxw/测试环境部署

测试环境裸机部署说明

本文档描述测试机 101.35.245.122 上的 web-admin + backend 裸机部署拓扑与日常操作。
代码仓库：web-admin/、backend/；服务器部署根目录：/root/zkxw/。

说明：旧 8112 / 双机拓扑（前端 47.121.120.79 + 后端 47.99.164.66:8112）已废弃，以本文件为准。

---

1. 环境拓扑

角色	地址
入口	https://www.chengyantek.cn（兼容 http://101.35.245.122:10001）
Nginx 静态	/root/zkxw/web-admin/dist
OA H5 静态	/root/zkxw/static/oa-h5（路径前缀 /oa-h5/）
后端	127.0.0.1:10002（仅本机）
中间件	与本机 backend/.env 相同（47.99.164.66）
MinIO	同域 /minio/zkxw → 47.99.164.66:20004/zkxw
SSL 证书	服务器 /root/zkxw/cert/www.chengyantek.cn.{pem,key}

流量路径：

浏览器 → https://www.chengyantek.cn （或 http://IP:10001）
           ├─ /          → Nginx 静态（web-admin/dist）
           ├─ /oa-h5/    → Nginx 静态（mobile-oa-h5 → /root/zkxw/static/oa-h5）
           ├─ /api/*     → 127.0.0.1:10002（本机后端）
           └─ /minio/zkxw/ → 47.99.164.66:20004/zkxw/

mobile-h5 配置示例：OA_H5_ORIGIN = 'https://www.chengyantek.cn/oa-h5'（微信 web-view 业务域名须含 www.chengyantek.cn）。 云安全组 / 防火墙仅放行 TCP 10001；后端绑定 127.0.0.1，不对公网暴露 10002。

---

2. 机装依赖

组件	状态	说明
Python	已有 3.12.3	用于创建 .venv
Nginx	需安装	对外 10001，反代 /api
中间件	远程复用	MySQL / Redis / MinIO 在 47.99.164.66

探测包管理器后安装 Nginx（示例）：

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y nginx

# RHEL/CentOS/Alma（示例）
sudo yum install -y nginx   # 或 dnf install -y nginx
sudo systemctl enable --now nginx

---

3. 服务器目录

/root/zkxw/
├── web-admin/
│   └── dist/                 # pnpm build:test 产物
├── backend/
│   ├── app/
│   ├── requirements.txt
│   ├── start-test.sh
│   ├── .env.test             # 敏感，勿提交 git
│   ├── .venv/                # Python 3.12.3 虚拟环境
│   ├── backend-test.pid
│   └── logs/
└── （Nginx site 配置见下文）

---

4. 首次部署

4.1 后端环境变量

.env.test 来源：从本机开发机 backend/.env 复制为服务器 backend/.env.test，按测试需要调整（库名、Redis DB、密钥等）。勿将含密码的文件提交 git。

# 在本机执行（示例）
scp backend/.env root@101.35.245.122:/root/zkxw/backend/.env.test

或使用模板 backend/.env.test.example 手工填写。

4.2 虚拟环境与启动

cd /root/zkxw/backend
python3.12 -m venv .venv
./.venv/bin/pip install -U pip
./.venv/bin/pip install -r requirements.txt
chmod +x start-test.sh
HOST=127.0.0.1 PORT=10002 ./start-test.sh start
./start-test.sh status
curl -s http://127.0.0.1:10002/health

start-test.sh 子命令：start / stop / restart / status / logs / activate / help。

4.3 前端静态资源

在本机构建后上传（见 §6 日常发版）。

4.4 启用 Nginx

配置文件已存在于仓库：测试环境部署/zkxw-test-10001.conf。

Ubuntu / Debian：

sudo cp 测试环境部署/zkxw-test-10001.conf /etc/nginx/sites-available/zkxw-test-10001.conf
sudo ln -sf /etc/nginx/sites-available/zkxw-test-10001.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

RHEL / CentOS / Alma：

sudo cp 测试环境部署/zkxw-test-10001.conf /etc/nginx/conf.d/zkxw-test-10001.conf
sudo nginx -t && sudo systemctl reload nginx

Nginx 关键配置摘要：

• https://www.chengyantek.cn（443 SSL）+ http 80/apex → 301 到 https://www
• 兼容 http://IP:10001
• root /root/zkxw/web-admin/dist；/api、/health → 127.0.0.1:10002
• /oa-h5/ → /root/zkxw/static/oa-h5（mobile-oa-h5，Vite base=/oa-h5/）
• /minio/zkxw/ → 47.99.164.66:20004/zkxw/（HTTPS 同域，避免混合内容）
• 证书：/root/zkxw/cert/www.chengyantek.cn.{pem,key}（来源仓库旁证书包，私钥勿提交 git；*.pem/*.key 已在 .gitignore）

云安全组须放行 TCP 80、443（10001 已通不代表 443 已开）。

静态目录在 /root/... 下时，Nginx 工作用户（如 www-data）须能穿越 /root，否则首页 500 / Permission denied：

chmod 755 /root
chmod -R a+rX /root/zkxw/web-admin

（或将静态目录放到 /var/www/zkxw 等非 /root 路径。）

4.5 更新 SSL 证书

# 本机
scp 26548929_www.chengyantek.cn_nginx/www.chengyantek.cn.pem \
    26548929_www.chengyantek.cn_nginx/www.chengyantek.cn.key \
    root@101.35.245.122:/root/zkxw/cert/
ssh root@101.35.245.122 'chmod 600 /root/zkxw/cert/* && nginx -t && systemctl reload nginx'

---

5. 脚本与环境对照

项	测试环境（本拓扑）	生产环境
启动脚本	backend/start-test.sh	backend/start-prod.sh
环境变量文件	.env.test	.env.production
监听地址	127.0.0.1:10002	0.0.0.0:8111
虚拟环境	.venv	venv
PID 文件	backend-test.pid	backend-prod.pid
运行日志	logs/backend-test.log	logs/backend-prod.log

应用通过 ENV_FILE 加载配置（见 backend/app/core/config.py），启动脚本会 export ENV_FILE 后再拉起 uvicorn。

---

6. 日常发版

6.1 推荐：一键脚本

# 仓库根目录执行（默认：web-admin + mobile-oa-h5 + 后端 rsync、重启、验收）
python3 测试环境部署/deploy_test_env.py

python3 测试环境部署/deploy_test_env.py --frontend-only   # 仅 web-admin
python3 测试环境部署/deploy_test_env.py --oa-h5-only      # 仅 mobile-oa-h5（市场部 / OA web-view）
python3 测试环境部署/deploy_test_env.py --backend-only    # 仅后端并重启
python3 测试环境部署/deploy_test_env.py --verify          # 仅验收
python3 测试环境部署/deploy_test_env.py --upload-env      # 额外上传本机 backend/.env → 远端 .env.test
python3 测试环境部署/deploy_test_env.py --pip             # 远端重新 pip install -r requirements.txt
python3 测试环境部署/deploy_test_env.py --health-timeout 90  # 重启后等待健康检查最长时间（默认 60s）

依赖本机：python3、pnpm、npm、rsync、ssh/scp；密码登录需 sshpass。
SSH 密码默认读仓库根 测试环境机器的账号密码，或环境变量 ZKXW_TEST_SSH_PASS（勿提交密码到 git）。
发版若重启了后端，会先轮询 127.0.0.1:10002/health（再确认 Nginx /health）通过后再跑验收，避免瞬时 502。
后端 start-test.sh restart 会按 PID 文件 + 端口 10002 上的本应用进程 清理旧实例，避免 PID 失效时僵尸进程占端口、健康检查打到旧代码。

6.2 手工命令（等价）

# 前端 web-admin
cd web-admin && pnpm build:test
rsync -avz --delete dist/ root@101.35.245.122:/root/zkxw/web-admin/dist/

# OA H5（市场部 / OA 表单 web-view）
cd mobile-oa-h5 && npm run build -- --mode test
rsync -avz --delete dist/ root@101.35.245.122:/root/zkxw/static/oa-h5/

# 后端
rsync -avz --exclude .venv --exclude venv --exclude '__pycache__' --exclude logs \
  backend/ root@101.35.245.122:/root/zkxw/backend/

ssh root@101.35.245.122 \
  'cd /root/zkxw/backend && HOST=127.0.0.1 PORT=10002 ./start-test.sh restart'

注意：

• 前端须使用 pnpm build:test（读取 web-admin/.env.test），勿误用 pnpm build。
• OA H5 须使用 npm run build -- --mode test（读取 mobile-oa-h5/.env.test），产物同步到 /root/zkxw/static/oa-h5。
• rsync 默认不覆盖服务器 .env.test；配置变更用脚本 --upload-env 或单独 scp。
• rsync 排除 .venv，依赖变更时用脚本 --pip 或在机器上重新 pip install -r requirements.txt。

---

7. 验收

curl -s -o /dev/null -w '%{http_code}\n' http://101.35.245.122:10001/
curl -s http://101.35.245.122:10001/health
curl -s -o /dev/null -w '%{http_code}\n' --connect-timeout 5 http://101.35.245.122:10002/health || echo '10002_closed_ok'
curl -s -o /dev/null -w '%{http_code}\n' http://101.35.245.122:10001/api/web/auth/login-rsa-public-key

预期：

• 首页与 /health 返回 200
• 外网直连 10002 不可达（输出 10002_closed_ok 或超时）
• 登录 RSA 公钥接口经 Nginx 反代返回 200

---

8. 前端环境变量（web-admin/.env.test）

变量	说明
VITE_BASE_URL	/（部署在 10001 根路径）
VITE_API_URL	/api（同域 Nginx 反代至 127.0.0.1:10002）
VITE_MINIO_BASE_URL	http://47.99.164.66:20004/zkxw（浏览器直连，不经测试机 Nginx）
VITE_API_ENCRYPT_*	与 backend/.env.test 中 API_ENCRYPT_* 一致

---

9. 常见问题

启动报「环境文件不存在」

cp .env.test.example .env.test
# 或从本机 backend/.env 复制后编辑
./start-test.sh start

API 504 / 502

在测试机上排查：

./start-test.sh status
curl -s http://127.0.0.1:10002/health
sudo nginx -t
sudo tail -f /var/log/nginx/zkxw_admin_10001_error.log

脚本语法错误（CRLF）

sed -i 's/\r$//' start-test.sh

虚拟环境未找到

python3.12 -m venv .venv
./.venv/bin/pip install -U pip
./.venv/bin/pip install -r requirements.txt

---

10. Drone CI（Gogs）— 生产 Docker 包

同机 Drone 对接 Gogs：仅 tag 触发生产 Docker 交付打包。说明见 drone/README.md。

项	地址
Gogs	http://101.35.245.122:3000
Drone UI	http://101.35.245.122:18088
流水线	仓库根 .drone.yml（git push origin <tag> 触发）
产物	/root/zkxw-releases/zkxw-docker-deploy-v1.1.0.tar.gz（镜像标签固定 v1.1.0）

服务器：/root/drone/（含 DRONE_RPC_SECRET）、/root/zkxw-releases/。

---

11. 仓库内相关文件

路径	说明
backend/start-test.sh	测试环境启动脚本
backend/.env.test.example	测试环境变量模板
web-admin/.env.test	测试环境前端打包变量
web-admin/package.json	pnpm build:test
测试环境部署/zkxw-test-10001.conf	Nginx 10001 site 配置
测试环境部署/deploy_test_env.py	日常发版一键脚本（前端打包 + rsync + 重启 + 验收）
测试环境部署/drone/	Drone compose 模板与说明
.drone.yml	CI 编译打包流水线
docs/superpowers/specs/2026-08-06-test-env-bare-metal-deploy-design.md	设计说明

---

12. 修订记录

日期	说明
2026-06-01	初版：测试脚本 start-test.sh（8112、.env.test、.venv）、activate 命令、与生产对照及部署步骤
2026-06-01	补充：web-admin 测试打包（pnpm build:test）、Nginx 8112、/root/zkxw/dist、API 反代 47.99.164.66:8112
2026-08-06	裸机部署 10001/10002 于 101.35.245.122
2026-08-06	新增 deploy_test_env.py 日常发版脚本
2026-08-10	启用 www.chengyantek.cn HTTPS（443）+ HTTP→HTTPS；MinIO 同域 /minio/zkxw
2026-10-23	新增同机 Drone CI（:18088）对接 Gogs；仓库 .drone.yml 仅编译打包
2026-10-24	Drone 改为仅 tag 打生产 Docker 包，产物 /root/zkxw-releases/