52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# 审计记录：后端依赖补全使 FastAPI 可启动
|
||
|
||
- 日期：2026-02-15（Asia/Shanghai）
|
||
- Prompt：「MCP 服务器调用 http://127.0.0.1:8000/health 时后端没跑……我要让 FastAPI 成功启动，需要怎么操作，你能帮我实现么？」
|
||
|
||
## 直接原因
|
||
|
||
`apps/backend/pyproject.toml` 的 `dependencies` 仅声明了 `neozqyy-shared`，缺少 `fastapi`、`uvicorn`、`psycopg2-binary`、`python-dotenv` 等实际运行依赖，导致 `uv run uvicorn` 无法找到这些包，后端无法启动。
|
||
|
||
修改方案：在 pyproject.toml 中补全四个运行依赖，执行 `uv sync --all-packages` 安装，使后端可正常启动并响应 `/health`。
|
||
|
||
## 修改文件清单
|
||
|
||
| 文件 | 变更类型 | 说明 |
|
||
|------|----------|------|
|
||
| `apps/backend/pyproject.toml` | 修改 | 补全 fastapi/uvicorn[standard]/psycopg2-binary/python-dotenv 依赖 |
|
||
| `apps/backend/README.md` | 重写 | 修复损坏的 markdown 代码块，更新依赖版本号和启动命令 |
|
||
|
||
## 风险点
|
||
|
||
- 依赖版本范围（>=0.115 等）较宽松，未来 breaking change 可能影响启动；建议后续考虑 pin 上限
|
||
- `uvicorn[standard]` 引入了 uvloop/httptools/websockets 等额外依赖，Windows 上 uvloop 不可用但 uvicorn 会自动降级
|
||
- 不涉及业务逻辑、数据库 schema、API 契约变更
|
||
|
||
## 回滚要点
|
||
|
||
```toml
|
||
# 回滚 pyproject.toml dependencies 为：
|
||
dependencies = [
|
||
"neozqyy-shared",
|
||
]
|
||
# 然后执行 uv sync --all-packages
|
||
```
|
||
|
||
## 验证步骤
|
||
|
||
```bash
|
||
# 1. 确认依赖安装
|
||
uv sync --all-packages
|
||
|
||
# 2. 启动后端
|
||
cd apps/backend
|
||
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||
|
||
# 3. 验证健康检查
|
||
curl http://127.0.0.1:8000/health
|
||
# 预期返回：{"status":"ok"}
|
||
|
||
# 4. 验证 OpenAPI 文档可访问
|
||
# 浏览器打开 http://127.0.0.1:8000/docs
|
||
```
|