zkxw/测试环境部署

后端测试环境部署说明

本文档汇总测试环境相关结论与操作步骤，便于后续追查。
代码仓库路径：backend/；服务器部署目录示例：/root/zkxw-backend/backend。

---

1. 环境与脚本对照

项	测试环境	生产环境
启动脚本	backend/start-test.sh	backend/start-prod.sh
环境变量文件	.env.test	.env.production
环境变量模板	backend/.env.test.example	backend/.env.example（复制为 .env.production）
默认端口	8112	8111
默认监听	0.0.0.0	0.0.0.0
工作进程数	1	2
日志级别	debug	info
虚拟环境目录	.venv	venv
PID 文件	backend-test.pid	backend-prod.pid
运行日志	logs/backend-test.log	logs/backend-prod.log

同机部署：测试用 8112、生产用 8111，避免端口冲突；启停命令必须分开，勿混用 start-test / start-prod。

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

---

2. 服务器目录

/root/zkxw-backend/backend/
├── start-test.sh          # 测试启停
├── start-prod.sh          # 生产启停（勿与测试混用命令）
├── .env.test              # 测试配置（勿提交敏感信息到 git）
├── .env.production        # 生产配置
├── .env.test.example      # 测试配置模板
├── .venv/                 # 测试脚本默认虚拟环境
├── venv/                  # 生产脚本默认虚拟环境
├── backend-test.pid
├── backend-prod.pid
└── logs/
    ├── backend-test.log
    └── backend-prod.log

---

3. 首次部署（测试）

cd /root/zkxw-backend/backend

# 1) 测试环境变量
cp .env.test.example .env.test
# 编辑 .env.test：测试库、Redis DB、MinIO bucket、SECRET_KEY、CORS、API 加密等与前端一致

# 2) 虚拟环境与依赖（须 python3.9+，勿用系统默认 python3.6）
python3.9 -m venv .venv
./.venv/bin/pip install --upgrade pip
./.venv/bin/pip install -r requirements.txt

# 3) 赋予脚本执行权限
chmod +x start-test.sh

# 4) 启动
./start-test.sh start
./start-test.sh status
curl -s http://127.0.0.1:8112/health

健康检查与文档：

• 健康检查：http://127.0.0.1:8112/health
• Swagger：http://127.0.0.1:8112/docs

---

4. start-test.sh 命令

./start-test.sh [start|stop|restart|status|logs|activate|help]

命令	说明
start	后台启动（默认）
stop	停止
restart	重启
status	查看运行状态
logs	最近 100 行日志
activate	激活 .venv 并进入交互 shell（等价 source .venv/bin/activate）
help	帮助

激活虚拟环境

./start-test.sh activate
# 或手动：
source .venv/bin/activate

activate 会进入已激活 venv 的交互 shell，输入 exit 退出。

可选环境变量

HOST=0.0.0.0 PORT=8112 WORKERS=1 LOG_LEVEL=debug \
ENV_FILE=./.env.test VENV_DIR=./.venv ./start-test.sh start

若仍使用旧目录 venv 而非 .venv：

VENV_DIR=./venv ./start-test.sh start

若测试也必须占用 8111（需确保未启动生产实例）：

PORT=8111 ./start-test.sh start

---

5. 生产环境（对照，便于追查）

生产脚本：backend/start-prod.sh，默认端口 8111，读取 .env.production。

cd /root/zkxw-backend/backend
cp .env.example .env.production   # 按生产填写
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
chmod +x start-prod.sh
./start-prod.sh start
curl -s http://127.0.0.1:8111/health

生产命令：start / stop / restart / status / logs（无 activate 子命令）。

---

6. .env.test 配置要点

模板文件：backend/.env.test.example。

配置项	建议
DEBUG	测试可为 true
DATABASE_URL	独立测试库，勿直连生产库
SECRET_KEY	与生产区分，勿提交仓库
REDIS_DB	与生产区分 DB 编号
MINIO_BUCKET	建议独立 bucket
API_ENCRYPT_*	与测试环境前端 VITE_API_ENCRYPT_* 一致
BACKEND_CORS_ORIGINS	测试管理端 / 小程序 H5 域名（JSON 数组）
微信支付	测试可用 WXPAY_SANDBOX=true 或留空

.env.test、.env.production 含密钥，不要提交到 git。

---

7. Web 管理端（web-admin）测试打包与部署

7.1 环境拓扑

角色	地址	说明
前端 Nginx	47.121.120.79:8112	静态资源 + /api 反代
前端静态目录	/root/zkxw/dist	pnpm build:test 产物上传至此
测试后端	47.99.164.66:8112	backend/start-test.sh 启动

浏览器访问：http://47.121.120.79:8112
API 请求：http://47.121.120.79:8112/api/... → Nginx 转发 → http://47.99.164.66:8112/api/...

7.2 本地打包命令

cd web-admin

# 首次或依赖变更
pnpm install

# 测试环境打包（读取 web-admin/.env.test）
pnpm build:test

# 产物目录
ls dist/

等价命令：

pnpm exec vite build --mode test

需要类型检查后再打包：

pnpm build:typecheck --mode test   # 若需单独 typecheck，可先 vue-tsc --noEmit

7.3 上传到前端服务器

# 在 web-admin 目录执行（示例）
rsync -avz --delete dist/ root@47.121.120.79:/root/zkxw/dist/

或使用 scp：

