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

将 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 新增「路由约定」说明。
2026-07-27 15:42:47 +08:00
parent 729c77e98b
commit ff2ad3fcb3
13 changed files with 75 additions and 60 deletions
--- 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
 </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` |
--- 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:
    """白板实时协作端点（文本记事本）。

--- 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 转换管理页（需鉴权）",
--- a/static/file_browser.html
+++ b/static/file_browser.html
@@ -4,8 +4,8 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>文件浏览 - zikai</title>
-<link rel="stylesheet" href="/static/common.css">
-<link rel="stylesheet" href="/static/file_browser.css">
+<link rel="stylesheet" href="/api/static/common.css">
+<link rel="stylesheet" href="/api/static/file_browser.css">
 </head>
 <body>
 <div class="wrap">
@@ -39,9 +39,9 @@

  <div id="pager" class="pager hidden"></div>

-  <p class="foot"><a class="link" href="/upload">上传文件</a> · zikai file service</p>
+  <p class="foot"><a class="link" href="/api/upload">上传文件</a> · zikai file service</p>
 </div>
-<script src="/static/common.js"></script>
-<script src="/static/file_browser.js"></script>
+<script src="/api/static/common.js"></script>
+<script src="/api/static/file_browser.js"></script>
 </body>
 </html>
--- a/static/file_browser.js
+++ b/static/file_browser.js
@@ -73,7 +73,7 @@

  function render() {
    if (!state.items.length) {
-      listEl.innerHTML = '<div class="empty">还没有文件。去 <a class="link" href="/upload">上传</a> 一个吧。</div>';
+      listEl.innerHTML = '<div class="empty">还没有文件。去 <a class="link" href="/api/upload">上传</a> 一个吧。</div>';
      renderSelection();
      return;
    }
--- a/static/pdf.html
+++ b/static/pdf.html
@@ -4,8 +4,8 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>PDF 转换 - zikai</title>
-<link rel="stylesheet" href="/static/common.css">
-<link rel="stylesheet" href="/static/pdf.css">
+<link rel="stylesheet" href="/api/static/common.css">
+<link rel="stylesheet" href="/api/static/pdf.css">
 </head>
 <body>
 <div class="wrap">
@@ -38,7 +38,7 @@

  <p class="foot">zikai file service</p>
 </div>
-<script src="/static/common.js"></script>
-<script src="/static/pdf.js"></script>
+<script src="/api/static/common.js"></script>
+<script src="/api/static/pdf.js"></script>
 </body>
 </html>
--- a/static/pdf_admin.html
+++ b/static/pdf_admin.html
@@ -4,9 +4,9 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>PDF 转换管理 - zikai</title>
-<link rel="stylesheet" href="/static/common.css">
-<link rel="stylesheet" href="/static/pdf.css">
-<link rel="stylesheet" href="/static/pdf_admin.css">
+<link rel="stylesheet" href="/api/static/common.css">
+<link rel="stylesheet" href="/api/static/pdf.css">
+<link rel="stylesheet" href="/api/static/pdf_admin.css">
 </head>
 <body>
 <div class="wrap">
@@ -22,9 +22,9 @@
    <div class="skel">加载中…</div>
  </div>

-  <p class="foot"><a class="link" href="/pdf">PDF 转换页</a> · zikai file service</p>
+  <p class="foot"><a class="link" href="/api/pdf">PDF 转换页</a> · zikai file service</p>
 </div>
-<script src="/static/common.js"></script>
-<script src="/static/pdf_admin.js"></script>
+<script src="/api/static/common.js"></script>
+<script src="/api/static/pdf_admin.js"></script>
 </body>
 </html>
--- a/static/whiteboard.html
+++ b/static/whiteboard.html
@@ -8,8 +8,8 @@
     禁用 common.css 的 prefers-color-scheme: dark，保持背景与嵌入站一致 -->
 <meta name="color-scheme" content="light">
 <title>记事本 - zikai</title>
-<link rel="stylesheet" href="/static/common.css">
-<link rel="stylesheet" href="/static/whiteboard.css">
+<link rel="stylesheet" href="/api/static/common.css">
+<link rel="stylesheet" href="/api/static/whiteboard.css">
 </head>
 <body>
 <div class="wb-app">
@@ -30,7 +30,7 @@
    <div class="wb-status" id="status">连接中…</div>
  </main>
 </div>
-<script src="/static/common.js"></script>
-<script src="/static/whiteboard.js"></script>
+<script src="/api/static/common.js"></script>
+<script src="/api/static/whiteboard.js"></script>
 </body>
 </html>
--- 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() {
--- a/static/whiteboard_admin.html
+++ b/static/whiteboard_admin.html
@@ -4,8 +4,8 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>白板管理 - zikai</title>
-<link rel="stylesheet" href="/static/common.css">
-<link rel="stylesheet" href="/static/whiteboard_admin.css">
+<link rel="stylesheet" href="/api/static/common.css">
+<link rel="stylesheet" href="/api/static/whiteboard_admin.css">
 </head>
 <body>
 <div class="wrap">
@@ -22,9 +22,9 @@
    <div class="skel">加载中…</div>
  </div>

-  <p class="foot"><a class="link" href="/upload">上传文件</a> · <a class="link" href="/files">文件浏览</a> · zikai</p>
+  <p class="foot"><a class="link" href="/api/upload">上传文件</a> · <a class="link" href="/api/files-page">文件浏览</a> · zikai</p>
 </div>
-<script src="/static/common.js"></script>
-<script src="/static/whiteboard_admin.js"></script>
+<script src="/api/static/common.js"></script>
+<script src="/api/static/whiteboard_admin.js"></script>
 </body>
 </html>
--- 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)),
--- 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

--- 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"