配置模块详细设计

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. 目录路径设计

启动前或初始化时应确保：

data/
  uploads/
  chroma/
configs/
static/
templates/

V1 可以在 settings.py 中定义路径，在 management command 或启动脚本中创建目录。生产代码不应在每次请求中反复创建目录。

5. URL 总路由设计

config.urls：

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()，不强制引入复杂配置库。

布尔值规则：

"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 或环境变量读取，不散落在业务代码中。

3.4 KiB Raw Blame History Unescape Escape