第 11 章 配置系统 conf.py
学习目标
学完本章，你应该能：
- 理解 fba 的配置体系（配置文件、配置优先级）
- 知道在哪里改数据库、Redis、token 等配置
- 理解静态配置和动态配置的区别
一、配置文件在哪
fba 的所有配置集中在一个文件：backend/core/conf.py。
这个文件通过 Pydantic 的 Settings 机制定义所有配置项。所有应用和插件的配置都统一放在这里。
Settings（Pydantic Settings）：Pydantic 提供的一个功能，能从环境变量、
.env文件等地方读取配置，并做类型校验。
二、配置分类
fba 把配置分为两类：
| 类型 | 说明 |
|---|---|
| 静态配置 | 在 Settings 初始化时解析（应用启动时读一次） |
| 动态配置 | 运行时按需从"参数配置"插件加载（可在管理后台修改） |
三、配置优先级（重要）
一个配置项可能出现在多个地方，fba 规定了明确的优先级（从高到低）：
系统环境变量 > .env 文件 > 插件 settings 配置 > conf.py 默认值也就是说：
- 系统环境变量优先级最高（适合容器、CI/CD 注入密钥）
.env文件次之（适合本地/单机部署）- 插件提供的默认值再次之
conf.py里写的默认值最低（兜底）
配置优先级金字塔
记住：越靠上的优先级越高。同一个配置项如果在多个地方都设了值，上面的会覆盖下面的。
四、.env 文件
.env 是存放环境变量的文件，初始化项目时通过 cp .env.example .env 创建。
它通常放敏感信息（数据库密码、token 密钥等），并且不应提交到 git 仓库。
五、常用配置项速查
fba 有 140+ 配置项，这里列出最常用的几类：
1. 数据库配置
| 配置项 | 说明 |
|---|---|
DATABASE_TYPE | 数据库类型（mysql / postgresql） |
DATABASE_HOST | 数据库地址 |
DATABASE_PORT | 数据库端口 |
DATABASE_USER | 用户名 |
DATABASE_PASSWORD | 密码 |
DATABASE_SCHEMA | 数据库名 |
DATABASE_PK_MODE | 主键模式（autoincrement / snowflake）⚠️ 不要随意改 |
2. Redis 配置
| 配置项 | 说明 |
|---|---|
REDIS_HOST | Redis 地址 |
REDIS_PORT | Redis 端口 |
REDIS_PASSWORD | Redis 密码 |
REDIS_DATABASE | Redis 数据库索引（0-15） |
3. Token / JWT 配置
| 配置项 | 说明 |
|---|---|
TOKEN_SECRET_KEY | token 密钥 ⚠️ 妥善保管 |
TOKEN_ALGORITHM | 加密算法 |
TOKEN_EXPIRE_SECONDS | token 过期时间（秒） |
4. 时区配置
| 配置项 | 说明 |
|---|---|
DATETIME_TIMEZONE | 全局时区 |
DATETIME_FORMAT | 时间格式化字符串 |
5. 环境配置
| 配置项 | 说明 |
|---|---|
ENVIRONMENT | 环境模式（dev / prod），设为 prod 会禁用在线文档 |
六、如何改配置
改配置的典型流程：
- 打开
backend/core/conf.py，找到对应配置项（了解它的类型和默认值） - 如果是敏感信息或环境差异配置，在
.env文件里设置 - 修改后重启服务生效
示例：修改数据库连接，在
.env里改DATABASE_HOST、DATABASE_PASSWORD等。
改配置决策流程
七、动态配置（进阶）
fba 支持运行时动态配置：在管理后台修改某些业务参数（如系统名称、开关等），无需重启服务。这通过"参数配置"插件实现。
动态配置是"静态配置完成后的运行时覆盖层"，业务调用加载函数后，插件中的值会覆盖 settings 单例中的同名值。
静态 vs 动态配置
八、常见疑问
Q1：为什么配置要分优先级？ 因为同一套代码要跑在开发、测试、生产不同环境。通过优先级，可以用环境变量覆盖默认值，实现"一份代码，多套配置"。
Q2：.env 为什么要不提交 git？ 因为它包含密码、密钥等敏感信息，一旦泄露可能被攻击。正确的做法是：提交 .env.example（模板），不提交真实的 .env。
本章小结
关键要点回顾：
- 所有配置集中在
backend/core/conf.py - 配置优先级：环境变量 > .env > 插件默认值 > conf.py 默认值
- 敏感信息放
.env，不提交到 git - 改配置后需重启服务（动态配置除外）
- 主键模式（DATABASE_PK_MODE）不要随意更改
下一步： 第 12 章讲认证与权限，这是企业级项目最核心的安全能力。
对应官方文档：
配置（backend/reference/conf.html）