zlwu
b220298f89
为减少仓库噪声和重复规则，整理当前开发入口并移除已废弃资料。 - 精简根 AGENTS，补充四个应用规则与 README，统一规范入口 - 归整部署文件、SOP 原稿和参考资源，修正迁移后的脚本路径 - 取消虚拟环境、工具状态、业务导出及备份的跟踪，本机所需原件保留 - 移除停用的 graphify 配置、脚本与产物 - 删除历史业务文档、执行计划、OpenSpec 业务变更和移动 UI 原型 - 清理失效引用，历史细胞产品导入改为必须显式指定 --file 验证：git diff --cached --check、OpenSpec 严格校验、导入参数隔离检查 3/3 通过； 迁移文件完整性和现行链接已核对。未执行部署、业务数据导入或服务启停。
331 lines
11 KiB
Markdown
331 lines
11 KiB
Markdown
# 测试环境裸机部署说明
|
||
|
||
> 本文档描述测试机 `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}` |
|
||
|
||
流量路径：
|
||
|
||
```text
|
||
浏览器 → 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（示例）：
|
||
|
||
```bash
|
||
# 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. 服务器目录
|
||
|
||
```text
|
||
/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**。
|
||
|
||
```bash
|
||
# 在本机执行（示例）
|
||
scp backend/.env root@101.35.245.122:/root/zkxw/backend/.env.test
|
||
```
|
||
|
||
或使用模板 `backend/.env.test.example` 手工填写。
|
||
|
||
### 4.2 虚拟环境与启动
|
||
|
||
```bash
|
||
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
|
||
|
||
配置文件已存在于仓库：`deploy/test/zkxw-test-10001.conf`。
|
||
|
||
**Ubuntu / Debian：**
|
||
|
||
```bash
|
||
sudo cp deploy/test/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：**
|
||
|
||
```bash
|
||
sudo cp deploy/test/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}`（来源 `.local/deploy/test/` 下的证书包，私钥勿提交 git；`*.pem`/`*.key` 已在 `.gitignore`）
|
||
|
||
**云安全组须放行 TCP 80、443**（10001 已通不代表 443 已开）。
|
||
|
||
静态目录在 `/root/...` 下时，Nginx 工作用户（如 `www-data`）须能穿越 `/root`，否则首页 500 / Permission denied：
|
||
|
||
```bash
|
||
chmod 755 /root
|
||
chmod -R a+rX /root/zkxw/web-admin
|
||
```
|
||
|
||
（或将静态目录放到 `/var/www/zkxw` 等非 `/root` 路径。）
|
||
|
||
### 4.5 更新 SSL 证书
|
||
|
||
```bash
|
||
# 本机
|
||
scp .local/deploy/test/26548929_www.chengyantek.cn_nginx/www.chengyantek.cn.pem \
|
||
.local/deploy/test/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 推荐：一键脚本
|
||
|
||
```bash
|
||
# 仓库根目录执行（默认：web-admin + mobile-oa-h5 + 后端 rsync、重启、验收）
|
||
python3 deploy/test/deploy_test_env.py
|
||
|
||
python3 deploy/test/deploy_test_env.py --frontend-only # 仅 web-admin
|
||
python3 deploy/test/deploy_test_env.py --oa-h5-only # 仅 mobile-oa-h5（市场部 / OA web-view）
|
||
python3 deploy/test/deploy_test_env.py --backend-only # 仅后端并重启
|
||
python3 deploy/test/deploy_test_env.py --verify # 仅验收
|
||
python3 deploy/test/deploy_test_env.py --upload-env # 额外上传本机 backend/.env → 远端 .env.test
|
||
python3 deploy/test/deploy_test_env.py --pip # 远端重新 pip install -r requirements.txt
|
||
python3 deploy/test/deploy_test_env.py --health-timeout 90 # 重启后等待健康检查最长时间（默认 60s）
|
||
```
|
||
|
||
依赖本机：`python3`、`pnpm`、`npm`、`rsync`、`ssh`/`scp`；密码登录需 `sshpass`。
|
||
SSH 密码默认读仓库内 `.local/deploy/test/测试环境机器的账号密码`，或环境变量 `ZKXW_TEST_SSH_PASS`（**勿提交密码到 git**）。
|
||
发版若重启了后端，会先轮询 `127.0.0.1:10002/health`（再确认 Nginx `/health`）通过后再跑验收，避免瞬时 502。
|
||
后端 `start-test.sh restart` 会按 **PID 文件 + 端口 10002 上的本应用进程** 清理旧实例，避免 PID 失效时僵尸进程占端口、健康检查打到旧代码。
|
||
|
||
### 6.2 手工命令（等价）
|
||
|
||
```bash
|
||
# 前端 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. 验收
|
||
|
||
```bash
|
||
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. 常见问题
|
||
|
||
### 启动报「环境文件不存在」
|
||
|
||
```bash
|
||
cp .env.test.example .env.test
|
||
# 或从本机 backend/.env 复制后编辑
|
||
./start-test.sh start
|
||
```
|
||
|
||
### API 504 / 502
|
||
|
||
在测试机上排查：
|
||
|
||
```bash
|
||
./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）
|
||
|
||
```bash
|
||
sed -i 's/\r$//' start-test.sh
|
||
```
|
||
|
||
### 虚拟环境未找到
|
||
|
||
```bash
|
||
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](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` |
|
||
| `deploy/test/zkxw-test-10001.conf` | Nginx 10001 site 配置 |
|
||
| `deploy/test/deploy_test_env.py` | 日常发版一键脚本（前端打包 + rsync + 重启 + 验收） |
|
||
| `deploy/test/drone/` | Drone compose 模板与说明 |
|
||
| `.drone.yml` | CI 编译打包流水线 |
|
||
|
||
---
|
||
|
||
## 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/` |
|