zikai/zMainPage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 配置简化为同源相对路径，统一 /api/ 路由约定

Browse Source 
配合 zTools2 路由统一到 /api/，简化环境感知配置：
- app.config.js：去掉 BASE_URL 的 dev/prod 分支，iframe 与探针一律用同源相对路径
  （/api/pdf、/api/health、/api/wb-page/{id}），默认空 baseUrl；保留 VITE_API_BASE 覆盖。
  这样无论 dev（vite proxy）还是任意部署环境（反代），同源相对路径都自动指向当前环境 zTools2，
  不再误打到 f.zikai.wang 等其它环境域名。
- vite.config.js：dev proxy 从 /api /pdf /health /static /upload /files /wb /ws 多条
  简化为单条 /api（含 ws:true，覆盖 /api/ws WebSocket）。
- deploy.sh：Apache vhost 从多条 ProxyPass 简化为单条 /api/，a2enmod 增加 proxy_wstunnel。
- docs/deployment.md：更新拓扑/模式说明，新增路由约定（所有入口在 /api/ 下，反代只需一条规则）。
- 同步更新 zPDF_package 子模块指针（其 vite proxy 亦简化为单条 /api）。
This commit is contained in:
zikai
2026-07-27 15:44:49 +08:00
parent 39f3056099
commit 304ebc9448
5 changed files with 43 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/deployment.md
View File

@@ -7,15 +7,17 @@ zPDF_package 功能涉及三个项目协同：**zMainPage**（父站，Vue3 静
```
浏览器 -> Apache(:80)
├── 静态文件 /var/www/html （zMainPage 构建产物：主页 + 页签）
└── 反代 -> zTools2(127.0.0.1:6867)
├── /api/pdf/* PDF 转换 API（cookie 用户）
├── /pdf PDF 转换页面（iframe 嵌入源）
├── /pdf-admin PDF 管理页（Basic Auth）
├── /static/pdf* 前端静态资源
└── 反代 /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 的 `/pdf` 页面（同源，cookie 第一方生效）。
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「路由约定」。
---
@@ -32,7 +34,7 @@ cd zTools2
# 或：python -m uvicorn app.main:app --host 127.0.0.1 --port 6867
```
访问：http://127.0.0.1:6867/pdf（PDF 页面）、http://127.0.0.1:6867/docs（API 文档）。
访问：http://127.0.0.1:6867/api/pdf（PDF 页面）、http://127.0.0.1:6867/docs（API 文档）。
### 2. zPDF_package 前端独立运行
@@ -42,7 +44,7 @@ npm install
npm run dev # http://localhost:5175
```
`vite.config.js` 已配代理：`/api/pdf/*` 与 `/api/admin/pdf/*` 转发到 `127.0.0.1:6867`（需 zTools2 在跑）。
`vite.config.js` 已配代理：`/api` 转发到 `127.0.0.1:6867`（需 zTools2 在跑），覆盖 `/api/pdf/*` 与 `/api/admin/pdf/*`。
### 3. zMainPage 独立运行
@@ -55,7 +57,7 @@ npm install
npm run dev # http://localhost:5173
```
> 独立模式下 PDF 页签的 iframe 指向 `https://f.zikai.wang/pdf`（线上），如需指向本地 zTools2，改 `src/config/app.config.js` 的 `pdf.baseUrl` 为 `http://127.0.0.1:6867` 后重新 `npm run dev`。
> 独立模式下 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` 环境变量。
---
@@ -72,12 +74,12 @@ cd zMainPage
`deploy.sh` 做的事：
1. 构建 zMainPage（含子模块），rsync 到 `/var/www/html`
2. 写入 `.htaccess`（SPA history 回退）
3. 配置 Apache vhost（`/etc/apache2/sites-available/zmainpage.conf`）反代 `/api` `/pdf` `/pdf-admin` `/static` 等到 `127.0.0.1:6867`
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 同源加载 `/pdf`。
部署后访问 http://localhost/ 即主页，PDF 页签 iframe 同源加载 `/api/pdf`。
> 已有 HTTPS vhost 时：`deploy.sh` 不会覆盖（仅首次写入）。手动在现有 vhost 加 `ProxyPass /pdf http://127.0.0.1:6867/pdf` 等规则即可。
> 已有 HTTPS vhost 时：`deploy.sh` 不会覆盖（仅首次写入）。手动在现有 vhost 加 `ProxyPass /api/ http://127.0.0.1:6867/api/` 一条规则即可（需 `a2enmod proxy_wstunnel` 以支持 WebSocket）。
---
@@ -138,7 +140,7 @@ cd zTools2 && sudo systemctl restart ztools2
| Python | ≥ 3.10（本仓开发用 3.14，需 SQLAlchemy ≥ 2.0.37） |
| Node.js | ≥ 18 |
| MySQL | 8.x |
| Apache | 2.4（启用 proxy / proxy_http / rewrite / headers） |
| 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 |
## 防火墙