diff --git a/README.md b/README.md index 7a60cbf..8b86a89 100644 --- a/README.md +++ b/README.md @@ -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 ``` @@ -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` | diff --git a/app/controllers/whiteboard_controller.py b/app/controllers/whiteboard_controller.py index ec890ec..55424f1 100644 --- a/app/controllers/whiteboard_controller.py +++ b/app/controllers/whiteboard_controller.py @@ -86,7 +86,7 @@ async def delete_whiteboard( # ---------------- WebSocket（公开，实时同步 + 心跳） ---------------- -@router.websocket("/ws/wb/{board_id}") +@router.websocket("/api/ws/wb/{board_id}") async def whiteboard_ws(websocket: WebSocket, board_id: str) -> None: """白板实时协作端点（文本记事本）。 diff --git a/app/main.py b/app/main.py index adefa2b..78e0405 100644 --- a/app/main.py +++ b/app/main.py @@ -153,8 +153,10 @@ def create_app() -> FastAPI: app.include_router(pdf_router) # 前端静态资源（JS/CSS）；HTML 壳由下面的具名路由返回，便于各自挂 Basic Auth + # 统一 /api/ 前缀：所有 zTools2 入口（页面/静态/探针/WS/API）都在 /api/ 下， + # 反代与 vite proxy 只需一条 /api/ 规则即可转发，与环境无关 if _STATIC_DIR.is_dir(): - app.mount("/static", StaticFiles(directory=str(_STATIC_DIR)), name="static") + app.mount("/api/static", StaticFiles(directory=str(_STATIC_DIR)), name="static") # 受 Basic Auth 保护的文档接口 @app.get("/openapi.json", tags=["docs"], summary="OpenAPI 文档（需鉴权）") @@ -177,12 +179,12 @@ def create_app() -> FastAPI: def root() -> PlainTextResponse: return PlainTextResponse(f"zikai {app.version}\n") - @app.get("/health", tags=["meta"], summary="存活探针") + @app.get("/api/health", tags=["meta"], summary="存活探针") def health() -> dict: return {"status": "ok"} @app.get( - "/upload", + "/api/upload", response_class=HTMLResponse, tags=["pages"], summary="上传页面", @@ -192,7 +194,7 @@ def create_app() -> FastAPI: return HTMLResponse(render_upload_html()) @app.get( - "/files", + "/api/files-page", response_class=HTMLResponse, tags=["pages"], summary="文件浏览页（需鉴权）", @@ -202,7 +204,7 @@ def create_app() -> FastAPI: return _serve_static_html("file_browser.html") @app.get( - "/wb-admin", + "/api/wb-admin", response_class=HTMLResponse, tags=["pages"], summary="记事本管理页（需鉴权）", @@ -212,17 +214,17 @@ def create_app() -> FastAPI: return _serve_static_html("whiteboard_admin.html") @app.get( - "/wb/{board_id}", + "/api/wb-page/{board_id}", response_class=HTMLResponse, tags=["pages"], summary="记事本页面", - description="公开访问的共享文本记事本，不存在则自动新建；实时协作走 WS /ws/wb/{id}。", + description="公开访问的共享文本记事本，不存在则自动新建；实时协作走 WS /api/ws/wb/{id}。", ) def whiteboard_page(board_id: str) -> HTMLResponse: return _serve_static_html("whiteboard.html") @app.get( - "/pdf", + "/api/pdf", response_class=HTMLResponse, tags=["pages"], summary="PDF 转换页面", @@ -232,7 +234,7 @@ def create_app() -> FastAPI: return _serve_static_html("pdf.html") @app.get( - "/pdf-admin", + "/api/pdf-admin", response_class=HTMLResponse, tags=["pages"], summary="PDF 转换管理页（需鉴权）", diff --git a/static/file_browser.html b/static/file_browser.html index 9757dc4..466ab47 100644 --- a/static/file_browser.html +++ b/static/file_browser.html @@ -4,8 +4,8 @@ 文件浏览 - zikai - - + +
@@ -39,9 +39,9 @@ -

上传文件 · zikai file service

+

上传文件 · zikai file service

- - + + diff --git a/static/file_browser.js b/static/file_browser.js index 0ae065d..bf5a41e 100644 --- a/static/file_browser.js +++ b/static/file_browser.js @@ -73,7 +73,7 @@ function render() { if (!state.items.length) { - listEl.innerHTML = '
还没有文件。去 上传 一个吧。
'; + listEl.innerHTML = '
还没有文件。去 上传 一个吧。
'; renderSelection(); return; } diff --git a/static/pdf.html b/static/pdf.html index d0f0c2c..017aa82 100644 --- a/static/pdf.html +++ b/static/pdf.html @@ -4,8 +4,8 @@ PDF 转换 - zikai - - + +
@@ -38,7 +38,7 @@

zikai file service

- - + + diff --git a/static/pdf_admin.html b/static/pdf_admin.html index 9fde0d8..900d279 100644 --- a/static/pdf_admin.html +++ b/static/pdf_admin.html @@ -4,9 +4,9 @@ PDF 转换管理 - zikai - - - + + +
@@ -22,9 +22,9 @@
加载中…
-

PDF 转换页 · zikai file service

+

PDF 转换页 · zikai file service

- - + + diff --git a/static/whiteboard.html b/static/whiteboard.html index 7c0ca95..e027873 100644 --- a/static/whiteboard.html +++ b/static/whiteboard.html @@ -8,8 +8,8 @@ 禁用 common.css 的 prefers-color-scheme: dark，保持背景与嵌入站一致 --> 记事本 - zikai - - + +
@@ -30,7 +30,7 @@
连接中…
- - + + diff --git a/static/whiteboard.js b/static/whiteboard.js index ea97e64..b423358 100644 --- a/static/whiteboard.js +++ b/static/whiteboard.js @@ -8,7 +8,7 @@ const { toast, copyText } = window.ZK; // ---------- 从 URL 解析 board_id ---------- - const m = location.pathname.match(/^\/wb\/([^/]+)\/?$/); + const m = location.pathname.match(/^\/api\/wb-page\/([^/]+)\/?$/); let boardId = m ? decodeURIComponent(m[1]) : "default"; if (!/^[a-zA-Z0-9_-]{1,64}$/.test(boardId)) boardId = "default"; document.getElementById("boardId").textContent = boardId; @@ -81,7 +81,7 @@ }); copyLinkBtn.addEventListener("click", async () => { - const url = `${location.origin}/wb/${boardId}`; + const url = `${location.origin}/api/wb-page/${boardId}`; const ok = await copyText(url); toast(ok ? "链接已复制" : "复制失败"); }); @@ -143,7 +143,7 @@ // ---------- WebSocket ---------- function wsUrl() { const proto = location.protocol === "https:" ? "wss:" : "ws:"; - return `${proto}//${location.host}/ws/wb/${encodeURIComponent(boardId)}`; + return `${proto}//${location.host}/api/ws/wb/${encodeURIComponent(boardId)}`; } function connect() { diff --git a/static/whiteboard_admin.html b/static/whiteboard_admin.html index da3b7c6..bbedf82 100644 --- a/static/whiteboard_admin.html +++ b/static/whiteboard_admin.html @@ -4,8 +4,8 @@ 白板管理 - zikai - - + +
@@ -22,9 +22,9 @@
加载中…
-

上传文件 · 文件浏览 · zikai

+

上传文件 · 文件浏览 · zikai

- - + + diff --git a/static/whiteboard_admin.js b/static/whiteboard_admin.js index 4cc05fb..22477a5 100644 --- a/static/whiteboard_admin.js +++ b/static/whiteboard_admin.js @@ -11,7 +11,7 @@ newBtn.addEventListener("click", () => { // 生成一个随机 board_id 并打开（访问即创建） const id = "b_" + Math.random().toString(36).slice(2, 10); - window.open(`/wb/${id}`, "_blank"); + window.open(`/api/wb-page/${id}`, "_blank"); }); async function load() { @@ -47,7 +47,7 @@ for (const b of items) { const row = el("tr", null, el("td", { class: "col-id" }, - el("a", { class: "bid link", href: `/wb/${b.board_id}`, target: "_blank" }, b.board_id) + el("a", { class: "bid link", href: `/api/wb-page/${b.board_id}`, target: "_blank" }, b.board_id) ), el("td", { class: "col-mods mono" }, String(b.edit_count ?? 0)), el("td", { class: "col-created muted" }, fmtTime(b.created_at)), diff --git a/tests/manual_whiteboard_kick.py b/tests/manual_whiteboard_kick.py index 62531ca..aab504c 100644 --- a/tests/manual_whiteboard_kick.py +++ b/tests/manual_whiteboard_kick.py @@ -8,7 +8,7 @@ import urllib.request import websockets -BASE_WS = "ws://127.0.0.1:6867/ws/wb" +BASE_WS = "ws://127.0.0.1:6867/api/ws/wb" BOARD = "kicktest" AUTH = "Basic YTo2NjUxMTMxNQ==" # a:66511315 diff --git a/tests/manual_whiteboard_ws.py b/tests/manual_whiteboard_ws.py index 0901d22..3880d97 100644 --- a/tests/manual_whiteboard_ws.py +++ b/tests/manual_whiteboard_ws.py @@ -18,7 +18,7 @@ import urllib.request import websockets -BASE_WS = "ws://127.0.0.1:6867/ws/wb" +BASE_WS = "ws://127.0.0.1:6867/api/ws/wb" BOARD = "e2etest"