DEMO-AGENT/docs/需求分析/3.配置模块需求.md

配置模块需求文档

1. 模块定位

Config 模块是 Django 项目的基础配置模块，负责系统启动、路由装配、环境变量读取、静态资源、文件存储、数据库、日志和第三方组件配置。

该模块不承载业务逻辑，只负责让系统稳定启动，并为其他模块提供统一运行环境。

2. 模块目标

• 支持本地开发和 Docker 部署两种运行方式。
• 支持通过环境变量切换模型 API、Embedding API、调试模式和文件路径。
• 统一注册 Django Apps、模板目录、静态资源目录和上传目录。
• 提供系统级 URL 路由入口。
• 为后续扩展 PostgreSQL、Redis、Celery 等组件预留配置空间。

3. 职责边界

3.1 负责

• Django settings.py 配置。
• Django urls.py 总路由配置。
• WSGI / ASGI 启动配置。
• 环境变量读取。
• SQLite 默认数据库配置。
• 静态文件和上传文件配置。
• Chroma 本地持久化目录配置。
• LLM 与 Embedding 相关环境变量配置。

3.2 不负责

• 不处理具体 Agent 业务逻辑。
• 不解析场景 YAML。
• 不处理文件入库。
• 不直接调用大模型。
• 不保存审计日志。

4. 配置项需求

系统至少需要支持以下环境变量：

配置项	默认值	说明
DJANGO_SECRET_KEY	dev-secret-key	Django 密钥
DJANGO_DEBUG	true	是否开启调试模式
DJANGO_ALLOWED_HOSTS	*	允许访问的主机
DATABASE_URL	空	预留配置，V1 默认 SQLite，不要求解析该配置
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 模型名称
CHROMA_PATH	data/chroma	Chroma 持久化目录
UPLOAD_ROOT	data/uploads	上传文件目录
SCENARIO_CONFIG_DIR	configs	场景配置目录

补充要求：

• .env.example 仅作为模板文件，不得写入真实密钥。
• 本地直接执行 python manage.py runserver 时，应自动读取根目录 .env。
• Docker 运行时可通过 env_file 或容器环境变量注入同一组配置；当前仓库默认由 Compose 读取 .env。

5. 目录需求

系统启动时需要保证以下目录存在：

data/
  uploads/
  chroma/
  db.sqlite3

configs/

如果目录不存在，V1 可以在初始化脚本或启动流程中创建。

6. 路由需求

总路由需要聚合以下模块路由：

路径	模块	用途
/	apps.scenarios	首页和场景列表
/chat/	apps.chat	Agent 对话
/documents/	apps.documents	文件上传和文档管理
/audit/	apps.audit	审计日志查看
/admin/	Django Admin	后台管理

7. 启动需求

本地启动：

python manage.py migrate
python manage.py runserver

说明：上述命令执行前，应先准备好根目录 .env；当前 V1 代码会在启动时自动加载该文件。

Docker 启动：

docker compose up --build

8. 验收标准

• 项目可以通过 python manage.py runserver 启动。
• 项目可以通过 docker compose up --build 启动。
• /admin/ 可以访问。
• 首页 / 可以访问。
• 环境变量可以覆盖默认 LLM 与 Embedding 配置。
• 上传目录和 Chroma 目录有明确配置。