zMainPage/docs/deployment.md

部署指南

zPDF_package 功能涉及三个项目协同：zMainPage（父站，Vue3 静态站）、zTools2（后端 API + PDF 页面）、zPDF_package（PDF 转换前端源码，zMainPage 子模块）。提供三种部署模式，按需选用。

拓扑

浏览器 -> Apache(:80)
            ├── 静态文件 /var/www/html  （zMainPage 构建产物：主页 + 页签）
            └── 反代 /api/ -> zTools2(127.0.0.1:6867)
                        ├── /api/pdf              PDF 转换页面（iframe 嵌入源）
                        ├── /api/pdf/*            PDF 转换 API（cookie 用户）
                        ├── /api/pdf-admin        PDF 管理页（Basic Auth）
                        ├── /api/static/pdf*      前端静态资源
                        └── MySQL(3306) + uploads/

PDF 页签 = zMainPage 用 iframe 嵌入 zTools2 的 /api/pdf 页面（同源相对路径，cookie 第一方生效，与环境无关）。

路由约定：zTools2 所有入口（页面 / 静态 / 探针 / WS / API）统一挂在 /api/ 下，反代与 vite proxy 只需一条 /api/ 规则。前端 iframe 与 fetch 一律用同源相对路径（/api/pdf、/api/health 等），自动指向当前环境的 zTools2，无需区分 dev/prod，也不会误打到其它环境域名。详见 zTools2 README「路由约定」。

---

模式一：组件独立部署（开发/调试）

各组件独立运行，互不依赖部署，适合开发调试。

1. zTools2 后端独立运行

cd zTools2
./setup.sh                 # 首次：venv + 依赖 + 建库 + SFTP 密钥
./start.sh                 # 启动 HTTP(127.0.0.1:6867) + SFTP(2022)
# 或：python -m uvicorn app.main:app --host 127.0.0.1 --port 6867

访问：http://127.0.0.1:6867/api/pdf（PDF 页面）、http://127.0.0.1:6867/docs（API 文档）。

2. zPDF_package 前端独立运行

cd zPDF_package
npm install
npm run dev                # http://localhost:5175

vite.config.js 已配代理：/api 转发到 127.0.0.1:6867（需 zTools2 在跑），覆盖 /api/pdf/* 与 /api/admin/pdf/*。

3. zMainPage 独立运行

cd zMainPage
git submodule update --init --recursive   # 含 timeTableFix / z449 / zPDF_package
npm install
(cd third_party/timeTableFix && npm install)
(cd third_party/z449 && npm install)
npm run dev                # http://localhost:5173

独立模式下 PDF 页签的 iframe 用同源相对路径 /api/pdf，经 vite proxy 转发到本地 zTools2（127.0.0.1:6867）。如需指向其它环境的 zTools2，改 src/config/app.config.js 的 pdf.baseUrl 为该环境地址（含协议与域名）后重新 npm run dev，或设 VITE_API_BASE 环境变量。

---

模式二：整体部署（生产，一次性）

一条命令构建并部署全部组件到生产。前提：zMainPage 与 zTools2 在同一主机的同级目录。

cd zMainPage
./deploy.sh                 # 构建 + 部署 + 配置 Apache 反代 + 重启 zTools2
./deploy.sh --no-restart    # 仅更新文件，不重启 zTools2（如 zTools2 由 systemd 管理）

deploy.sh 做的事：

1. 构建 zMainPage（含子模块），rsync 到 /var/www/html
2. 写入 .htaccess（SPA history 回退）
3. 配置 Apache vhost（/etc/apache2/sites-available/zmainpage.conf）反代 /api/ 到 127.0.0.1:6867（含 WebSocket，靠 proxy_wstunnel 透传 /api/ws）
4. 重启 zTools2（除非 --no-restart）

部署后访问 http://localhost/ 即主页，PDF 页签 iframe 同源加载 /api/pdf。

已有 HTTPS vhost 时：deploy.sh 不会覆盖（仅首次写入）。手动在现有 vhost 加 ProxyPass /api/ http://127.0.0.1:6867/api/ 一条规则即可（需 a2enmod proxy_wstunnel 以支持 WebSocket）。

---

模式三：持久化部署（systemd，开机自启 + 崩溃重启）

zTools2 后端需长期运行（PDF 转换是异步后台任务）。用 systemd 管理实现开机自启与崩溃自动重启。

安装 systemd 服务

cd zTools2
./deploy/install-systemd.sh

脚本自动：

• 用实际路径填充 deploy/ztools2.service 模板（自动检测 .venv/bin/uvicorn 或系统 uvicorn）
• 写入 /etc/systemd/system/ztools2.service
• systemctl enable --now ztools2（开机自启 + 立即启动）

运维命令

systemctl status ztools2          # 状态
systemctl restart ztools2         # 重启（更新代码后）
systemctl stop ztools2            # 停止
journalctl -u ztools2 -f          # 实时日志

卸载

sudo systemctl disable --now ztools2
sudo rm /etc/systemd/system/ztools2.service
sudo systemctl daemon-reload

与整体部署配合

生产推荐：systemd 管理 zTools2 + deploy.sh 部署前端。

# 首次
cd zTools2 && ./setup.sh && ./deploy/install-systemd.sh   # 后端持久化
cd ../zMainPage && ./deploy.sh --no-restart                # 前端部署（不重启后端，systemd 管）
# 后续更新前端
cd zMainPage && ./deploy.sh --no-restart
# 后续更新后端代码
cd zTools2 && sudo systemctl restart ztools2

---

环境要求

项	要求
OS	Ubuntu 22.04+（systemd + apache2）
Python	≥ 3.10（本仓开发用 3.14，需 SQLAlchemy ≥ 2.0.37）
Node.js	≥ 18
MySQL	8.x
Apache	2.4（启用 proxy / proxy_http / proxy_wstunnel / rewrite / headers）
weasyprint 系统库	libpango-1.0-0 / libpangoft2-1.0-0 / libcairo2 / libgdk-pixbuf-2.0-0

防火墙

• 80（HTTP）/ 443（HTTPS）：对外
• 6867：仅 loopback（经 Apache 反代，不对外）
• 2022（SFTP）：按需对外