zikai
25dbceee2d
死代码清理： - 删除未使用的 UI 组件 Card.vue / Tag.vue - 移除 app.config.js 死字段 healthTimeoutMs（×2）与 isDev() - 移除 PageShell.vue 死 prop padded（恒为默认值） - 移除 useLocale.js 死导出 isZh/pick/locale - 移除 router/index.js 不可达 try/catch，简化为直接 .map() - 移除 package.json 重复依赖 ical.js（子模块自带） - 移除 i18n 死键 common.notAvailable / common.serviceUnavailable - 移除 vite.config.js 陈旧的 /448 /449 dev proxy（z449 为构建期组件，不走该 URL） 提前失败/日志： - useI18nLazy.js switchLocale 加载语言包失败时 console.error 记录（原静默吞错） - modules/index.js 字段不全的模块跳过时 console.warn 告警（原与文档承诺不符、静默跳过） - deploy.sh 补齐 zWhiteBoard / zPDF_package 的 npm install 与子模块初始化 （均为构建期组件 import，全新检出时缺少依赖会构建失败） 文档对齐现状（无 iframe、无外部域名）： - README 改写为简洁版，修正 iframe/ical.js/子模块数量过时描述 - architecture.md 修正 requiresAlive 示例（同源 /api/health，非外部域名） 与「仅白板使用」断言（PDF 也用）；移除已删 padded prop - add-module.md 同步移除 padded、修正 requiresAlive 示例 - submodule-timeTableFix.md 修正 ical.js 归属（子模块自带，非父项目共享） - submodule-zPDF_package.md 子项目数量 3 -> 4 - 新增 submodule-zWhiteBoard.md - readme-fixes.md 记录本次勘误
152 lines
5.8 KiB
Markdown
152 lines
5.8 KiB
Markdown
# 部署指南
|
||
|
||
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 转换 API（cookie 用户）
|
||
├── /api/pdf-admin PDF 管理页（Basic Auth）
|
||
├── /api/static/pdf* 前端静态资源
|
||
└── MySQL(3306) + uploads/
|
||
```
|
||
|
||
PDF 页签 = zMainPage 构建期 import zPDF_package 的 `App.vue` 作为组件（非 iframe），经同源 fetch 调用 zTools2 的 `/api/pdf/*` REST API（**同源相对路径**，cookie 第一方生效，与环境无关）。
|
||
|
||
> **路由约定**：zTools2 所有入口（页面 / 静态 / 探针 / WS / API）统一挂在 `/api/` 下，反代与 vite proxy 只需一条 `/api/` 规则。前端组件经同源相对路径（`/api/pdf/jobs`、`/api/health` 等）调用，自动指向**当前环境**的 zTools2，无需区分 dev/prod，也不会误打到其它环境域名。详见 zTools2 README「路由约定」。
|
||
|
||
---
|
||
|
||
## 模式一：组件独立部署（开发/调试）
|
||
|
||
各组件独立运行，互不依赖部署，适合开发调试。
|
||
|
||
### 1. zTools2 后端独立运行
|
||
|
||
```bash
|
||
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-admin（PDF 管理页）、http://127.0.0.1:6867/docs（API 文档）。
|
||
|
||
> 用户侧 PDF 页面由 zMainPage 的 zPDF_package 组件提供（构建期 import），zTools2 仅提供 `/api/pdf/*` REST API 与 `/api/pdf-admin` 管理页。
|
||
|
||
### 2. zPDF_package 前端独立运行
|
||
|
||
```bash
|
||
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 独立运行
|
||
|
||
```bash
|
||
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 页签的 zPDF_package 组件经同源相对路径 `/api/pdf/*` 调用 zTools2，经 vite proxy 转发到本地 zTools2（127.0.0.1:6867）。如需指向其它环境的 zTools2，改 `src/config/app.config.js` 的 `pdf.baseUrl` 为该环境地址（含协议与域名）后重新 `npm run dev`，或设 `VITE_API_BASE` 环境变量。
|
||
|
||
---
|
||
|
||
## 模式二：整体部署（生产，一次性）
|
||
|
||
一条命令构建并部署全部组件到生产。**前提**：zMainPage 与 zTools2 在同一主机的同级目录。
|
||
|
||
```bash
|
||
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 页签渲染 zPDF_package 组件并经同源 fetch 调用 `/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 服务
|
||
|
||
```bash
|
||
cd zTools2
|
||
./deploy/install-systemd.sh
|
||
```
|
||
|
||
脚本自动：
|
||
- 用实际路径填充 `deploy/ztools2.service` 模板（自动检测 `.venv/bin/uvicorn` 或系统 `uvicorn`）
|
||
- 写入 `/etc/systemd/system/ztools2.service`
|
||
- `systemctl enable --now ztools2`（开机自启 + 立即启动）
|
||
|
||
### 运维命令
|
||
|
||
```bash
|
||
systemctl status ztools2 # 状态
|
||
systemctl restart ztools2 # 重启（更新代码后）
|
||
systemctl stop ztools2 # 停止
|
||
journalctl -u ztools2 -f # 实时日志
|
||
```
|
||
|
||
### 卸载
|
||
|
||
```bash
|
||
sudo systemctl disable --now ztools2
|
||
sudo rm /etc/systemd/system/ztools2.service
|
||
sudo systemctl daemon-reload
|
||
```
|
||
|
||
### 与整体部署配合
|
||
|
||
生产推荐：**systemd 管理 zTools2 + deploy.sh 部署前端**。
|
||
|
||
```bash
|
||
# 首次
|
||
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）：按需对外
|