测试环境裸机部署设计（101.35.245.122）

日期：2026-08-06
状态：已确认设计，待写实现计划
范围：在测试机部署 web-admin + backend；不使用 Docker；中间件复用开发环境已有实例

1. 背景与目标

在测试机 101.35.245.122 的 /root/zkxw 部署一套可外网访问的测试环境：

前端：本机 pnpm build:test 后 rsync 静态产物；Nginx 对外 10001
后端：源码 rsync 到机器，用 start-test.sh 监听 127.0.0.1:10002
中间件：与本机开发一致，连接 47.99.164.66 上的 MySQL / Redis / MinIO（含库名等）
不在测试机用 Docker 跑应用或中间件

成功标准：

浏览器打开 http://101.35.245.122:10001 可使用管理端
/api 经 Nginx 反代到本机后端，健康检查与登录可用
外网无法直连 10002；附件走 MinIO 直连地址

2. 架构与流量

浏览器
  └─ http://101.35.245.122:10001
        └─ Nginx（测试机，需新装）
              ├─ /          → /root/zkxw/web-admin/dist
              ├─ /api/*     → http://127.0.0.1:10002
              └─ （不反代 MinIO）

后端（start-test.sh）
  HOST=127.0.0.1  PORT=10002
  .env.test 中间件 ≈ 本机 backend/.env
       → MySQL  47.99.164.66:3306 / zkxw-sc
       → Redis  47.99.164.66:16379 DB=8
       → MinIO  47.99.164.66:20004 bucket=zkxw

浏览器附件
  └─ 直连 http://47.99.164.66:20004/zkxw/...

约束：

云安全组 / 防火墙仅放行 TCP 10001
后端绑定 127.0.0.1，不对公网暴露 10002
前端 VITE_API_URL=/api；VITE_MINIO_BASE_URL=http://47.99.164.66:20004/zkxw

3. 服务器目录

/root/zkxw/
├── web-admin/
│   └── dist/                 # 本机 build:test 产物
├── backend/
│   ├── app/
│   ├── requirements.txt
│   ├── start-test.sh
│   ├── .env.test             # 敏感，勿提交 git
│   ├── .venv/                # 服务器用 Python 3.12.3 创建
│   ├── backend-test.pid
│   └── logs/
└── nginx/
    └── zkxw-test-10001.conf  # 仓库维护的 site 片段，部署到系统 nginx

rsync 排除：venv/、.venv/、__pycache__/、*.pyc、logs/、graphify-out/；.env* 默认不覆盖，首次单独 scp。

4. 机装依赖（实测前提）

组件	状态	动作
Python	已装 3.12.3	用 `python3.12 -m venv .venv`，无需再装 Python
Nginx	未安装	按 OS 安装、开机自启、加载 10001 site
Docker	已装但本方案不用	不启动 zkxw compose 应用栈

实现阶段须探测发行版（apt / yum / dnf）后写入准确安装命令。

5. 配置

5.1 backend `.env.test`

中间件字段与本机 backend/.env 对齐（同一 MySQL 库名、Redis DB、MinIO endpoint/bucket/密钥）
API_ENCRYPT_* 与 web-admin/.env.test 一致
启动覆盖：HOST=127.0.0.1 PORT=10002（脚本默认曾为 0.0.0.0:8112）

5.2 web-admin `.env.test`

保持 VITE_API_URL=/api、VITE_MINIO_BASE_URL=http://47.99.164.66:20004/zkxw
文档注释中的访问入口改为 http://101.35.245.122:10001

5.3 Nginx

listen 10001
root /root/zkxw/web-admin/dist；SPA try_files
location ^~ /api/ → http://127.0.0.1:10002（保留 URI）
location = /health → http://127.0.0.1:10002/health（验收固定入口）
不配置 MinIO 反代

6. 发版流程（方案：本机打包 + rsync）

6.1 首次

SSH 安装 Nginx，创建目录，放置 site，nginx -t && reload
rsync backend 源码；python3.12 -m venv .venv；pip install -r requirements.txt
scp .env.test；HOST=127.0.0.1 PORT=10002 ./start-test.sh start
本机 pnpm build:test；rsync dist/ 到服务器
安全组放行 10001；按 §7 验收

6.2 日常

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

# 后端
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'

7. 验收

检查	期望
`curl -s -o /dev/null -w '%{http_code}' http://101.35.245.122:10001/`	200
`curl -s http://101.35.245.122:10001/health`	后端健康检查成功
SSH 上 `curl -s http://127.0.0.1:10002/health`	成功
外网直连 `http://101.35.245.122:10002/health`	失败（超时/拒绝）
登录与附件预览	可用（MinIO 公网可达）

8. 风险与回滚

风险	缓解
与开发共用库 `zkxw-sc`，测试写库影响开发数据	已知接受（选型 A）；后续若需隔离再开独立库
测试机访问不到中间件端口	部署前从测试机 `curl`/连通性探测 3306、16379、20004
浏览器访问不到 MinIO	确认 `47.99.164.66:20004` 对使用方网络开放
误提交密钥 / 机器密码	`.env.test` 与账号文件不进 git

回滚：前端保留上一版 dist 备份再覆盖；后端停服务或回退代码后 restart。

9. 仓库交付物（实现阶段）

本设计文档（本文件）
Nginx site 示例：建议 测试环境部署/zkxw-test-10001.conf（或更新现有 nginx 说明）
更新 测试环境部署/README.md：新 IP、端口 10001/10002、无 Docker、Python 3.12、安装 Nginx 步骤
视需要微调 web-admin/.env.test 注释中的入口地址
不把 测试环境机器的账号密码、真实 .env.test 提交入库

10. 明确不在范围

Docker Compose / 应用镜像部署
在测试机新建 MySQL / Redis / MinIO
服务器上安装 Node 并执行 pnpm build
将后端 10002 对公网开放
Nginx 反代 MinIO

2026-08-06-test-env-bare-metal-deploy-design.md 5.9 KB Link permanente Histórico Em bruto