refactor: 白板路由改 /wb 前缀,消除 HTML 与 REST 同路径冲突

问题:GET /whiteboard/{board_id} 同时被 REST(返回 JSON)与 main.py 的 HTML 页面
注册,FastAPI 按注册顺序匹配到 REST,导致浏览器访问拿到 JSON 而非前端页面。

改为按职责分命名空间,避免冲突:
- HTML 页面:/wb/{id}(main.py)、/wb-admin(main.py,Basic Auth)
- 公开 REST:GET /api/wb/{id}(前端 init 拉取初始笔画)
- WS:/ws/wb/{id}(实时同步 + 心跳)
- 管理 REST:GET /api/admin/wb、DELETE /api/admin/wb/{id}(Basic Auth)

前端 whiteboard.js / whiteboard_admin.js、测试脚本、README 路径同步更新。
旧 /whiteboard/* 路径不再注册(404)。
This commit is contained in:
zikai
2026-07-21 14:51:33 +00:00
parent 3284269399
commit 7188c62d3a
7 changed files with 44 additions and 41 deletions

View File

@@ -15,10 +15,10 @@
- **文件浏览页** `GET /files`Basic Auth同 docs列出/下载/**硬删除**已上传文件;删除后不再显示。
管理 API`GET /api/admin/files``GET /api/admin/files/{id}``GET /api/admin/files/{id}/download`
`DELETE /api/admin/files/{id}`(均 Basic Auth
- **共享白板** `GET /whiteboard/{id}`公开不存在则新建Canvas 实时协作 + **清空 / 复制链接**,兼容移动端。
实时同步走 `WS /ws/whiteboard/{id}`**心跳 3s连续 5 次丢失判失活并移除**)。
- **白板管理页** `GET /whiteboard-admin`Basic Auth同 docs查看创建时间/修改次数/上次修改时间/删除。
管理 API`GET /api/admin/whiteboards``DELETE /api/admin/whiteboards/{id}`(均 Basic Auth
- **共享白板** `GET /wb/{id}`公开不存在则新建Canvas 实时协作 + **清空 / 复制链接**,兼容移动端。
实时同步走 `WS /ws/wb/{id}`**心跳 3s连续 5 次丢失判失活并移除**)。
- **白板管理页** `GET /wb-admin`Basic Auth同 docs查看创建时间/修改次数/上次修改时间/删除。
管理 API`GET /api/admin/wb``DELETE /api/admin/wb/{id}`(均 Basic Auth
- **反向隧道反代**`ALL /api/userPort/{userName}` -- 把请求经 SSH 反向隧道转发到该 user 的本机服务。
- **内置 SFTP/SSH 服务器**asyncssh支持 **密码 + 公钥** 鉴权,同时承载 SFTP 文件暂存与反向隧道。
- `/docs`Swagger UI`/redoc` - 交互式文档,自动列出所有 API。
@@ -70,8 +70,8 @@ cd /root/zikai
| API 文档ReDoc | https://f.zikai.wang/redoc同样鉴权 |
| 上传页(拖拽、分片、断点续传) | https://f.zikai.wang/upload |
| 文件浏览页(列出/下载/删除) | https://f.zikai.wang/files **Basic Auth同 docs** |
| 共享白板(实时协作) | https://f.zikai.wang/whiteboard/{id}(公开,`{id}``[a-zA-Z0-9_-]{1,64}`,不存在则新建) |
| 白板管理页 | https://f.zikai.wang/whiteboard-admin **Basic Auth同 docs** |
| 共享白板(实时协作) | https://f.zikai.wang/wb/{id}(公开,`{id}``[a-zA-Z0-9_-]{1,64}`,不存在则新建) |
| 白板管理页 | https://f.zikai.wang/wb-admin **Basic Auth同 docs** |
| 上传curl | `curl -F file=@big.iso https://f.zikai.wang/api/files/upload` |
| SFTP | `sftp -P 2022 uploader@f.zikai.wang` |
@@ -170,13 +170,13 @@ SSH 服务器2022同时承载 SFTP 文件暂存与反向隧道。隧道 us
## 共享白板
白板无鉴权,任何人凭 `/whiteboard/{id}` 即可访问并实时协作;`{id}` 须匹配
白板无鉴权,任何人凭 `/wb/{id}` 即可访问并实时协作;`{id}` 须匹配
`[a-zA-Z0-9_-]{1,64}`,非法返回 400。访问不存在的 id 自动新建空板。白板长期留存
(存 MySQL `whiteboard` 表),进程重启后内容仍在。
### 实时同步与心跳
- 连接:`WS /ws/whiteboard/{id}`公开。JSON 文本帧协议:
- 连接:`WS /ws/wb/{id}`公开。JSON 文本帧协议:
- client -> server`{"type":"hello","client_id":"..."}`(首帧,可选)、
`{"type":"ping"}`(心跳)、`{"type":"stroke","stroke":{points,color,width}}``{"type":"clear"}`
- server -> client`{"type":"init","strokes":[...],"stroke_count":n}``{"type":"pong"}`
@@ -195,10 +195,10 @@ SSH 服务器2022同时承载 SFTP 文件暂存与反向隧道。隧道 us
### 白板管理
- `GET /whiteboard-admin`Basic Auth同 docs渲染 `static/whiteboard_admin.html`
- `GET /wb-admin`Basic Auth同 docs渲染 `static/whiteboard_admin.html`
- 管理 API均 Basic Auth
- `GET /api/admin/whiteboards?limit=&offset=` -> `{total, items:[{board_id, stroke_count, created_at, updated_at}]}`
- `DELETE /api/admin/whiteboards/{id}` -> 删 DB 行 + 关闭该 board 所有在线 WS 连接。
- `GET /api/admin/wb?limit=&offset=` -> `{total, items:[{board_id, stroke_count, created_at, updated_at}]}`
- `DELETE /api/admin/wb/{id}` -> 删 DB 行 + 关闭该 board 所有在线 WS 连接。
## 临时文件清理