112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
# V1 部署设计文档
|
||
|
||
## 1. 部署设计目标
|
||
|
||
V1 部署目标是降低复试现场环境风险。系统应支持本地 Python 方式启动，也支持 Docker Compose 一键启动。默认不依赖外部数据库、Redis 或任务队列。
|
||
|
||
## 2. 本地运行方式
|
||
|
||
建议命令：
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
.venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
python manage.py migrate
|
||
python manage.py runserver
|
||
```
|
||
|
||
本地运行使用 SQLite、`data/uploads` 和 `data/chroma`。
|
||
|
||
当前本地方式会在启动时自动读取根目录 `.env`，因此 `runserver`、`pytest` 和日常脚本可以共享同一套配置。
|
||
|
||
## 3. Docker 运行方式
|
||
|
||
建议命令：
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
V1 Docker Compose 只需要一个 Django Web 服务。Chroma 使用本地持久化目录，不额外启动独立服务。
|
||
|
||
## 4. 环境变量设计
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `DJANGO_SECRET_KEY` | `dev-secret-key` | 开发密钥 |
|
||
| `DJANGO_DEBUG` | `true` | 是否开启调试 |
|
||
| `DJANGO_ALLOWED_HOSTS` | `*` | 允许主机 |
|
||
| `LLM_API_KEY` | 空 | 大模型 API Key |
|
||
| `LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容接口地址，可接入 OpenAI、硅基流动等兼容服务 |
|
||
| `LLM_MODEL` | `gpt-4.1-mini` | 默认模型 |
|
||
| `EMBEDDING_API_KEY` | 空 | Embedding API Key；为空时可复用 `LLM_API_KEY` |
|
||
| `EMBEDDING_BASE_URL` | 空 | Embedding OpenAI 兼容接口地址；为空时可复用 `LLM_BASE_URL` |
|
||
| `EMBEDDING_MODEL` | `text-embedding-3-small` | 默认 Embedding 模型 |
|
||
| `SCENARIO_CONFIG_DIR` | `configs` | 场景配置目录 |
|
||
| `UPLOAD_ROOT` | `data/uploads` | 上传目录 |
|
||
| `CHROMA_PATH` | `data/chroma` | 向量库目录 |
|
||
|
||
`.env.example` 应提供这些变量的样例，不写真实密钥。
|
||
|
||
当前实现说明：
|
||
|
||
- 本地 Python 方式启动时，会先加载根目录 `.env`，再读取进程环境中的覆盖值。
|
||
- Docker Compose 方式可通过 `env_file` 向容器注入环境变量；当前仓库默认读取 `.env`。
|
||
- 因此本地运行和容器运行可以默认共用一份 `.env`，但演示前仍应确认密钥和模型参数是否正确。
|
||
|
||
## 5. 目录挂载设计
|
||
|
||
Docker 需要持久化以下目录：
|
||
|
||
```text
|
||
./data/db.sqlite3
|
||
./data/uploads
|
||
./data/chroma
|
||
./configs
|
||
```
|
||
|
||
`configs` 挂载后可以在不重建镜像的情况下修改场景配置。
|
||
|
||
## 6. SQLite 数据持久化
|
||
|
||
SQLite 文件放在 `data/db.sqlite3`。Docker 中应将 `data/` 作为 volume 挂载，避免容器重建后数据丢失。
|
||
|
||
## 7. Chroma 数据持久化
|
||
|
||
Chroma 数据放在 `data/chroma`。RAG 入库后，重启容器不应丢失向量数据。
|
||
|
||
## 8. 上传文件持久化
|
||
|
||
上传文件放在 `data/uploads/<scenario_id>/`。数据库只保存相对路径或 Django FileField 路径。
|
||
|
||
## 9. 启动命令设计
|
||
|
||
Docker 容器启动时建议执行：
|
||
|
||
```bash
|
||
python manage.py migrate
|
||
python manage.py runserver 0.0.0.0:8000
|
||
```
|
||
|
||
V1 可以先用开发服务器满足演示。后续正式部署可切换到 Gunicorn。
|
||
|
||
## 10. 常见部署问题
|
||
|
||
| 问题 | 处理 |
|
||
|---|---|
|
||
| 端口 8000 被占用 | 修改 compose 端口映射 |
|
||
| API Key 缺失 | 页面提示 LLM 或 Embedding 配置缺失 |
|
||
| Chroma 目录无权限 | 检查 `data/chroma` 挂载权限 |
|
||
| 上传目录不存在 | settings 或启动脚本创建目录 |
|
||
| 场景配置读取失败 | 检查 `configs/*.yaml` 格式 |
|
||
| Docker 构建慢 | 提前构建镜像或使用本地 Python 方式演示 |
|
||
|
||
## 11. 后续部署扩展
|
||
|
||
- 使用 Gunicorn + WhiteNoise。
|
||
- 增加 PostgreSQL 服务。
|
||
- 增加 Redis 和 Celery 做异步入库。
|
||
- 增加 Nginx 反向代理。
|
||
- 增加健康检查接口。
|