DEMO-AGENT/docs/设计文档/5.部署设计.md

V1 部署设计文档

1. 部署设计目标

V1 部署目标是降低复试现场环境风险。系统应支持本地 Python 方式启动，也支持 Docker Compose 一键启动。默认不依赖外部数据库、Redis 或任务队列。

2. 本地运行方式

建议命令：

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 运行方式

建议命令：

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 需要持久化以下目录：

./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 容器启动时建议执行：

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 反向代理。
• 增加健康检查接口。