zhixing-system/.trellis/spec/backend/configuration-and-runtime.md

配置与运行时

配置入口

进程配置集中在 zhixing-server/src/zhixing_server/bootstrap/config.py:Settings：

• 继承 pydantic_settings.BaseSettings，字段声明默认值和可接受类型。
• 通过 SettingsConfigDict(env_file=".env", env_prefix="ZHIXING_", extra="ignore") 读取环境变量；新增变量应遵循 ZHIXING_<FIELD> 命名。
• app_env 使用 Literal["development", "test", "production"]，不要在业务代码里重复字符串校验。
• get_settings() 使用 @lru_cache，在一个进程内复用同一配置对象。

端点通过 FastAPI 依赖注入拿配置，例如 interfaces/http/system.py:system_status 的 Annotated[Settings, Depends(get_settings)]。不要在路由或领域代码中直接读取 os.environ、.env 或 Docker 变量。

应用生命周期与部署

• bootstrap/app.py:create_app 创建 FastAPI(title=settings.app_name)，然后挂载 operational_router 和 api_v1_router。
• main.py 只导出 ASGI app，容器入口可以安全导入它。
• 健康检查固定为 /healthz；业务 API 固定挂在 /api/v1 下。
• 开发环境由 Vite 将 /api 和 /healthz 代理到 VITE_DEV_API_TARGET（默认 http://localhost:8000）；生产环境由 zhixing-web/nginx/default.conf.template 以 API_UPSTREAM 代理。浏览器代码不要拼接后端绝对地址。
• Docker Compose 的环境变量和端口默认值见根目录 .env.example、docker-compose.dev.yml 和 docker-compose.prod.yml。

目前没有的能力

当前仓库没有数据库连接、迁移、任务队列或日志配置实现。不要只因为 Settings.log_level 字段存在就引入一套日志框架；如果新增持久化或结构化日志，应先形成可验证的实现和对应规格。