docs(design): 补全中文设计文档体系

docs/设计文档/5.部署设计.md

@@ -0,0 +1,103 @@
+# 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`。
+
+## 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` 应提供这些变量的样例，不写真实密钥。
+
+## 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 反向代理。
+- 增加健康检查接口。