yuxuanhui
25 lines
1.8 KiB
Markdown
25 lines
1.8 KiB
Markdown
# 配置与运行时
|
||
|
||
## 配置入口
|
||
|
||
进程配置集中在 `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` 字段存在就引入一套日志框架；如果新增持久化或结构化日志，应先形成可验证的实现和对应规格。
|