113 lines
3.4 KiB
Markdown
113 lines
3.4 KiB
Markdown
# 配置模块详细设计
|
||
|
||
## 1. 模块目标
|
||
|
||
Config 模块负责 Django 项目的启动配置和总装配。它不承载业务逻辑，只为其他模块提供稳定运行环境。
|
||
|
||
目标：
|
||
|
||
- 项目本地和 Docker 均可启动。
|
||
- 环境变量可覆盖关键配置。
|
||
- App、模板、静态资源、上传文件和数据库路径统一配置。
|
||
- URL 总入口清晰，模块路由各自维护。
|
||
|
||
## 2. 职责边界
|
||
|
||
负责：
|
||
|
||
- `settings.py`、`urls.py`、`wsgi.py`、`asgi.py`。
|
||
- 环境变量读取和默认值。
|
||
- SQLite、静态文件、媒体文件、Chroma、场景配置目录。
|
||
- Django Admin 和模块 URL 装配。
|
||
|
||
不负责：
|
||
|
||
- 不读取场景 YAML 业务内容。
|
||
- 不调用 Agent Core。
|
||
- 不处理上传文件文本抽取。
|
||
- 不写审计日志。
|
||
|
||
## 3. 配置项设计
|
||
|
||
| 配置 | Django setting | 默认值 |
|
||
|---|---|---|
|
||
| `DJANGO_SECRET_KEY` | `SECRET_KEY` | `dev-secret-key` |
|
||
| `DJANGO_DEBUG` | `DEBUG` | `true` |
|
||
| `DJANGO_ALLOWED_HOSTS` | `ALLOWED_HOSTS` | `["*"]` |
|
||
| `UPLOAD_ROOT` | `MEDIA_ROOT` | `BASE_DIR / "data" / "uploads"` |
|
||
| `SCENARIO_CONFIG_DIR` | `SCENARIO_CONFIG_DIR` | `BASE_DIR / "configs"` |
|
||
| `CHROMA_PATH` | `CHROMA_PATH` | `BASE_DIR / "data" / "chroma"` |
|
||
| `LLM_API_KEY` | `LLM_API_KEY` | 空 |
|
||
| `LLM_BASE_URL` | `LLM_BASE_URL` | `https://api.openai.com/v1` |
|
||
| `LLM_MODEL` | `LLM_MODEL` | `gpt-4.1-mini` |
|
||
| `EMBEDDING_API_KEY` | `EMBEDDING_API_KEY` | 空，默认可复用 `LLM_API_KEY` |
|
||
| `EMBEDDING_BASE_URL` | `EMBEDDING_BASE_URL` | 空，默认可复用 `LLM_BASE_URL` |
|
||
| `EMBEDDING_MODEL` | `EMBEDDING_MODEL` | `text-embedding-3-small` |
|
||
|
||
## 4. 目录路径设计
|
||
|
||
启动前或初始化时应确保：
|
||
|
||
```text
|
||
data/
|
||
uploads/
|
||
chroma/
|
||
configs/
|
||
static/
|
||
templates/
|
||
```
|
||
|
||
V1 可以在 `settings.py` 中定义路径，在 management command 或启动脚本中创建目录。生产代码不应在每次请求中反复创建目录。
|
||
|
||
## 5. URL 总路由设计
|
||
|
||
`config.urls`：
|
||
|
||
```python
|
||
urlpatterns = [
|
||
path("admin/", admin.site.urls),
|
||
path("", include("apps.scenarios.urls")),
|
||
path("chat/", include("apps.chat.urls")),
|
||
path("documents/", include("apps.documents.urls")),
|
||
path("audit/", include("apps.audit.urls")),
|
||
]
|
||
```
|
||
|
||
开发模式下追加 `static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)`，用于访问上传文件。
|
||
|
||
## 6. 静态资源与上传文件设计
|
||
|
||
- `STATIC_URL = "static/"`
|
||
- `STATICFILES_DIRS = [BASE_DIR / "static"]`
|
||
- `MEDIA_URL = "media/"`
|
||
- `MEDIA_ROOT = UPLOAD_ROOT`
|
||
|
||
上传文件路径由 Documents 模块按场景组织，Config 只提供根目录。
|
||
|
||
## 7. 环境变量读取设计
|
||
|
||
V1 可使用标准库 `os.environ.get()`，不强制引入复杂配置库。
|
||
|
||
布尔值规则：
|
||
|
||
```text
|
||
"1", "true", "yes", "on" -> True
|
||
其他 -> False
|
||
```
|
||
|
||
`DJANGO_ALLOWED_HOSTS` 使用逗号分隔，空值时默认 `["*"]`。
|
||
|
||
当前实现约束：
|
||
|
||
- 本地直接运行 Django 命令时，会先尝试解析根目录 `.env` 文件，再读取进程环境中的覆盖值。
|
||
- Docker Compose 方式可以通过 `env_file` 传入同一批变量；当前仓库默认读取 `.env`。
|
||
- `.env.example` 只保留占位符示例，不保存真实 API Key。
|
||
|
||
## 8. 验收标准
|
||
|
||
- `python manage.py check` 通过。
|
||
- `python manage.py migrate` 可执行。
|
||
- `/`、`/admin/` 路由可访问。
|
||
- `MEDIA_ROOT`、`CHROMA_PATH`、`SCENARIO_CONFIG_DIR` 在 settings 中可被其他模块引用。
|
||
- LLM 与 Embedding 配置只从 settings 或环境变量读取，不散落在业务代码中。
|