admin
b5413066a0
- 新增 Seg_Server_Docker 自包含部署内容，包含前后端、FastAPI、Celery、PostgreSQL、Redis、MinIO、演示视频和 DICOM 数据。 - 保留 demo 数据以支持恢复演示出厂设置，排除 SAM 2.1 .pt 权重并在 README 中补充下载命令。 - 补充 GPU 部署、backend/worker 镜像复用、frpc/frps + NPM 公网域名反代部署说明。 - 在 .env/.env.example 中用 # XXXX 标注局域网和公网域名部署需要修改的配置项。 - 添加部署分支 .gitignore，忽略本地模型权重、构建产物、缓存和日志。
3.2 KiB
3.2 KiB
/docs 是什么
地址：
- 本机：
http://localhost:8000/docs - 局域网：
http://192.168.3.11:8000/docs
这个页面不是文件列表，也不是项目文档目录。它是 FastAPI 自动生成的 Swagger UI，用来展示和调试后端 HTTP API。
为什么会自动出现
FastAPI 会根据代码里的路由和 Pydantic schema 自动生成 OpenAPI 描述，然后用 Swagger UI 展示出来。
相关代码在：
backend/main.py创建FastAPI(...)backend/routers/*.py定义@router.get(...)、@router.post(...)等接口backend/schemas.py定义请求体和响应体
页面上 GET / POST / PATCH / DELETE 是什么
这些是 HTTP 方法，不是文件。
| 方法 | 含义 | 例子 |
|---|---|---|
| GET | 读取数据 | GET /api/projects 获取项目列表 |
| POST | 创建或触发动作 | POST /api/media/upload 上传文件 |
| PATCH | 局部更新 | PATCH /api/templates/{template_id} 更新模板 |
| DELETE | 删除 | DELETE /api/projects/{project_id} 删除项目 |
你看到的每一行，都是后端暴露给前端调用的一个接口。
/docs 能做什么
可以：
- 查看后端目前有哪些接口。
- 展开接口查看参数、请求体和响应格式。
- 点击
Try it out直接发请求测试后端。 - 检查接口返回错误，比如 400、401、404、500。
不能：
- 查看前端页面源码。
- 直接代表某个功能已经完整可用。
- 展示 WebSocket 的完整交互，因为 OpenAPI 主要描述 HTTP 接口。
和前端有什么关系
前端的 src/lib/api.ts 会调用这些接口。例如：
- 登录页调用
/api/auth/login - 项目库调用
/api/projects - 上传视频调用
/api/media/upload - 拆帧调用
/api/media/parse - 模板库调用
/api/templates
所以 /docs 是检查“后端提供了什么”的地方；前端是否真的用对了，还要对照 src/lib/api.ts。
目前通过 /docs 能看到的接口
当前后端接口包括：
- Auth：登录
- Projects：项目 CRUD、项目帧 CRUD
- Templates：模板 CRUD
- Media：上传视频/DICOM、触发拆帧
- AI：当前启用 SAM 2 推理、模型状态、自动分割、保存标注；SAM 3 源码保留但产品入口禁用
- Export：导出 COCO JSON、导出 PNG masks
- Health：健康检查
为什么看起来像“列举文件和请求”
因为 Swagger UI 默认按接口分组，把每个 endpoint 展开成一行。它列举的是“后端可被调用的功能入口”，不是项目文件。
真正的项目文件在本地目录里，例如：
- 前端：
src/components/*.tsx - 后端路由：
backend/routers/*.py - 后端模型：
backend/models.py
如何用 /docs 验证一个接口
以项目列表为例：
- 打开
/docs。 - 找到
GET /api/projects。 - 点开。
- 点击
Try it out。 - 点击
Execute。 - 查看 Response body。
如果这里能返回数据，但前端项目库加载失败，那问题多半在前端 API 地址、CORS、字段映射或浏览器网络请求。
另一个机器可读入口
OpenAPI JSON 在：
http://localhost:8000/openapi.json
这是给工具读取的接口描述，Swagger UI 就是基于它渲染出来的。