添加Docker自包含部署分支
- 新增 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,忽略本地模型权重、构建产物、缓存和日志。
This commit is contained in:
103
doc/06-fastapi-docs-explained.md
Normal file
103
doc/06-fastapi-docs-explained.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# `/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` 验证一个接口
|
||||
|
||||
以项目列表为例:
|
||||
|
||||
1. 打开 `/docs`。
|
||||
2. 找到 `GET /api/projects`。
|
||||
3. 点开。
|
||||
4. 点击 `Try it out`。
|
||||
5. 点击 `Execute`。
|
||||
6. 查看 Response body。
|
||||
|
||||
如果这里能返回数据,但前端项目库加载失败,那问题多半在前端 API 地址、CORS、字段映射或浏览器网络请求。
|
||||
|
||||
## 另一个机器可读入口
|
||||
|
||||
OpenAPI JSON 在:
|
||||
|
||||
```text
|
||||
http://localhost:8000/openapi.json
|
||||
```
|
||||
|
||||
这是给工具读取的接口描述,Swagger UI 就是基于它渲染出来的。
|
||||
Reference in New Issue
Block a user