zikai
9af28f41b4
死代码移除: - whiteboard_hub.py: 移除未引用的 reset_hub 单例重置函数 - tunnel_service.py: 移除未引用的 is_port_allowed (逻辑已在 sftp_server 内联) - tunnel_session_dao.py: 移除未引用的 get_active_by_port - pdf_job_dao.py: 移除未用 datetime 导入 - pdf_converter.py: 移除未用 shutil 导入 - pdf_service.py: 移除未用 PdfSubmitResponse 导入 + _do_convert 内未用 hashlib 导入 - upload_html.py: 移除未用 escape 导入 (JS 侧自有 escapeHtml) - pdf_controller.py: 移除 _resolve_cookie 内未用 cfg 局部变量 提前失败/分层修复: - database.py init_db_schema: 建表后用 inspector 校验既有表列与模型一致, 缺列即抛 RuntimeError (fail-fast on schema drift), 避免运行期才暴露 - whiteboard_dao.get_or_create: 仅 IntegrityError 才回滚重读, 其他异常向上抛 (原 except Exception 会掩盖 schema/连接等真实故障) - pdf_service.admin_delete/_safe_delete_file: 改用 PdfJobDAO.delete / UploadedFileDAO.delete, 不再直接操作 job_dao.db / file_dao.db (修复分层契约: DAO 头注释声明 service 不直接操作 session) - PdfJobDAO 新增 delete(job) 方法 日志补全 (8 处 silent catch): - whiteboard_hub.py disconnect/close_board 关闭 ws: logger.debug - whiteboard_controller _safe_send/_safe_close: logger.debug - sftp_server _close_tunnel_dao/读用户名: logger.debug - sftp_server validate_public_key: logger.warning (auth 路径, 避免静默失败) 文档: - 新增 docs/routes.md, docs/configuration.md, docs/error-handling.md - README.md 精简为简介/结构/外部依赖/apache2 配置/Ubuntu 安装/docs 链接
3.5 KiB
3.5 KiB
路由与访问入口
路由约定
所有 zTools2 托管的入口（页面 / 静态资源 / 健康探针 / WebSocket / REST API）统一挂在 /api/ 前缀下，只有元信息/文档例外（/、/docs、/redoc、/openapi.json）。这样反向代理与 vite dev proxy 都只需一条 /api/ 规则即可把请求转给当前环境的 zTools2，前端用同源相对路径（如 /api/pdf/jobs、/api/health）即可，与运行环境（本地 / 测试 / 生产）无关，无需区分 dev/prod 指向。
PDF 转换的用户侧 UI 由 zMainPage 的 zPDF_package 组件提供（构建期 import，非 iframe）；zTools2 仅提供
/api/pdf/jobs等 REST API 与/api/pdf-admin管理页。
页面类入口为避免与同名 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-admin、/api/wb-admin。
功能一览
| 模块 | 页面 / 接口 | 鉴权 |
|---|---|---|
| 文件上传 | POST /api/files/upload（流式）/ POST /api/files/chunk-uploads/*（分片+断点续传） |
公开 |
| 上传页 | 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 /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 转换 API | POST /api/pdf/jobs、GET /api/pdf/jobs[/{id}]、GET /api/pdf/jobs/{id}/download、DELETE /api/pdf/jobs/{id} |
公开（cookie） |
| 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 |
访问入口
| 入口 | URL |
|---|---|
| API 文档 | https://f.zikai.wang/docs（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 转换 | 经 zMainPage 的 PDF 页签（zPDF_package 组件）调用 /api/pdf/jobs 等 REST API（公开，凭 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 |