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

feat: 所有入口统一到 /api/ 前缀

Browse Source 
将 zTools2 托管的页面/静态/探针/WebSocket 路由全部从顶级路径迁移到 /api/ 下：
- 页面：/pdf -> /api/pdf、/pdf-admin -> /api/pdf-admin、/upload -> /api/upload、
  /files -> /api/files-page、/wb/{id} -> /api/wb-page/{id}、/wb-admin -> /api/wb-admin
  （页面类加 -page 后缀以规避同名 REST API /api/files、/api/wb/{id}）
- 静态资源：/static -> /api/static
- 探针：/health -> /api/health
- WebSocket：/ws/wb/{id} -> /api/ws/wb/{id}
- 前端 HTML 壳与 JS 中的资源/页间链接/WS URL 同步更新
- 手动测试脚本 BASE_WS 同步

这样反代与 vite proxy 只需一条 /api/ 规则即可转发全部入口；
前端 iframe 用同源相对路径 /api/pdf，与环境无关，不再误打到其它环境域名。
README 新增「路由约定」说明。
This commit is contained in:
zikai
2026-07-27 15:42:47 +08:00
parent 729c77e98b
commit ff2ad3fcb3
13 changed files with 75 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
README.md
View File

@@ -8,22 +8,35 @@
| 模块 | 页面 / 接口 | 鉴权 |
|------|------------|------|
| 文件上传 | `POST /api/files/upload`（流式）/ `POST /api/files/chunk-uploads/*`（分片+断点续传） | 公开 |
| 上传页 | `GET /upload`（拖拽/多文件/分片/去重） | 公开 |
| 文件浏览 | `GET /files`（多选/批量下载删除/分页） | Basic Auth |
| 上传页 | `GET /api/upload`（拖拽/多文件/分片/去重） | 公开 |
| 文件浏览 | `GET /api/files-page`（多选/批量下载删除/分页） | Basic Auth |
| 文件管理 API | `GET /api/admin/files`、`GET/DELETE /api/admin/files/{id}`、`GET /api/admin/files/{id}/download` | Basic Auth |
| 共享记事本 | `GET /wb/{id}`（公开，不存在则新建） | 公开 |
| 记事本实时同步 | `WS /ws/wb/{id}`（心跳 3s，5 次失活移除） | 公开 |
| 记事本管理 | `GET /wb-admin`（查看/删除） | Basic Auth |
| 共享记事本 | `GET /api/wb-page/{id}`（公开，不存在则新建） | 公开 |
| 记事本实时同步 | `WS /api/ws/wb/{id}`（心跳 3s，5 次失活移除） | 公开 |
| 记事本管理 | `GET /api/wb-admin`（查看/删除） | Basic Auth |
| 记事本管理 API | `GET /api/admin/wb`、`DELETE /api/admin/wb/{id}` | Basic Auth |
| PDF 转换 | `GET /pdf`（上传 epub→PDF，进度轮询，下载；凭 cookie 记住任务） | 公开（cookie） |
| PDF 转换 | `GET /api/pdf`（上传 epub->PDF，进度轮询，下载；凭 cookie 记住任务） | 公开（cookie） |
| PDF 转换 API | `POST /api/pdf/jobs`、`GET /api/pdf/jobs[/{id}]`、`GET /api/pdf/jobs/{id}/download`、`DELETE /api/pdf/jobs/{id}` | 公开（cookie） |
| PDF 转换管理 | `GET /pdf-admin`（全部任务，含已软删标记，硬删） | Basic Auth |
| PDF 转换管理 | `GET /api/pdf-admin`（全部任务，含已软删标记，硬删） | Basic Auth |
| PDF 转换管理 API | `GET /api/admin/pdf/jobs`、`DELETE /api/admin/pdf/jobs/{id}` | Basic Auth |
| 主机监控 | `GET /api/system/status`（CPU/内存/磁盘，HTML+JSON 内容协商） | 公开 |
| 反向隧道反代 | `ALL /api/userPort/{userName}`（经 SSH 隧道转发到 user 本地服务） | 公开 |
| SFTP/SSH | 端口 2022（密码+公钥，chroot 到上传目录，承载隧道转发） | SSH |
| API 文档 | `GET /docs`（Swagger）/ `GET /redoc` | Basic Auth |
## 路由约定
**所有 zTools2 托管的入口（页面 / 静态资源 / 健康探针 / WebSocket / REST API）统一挂在 `/api/` 前缀下**，只有元信息/文档例外（`/`、`/docs`、`/redoc`、`/openapi.json`）。这样反向代理与 vite dev proxy 都只需一条 `/api/` 规则即可把请求转给当前环境的 zTools2，前端 iframe 用**同源相对路径** `/api/pdf` 即可，与运行环境（本地 / 测试 / 生产）无关，无需区分 dev/prod 指向。
页面类入口为避免与同名 REST API 冲突，统一加 `-page` 后缀：
| 类型 | 页面入口 | REST API（同名不加后缀） |
|------|---------|------------------------|
| 文件浏览 | `GET /api/files-page` | `GET /api/files`、`/api/files/{id}` 等 |
| 记事本 | `GET /api/wb-page/{id}` | `GET /api/wb/{id}` |
其余入口：`/api/health`（探针）、`/api/static/*`（JS/CSS）、`/api/ws/wb/{id}`（WebSocket）、`/api/upload`、`/api/pdf`、`/api/pdf-admin`、`/api/wb-admin`。
## 项目结构
```
@@ -124,11 +137,10 @@ a2enmod ssl proxy proxy_http proxy_wstunnel rewrite headers
ProxyPreserveHost On
ProxyPass /fdata !
# WebSocket 反代：/ws/ 必须在通用 / 规则之前，用 proxy_wstunnel 透传
ProxyPass /ws/ ws://127.0.0.1:6867/ws/
ProxyPassReverse /ws/ ws://127.0.0.1:6867/ws/
ProxyPass / http://127.0.0.1:6867/
ProxyPassReverse / http://127.0.0.1:6867/
# 所有 zTools2 入口（页面/静态/探针/WS/API）统一在 /api/ 下，一条规则即可；
# WebSocket 走 /api/ws/wb/{id}，靠 proxy_wstunnel 透传 Upgrade 头
ProxyPass /api/ http://127.0.0.1:6867/api/
ProxyPassReverse /api/ http://127.0.0.1:6867/api/
ProxyTimeout 300
</VirtualHost>
```
@@ -139,7 +151,7 @@ systemctl reload apache2
```
> **防火墙**：放开 443（HTTPS）与 2022（SFTP）。6867 不对外（仅 loopback）。
> **大文件上传**：Apache 全局 `Timeout 300`，慢链路建议走分片上传（`/upload`）或 SFTP。
> **大文件上传**：Apache 全局 `Timeout 300`，慢链路建议走分片上传（`/api/upload`）或 SFTP。
## 配置说明
@@ -153,7 +165,7 @@ systemctl reload apache2
| | `chunk_bytes` | 流式上传分片大小（默认 1 MiB） |
| | `chunk_session_dir` | 分片会话暂存目录（默认 `uploads/.work`） |
| | `chunk_session_ttl_seconds` | 被放弃会话存活秒数（默认 300） |
| `docs` | `username`/`password` | `/docs`、`/files`、`/wb-admin` 及 `/api/admin/*` 的 Basic Auth（明文，常量时间比较） |
| `docs` | `username`/`password` | `/docs`、`/api/files-page`、`/api/wb-admin`、`/api/pdf-admin` 及 `/api/admin/*` 的 Basic Auth（明文，常量时间比较） |
| `sftp` | `enabled`/`host`/`port` | SFTP 服务，默认 `0.0.0.0:2022` |
| | `users[].username`/`password_hash` | SFTP 用户（bcrypt） |
| | `host_key_path`/`authorized_keys_path` | 主机密钥与公钥白名单路径 |
@@ -169,10 +181,11 @@ systemctl reload apache2
| 入口 | URL |
|------|-----|
| API 文档 | https://f.zikai.wang/docs（Basic Auth） |
| 上传页 | https://f.zikai.wang/upload |
| 文件浏览 | https://f.zikai.wang/files（Basic Auth） |
| 共享记事本 | https://f.zikai.wang/wb/{id}（公开，`{id}` 为 `[a-zA-Z0-9_-]{1,64}`） |
| 记事本管理 | https://f.zikai.wang/wb-admin（Basic Auth） |
| 上传页 | https://f.zikai.wang/api/upload |
| 文件浏览 | https://f.zikai.wang/api/files-page（Basic Auth） |
| 共享记事本 | https://f.zikai.wang/api/wb-page/{id}（公开，`{id}` 为 `[a-zA-Z0-9_-]{1,64}`） |
| 记事本管理 | https://f.zikai.wang/api/wb-admin（Basic Auth） |
| PDF 转换 | https://f.zikai.wang/api/pdf（公开，凭 cookie） |
| 系统状态 | https://f.zikai.wang/api/system/status（HTML，`?format=json` 切 JSON） |
| curl 上传 | `curl -F file=@big.iso https://f.zikai.wang/api/files/upload` |
| SFTP | `sftp -P 2022 uploader@f.zikai.wang` |