116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 配置模块需求文档
|
||
|
||
## 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. 目录需求
|
||
|
||
系统启动时需要保证以下目录存在：
|
||
|
||
```text
|
||
data/
|
||
uploads/
|
||
chroma/
|
||
db.sqlite3
|
||
|
||
configs/
|
||
```
|
||
|
||
如果目录不存在，V1 可以在初始化脚本或启动流程中创建。
|
||
|
||
## 6. 路由需求
|
||
|
||
总路由需要聚合以下模块路由：
|
||
|
||
| 路径 | 模块 | 用途 |
|
||
|---|---|---|
|
||
| `/` | `apps.scenarios` | 首页和场景列表 |
|
||
| `/chat/` | `apps.chat` | Agent 对话 |
|
||
| `/documents/` | `apps.documents` | 文件上传和文档管理 |
|
||
| `/audit/` | `apps.audit` | 审计日志查看 |
|
||
| `/admin/` | Django Admin | 后台管理 |
|
||
|
||
## 7. 启动需求
|
||
|
||
本地启动：
|
||
|
||
```bash
|
||
python manage.py migrate
|
||
python manage.py runserver
|
||
```
|
||
|
||
说明：上述命令执行前，应先准备好根目录 `.env`；当前 V1 代码会在启动时自动加载该文件。
|
||
|
||
Docker 启动：
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
## 8. 验收标准
|
||
|
||
- 项目可以通过 `python manage.py runserver` 启动。
|
||
- 项目可以通过 `docker compose up --build` 启动。
|
||
- `/admin/` 可以访问。
|
||
- 首页 `/` 可以访问。
|
||
- 环境变量可以覆盖默认 LLM 与 Embedding 配置。
|
||
- 上传目录和 Chroma 目录有明确配置。
|