scp -r dist/* root@47.121.120.79:/root/zkxw/dist/

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

变量	测试值	说明
VITE_BASE_URL	/	部署在 8112 根路径
VITE_API_URL	/api	同域 Nginx 反代，避免跨域
VITE_API_ENCRYPT_ENABLED	true	与后端 API_ENCRYPT_ENABLED 一致
VITE_API_ENCRYPT_FIXED_SECRET	与后端相同	须与 backend/.env.test 一致
VITE_MINIO_BASE_URL	/minio/zkxw	由 Nginx 反代 MinIO

7.5 Nginx 配置

配置文件：测试环境部署/nginx.conf（已新增 8112 的 ZKXW server 块）。

部署到服务器：

# 备份后覆盖或合并 include
nginx -t && nginx -s reload

关键配置摘要：

• listen 8112
• root /root/zkxw/dist
• location ^~ /api/ → http://47.99.164.66:8112（完整 URI 转发）
• location ^~ /minio/zkxw/ → http://47.99.164.66:20003/zkxw/（MinIO 端口按后端实际映射调整）

7.6 后端 CORS（若直连后端 API 时需要）

推荐走 Nginx 同域反代，一般无需额外 CORS。若前端改为直连 http://47.99.164.66:8112，须在 backend/.env.test 增加：

BACKEND_CORS_ORIGINS=["http://47.121.120.79:8112"]

---

8. 常见问题

API 请求地址是 47.121.120.79 而不是 47.99.164.66（正常）

测试环境使用 Nginx 同域反代，浏览器 Network 里应看到：

http://47.121.120.79:8112/api/web/auth/login-rsa-public-key

不会显示 47.99.164.66——由 Nginx 在服务端转发到后端，这是预期行为。

API 返回 504 Gateway Time-out（当前最可能问题）

已实测：http://47.121.120.79:8112/ 静态页 200，但 /api/... 返回 504，且从外网直连 47.99.164.66:8112 连接超时。

说明 Nginx 反代配置已生效，但 前端服务器连不上后端 8112，请在后端机 47.99.164.66 与网络侧排查：

① 后端服务是否已启动并监听 8112

cd /root/zkxw-backend/backend
./start-test.sh status
ss -lntp | grep 8112          # 应看到 0.0.0.0:8112
curl -s http://127.0.0.1:8112/health
curl -s http://127.0.0.1:8112/api/web/auth/login-rsa-public-key

未启动则：

cp .env.test.example .env.test   # 若尚未配置
./start-test.sh start
./start-test.sh logs

② 从前端 Nginx 服务器测试能否访问后端（关键）

在 47.121.120.79 上执行：

curl -v --connect-timeout 5 http://47.99.164.66:8112/health

• 若此处 超时/拒绝：不是前端打包问题，需放通 云安全组 / 防火墙，允许 47.121.120.79 → 47.99.164.66:8112（无需对公网全网开放 8112）。

阿里云安全组示例：入方向 TCP 8112，源 IP 47.121.120.79/32。

本机 firewalld 示例（仅允许 Nginx 服务器）：

firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="47.121.120.79/32" port port="8112" protocol="tcp" accept'
firewall-cmd --reload

③ Nginx 配置是否已 reload

nginx -t && nginx -s reload
tail -f /var/log/nginx/zkxw_admin_8112_error.log

④ 确认前端用测试包打包

须使用 pnpm build:test（读取 .env.test，VITE_API_URL=/api）。若误用 pnpm build 会走 .env.production，API 会打到生产域名。

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

cp .env.test.example .env.test
# 编辑后重试
./start-test.sh start

脚本语法错误（syntax error near unexpected token）

start-*.sh 须为 Unix 换行（LF），不能是 CRLF。在服务器上可执行：

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

测试与生产同时运行

• 端口：8112 / 8111
• PID：backend-test.pid / backend-prod.pid
• 停止测试勿执行 ./start-prod.sh stop，反之亦然。

虚拟环境未找到

python3.9 -m venv .venv
./.venv/bin/pip install --upgrade pip
./.venv/bin/pip install -r requirements.txt

Python 版本过低 / 依赖安装报 fastapi==0.109.0 找不到

现象：系统 python3 版本: 3.6，或 pip 版本 9.x，安装 fastapi 失败。

原因：系统默认 python3 为 3.6，而本项目需要 Python 3.9+。若曾用 3.6 创建过 venv/ 或 .venv/，启动脚本会误用旧环境。

处理：

cd /root/zkxw-backend/backend

# 确认可用版本
python3.9 --version

# 检查是否误设了生产 venv 目录
echo "VENV_DIR=${VENV_DIR:-<未设置>}"
unset VENV_DIR   # 若曾 export VENV_DIR=./venv，先取消

# 删除旧 venv，用 3.9 重建
rm -rf .venv venv
python3.9 -m venv .venv
./.venv/bin/pip install --upgrade pip
./.venv/bin/pip install -r requirements.txt

# 验证
./.venv/bin/python --version    # 应为 3.9.x
./.venv/bin/python -c "import uvicorn; print('ok')"

./start-test.sh start

若 shell 中曾 export VENV_DIR=./venv（生产用），测试启动前须 unset VENV_DIR 或显式指定：

VENV_DIR=./.venv ./start-test.sh start

---

9. 仓库内相关文件索引

路径	说明
backend/start-test.sh	测试环境启动脚本
backend/start-prod.sh	生产环境启动脚本
backend/.env.test.example	测试环境变量模板
backend/.env.example	通用环境变量示例
backend/app/core/config.py	ENV_FILE 加载逻辑
web-admin/.env.test	测试环境前端打包变量
web-admin/package.json	pnpm build:test
测试环境部署/nginx.conf	前端 8112 + API/MinIO 反代
AGENTS.md	开发说明中的 start-test / start-prod 命令摘要

---

10. 修订记录

日期	说明
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