InvenTree 1.6.1 配置参数详解

目标：以真实部署为载体，逐节拆解 InvenTree 1.6.1 的主配置文件 config.yaml 全部配置节，并实测其环境变量覆盖机制。全部回显取自 1.6.1 部署实例（部署过程见《InvenTree 1.6.1 Docker Compose 部署指南》），模板原文以 1.6.1 tag 源码 src/backend/InvenTree/config_template.yaml（278 行）为准，实测时点 2026-10-23。

一、环境信息

InvenTree 版本：1.6.1（官方最新稳定版，2026-10-21 发布）
部署形态：五服务栈（部署篇同款），Web 端口 8146，数据目录 /opt/inventree/data
主配置文件：/opt/inventree/data/config.yaml（首次启动时系统自动由内置模板复制生成，见部署篇 4.5 节日志回显）
配置模板：src/backend/InvenTree/config_template.yaml（1.6.1 tag，278 行）
运行时 Python：3.14（部署实例回显）；配置加载源码：InvenTree/config.py
实测时点：2026-10-23

二、配置体系总览

InvenTree 1.6.1 的配置有三层，生效优先级从高到低：

层	载体	适用场景	生效方式
1. 环境变量	`INVENTREE_*` 前缀（`.env` 文件或 systemd `Environment=` 注入）	编排参数与敏感信息	改后重启进程
2. config.yaml	数据目录下 `config.yaml`	站点级静态配置	改后重启进程
3. 默认值	源码 `settings.py` 内置	未配置项	即时

此外还有第四类「管理员中心设置」（存数据库、运行时可改，如货币、UI 偏好），它与 config.yaml 的分工是：config.yaml 管「进程启动参数」，管理员中心管「业务运行参数」。config.yaml 的 global_settings_override 节（见 4.17）可以把某个管理员中心设置锁死为静态值。

模板文件头部的声明（1.6.1 tag 原文）：

# InvenTree Configuration Template
# Ref: https://docs.inventree.org/en/stable/start/config/
# Note: Environment variables take precedence over values set in this file

优先级规则是官方显式承诺的，本章 3.2 节用实测证明它。

2.1 配置文件定位

首次启动时，系统把安装包内置模板复制到数据目录（部署篇日志回显）：

Copying config file from /home/inventree/src/backend/InvenTree/config_template.yml to /home/inventree/data/config.yaml

💡 注意细节：日志里源文件名是 config_template.yml（包内已重命名），复制产物是 config.yaml。裸机 git 安装时配置文件默认在源码树 src/backend/InvenTree/config.yaml，可用 INVENTREE_CONFIG_FILE 环境变量指向其他路径（部署实例即用该变量指向数据目录）。

2.2 配置来源溯源接口（本次实测的核心工具）

InvenTree 内置配置溯源接口 /api/admin/config/（超管权限），返回进程已读取的每个配置项及其实际生效来源（env/yaml/default）。实测（2026-10-23）：

curl -s -u admin:q1w2e3r4 http://192.168.146.128:8146/api/admin/config/ | python3 -c "
import json,sys
d = json.load(sys.stdin)
print('total:', len(d))
src = {}
for e in d: src[e['source']] = src.get(e['source'],0)+1
print('by source:', src)
for e in d:
    if e['key'] in ('INVENTREE_TIMEZONE','INVENTREE_DEBUG','INVENTREE_DB_HOST','INVENTREE_SITE_URL','INVENTREE_CACHE_ENABLED'):
        print(e['key'],'| config_key:',e['config_key'],'| source:',e['source'])
"

total: 146
by source: {'env': 29, 'yaml': 29, 'default': 88}
INVENTREE_DEBUG | config_key: debug | source: env
INVENTREE_DB_HOST | config_key: database.host | source: env
INVENTREE_CACHE_ENABLED | config_key: cache.enabled | source: env
INVENTREE_SITE_URL | config_key: site_url | source: env
INVENTREE_TIMEZONE | config_key: timezone | source: yaml

解读：部署实例运行时共访问 146 个配置项——29 项来自环境变量、29 项来自 config.yaml、88 项走源码默认值。env_var ↔ config_key 的映射关系（如 INVENTREE_TIMEZONE ↔ timezone、INVENTREE_DB_HOST ↔ database.host）即环境变量命名规则的权威清单。

三、环境变量覆盖机制（实测）

3.1 映射规则

环境变量名 = INVENTREE_ + 配置键大写蛇形；嵌套键用下划线连接，如 database.host → INVENTREE_DB_HOST、cache.enabled → INVENTREE_CACHE_ENABLED（INVENTREE_DB_/INVENTREE_EMAIL_ 等短前缀在模板注释中逐一标注）。
加载源码 config.py 的 get_setting() 实现：每个配置项先查环境变量，命中则来源记 env；未命中再取 config.yaml 的对应键，来源记 yaml；都没有则走 default。同一进程生命周期内每次读取都登记进 CONFIG_LOOKUPS（即 2.2 节接口的返回内容）。
部分路径类配置支持「文件引用变量」：如 INVENTREE_SECRET_KEY_FILE 指向存放密钥的文件（部署实例默认 /home/inventree/data/secret_key.txt），INVENTREE_OIDC_PRIVATE_KEY_FILE 指向 OIDC 签名密钥文件——避免把密钥明文写进环境变量。

3.2 实测一：config.yaml 修改生效流程（timezone）

第一步，把数据目录 config.yaml 第 80 行的时区改为 Asia/Shanghai：

sed -i 's/^timezone: UTC$/timezone: Asia\/Shanghai/' /opt/inventree/data/config.yaml
grep -n '^timezone' /opt/inventree/data/config.yaml

80:timezone: Asia/Shanghai

第二步，重启 InvenTree 服务进程与后台工作进程后，验证运行时设置与溯源：

cd /opt/inventree/src/backend/InvenTree && python manage.py shell -c "from django.conf import settings; print('TIME_ZONE =', settings.TIME_ZONE)"

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

TIME_ZONE = Asia/Shanghai

curl -s -u admin:q1w2e3r4 http://192.168.146.128:8146/api/admin/config/ | python3 -c "
import json,sys
for e in json.load(sys.stdin):
    if e['key']=='INVENTREE_TIMEZONE': print('lookup:', e['config_key'], '| source:', e['source'])
"

lookup: timezone | source: yaml

结论：改 config.yaml + 重启进程 → 生效，来源标记 yaml。（shell 输出的前两行 INVE-W3 与 116 objects imported automatically 是 manage.py shell 的固定横幅，与配置无关。）

3.3 实测二：环境变量覆盖 config.yaml（优先级证明）

在 .env 追加 INVENTREE_TIMEZONE=UTC 并重建服务进程后复验：

echo 'INVENTREE_TIMEZONE=UTC' >> /opt/inventree/.env
# 重启服务进程后：

cd /opt/inventree/src/backend/InvenTree && python manage.py shell -c "from django.conf import settings; print('TIME_ZONE =', settings.TIME_ZONE)"

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

TIME_ZONE = UTC

curl -s -u admin:q1w2e3r4 http://192.168.146.128:8146/api/admin/config/ | python3 -c "
import json,sys
for e in json.load(sys.stdin):
    if e['key']=='INVENTREE_TIMEZONE': print('lookup:', e['config_key'], '| source:', e['source'])
"

lookup: timezone | source: env

结论：config.yaml 明明写着 timezone: Asia/Shanghai，运行时却是 UTC，溯源显示来源 env——环境变量压过 config.yaml 实锤。测试后已回滚（删除该环境变量、timezone 恢复 UTC）。

3.4 安装包内置环境变量（部署实例实查）

部署实例进程内实查 env | grep ^INVENTREE | sort，除 .env 注入项外，以下为运行包自动设置的默认值（改路径类部署必看）：

INVENTREE_BACKEND_DIR=/home/inventree/src/backend
INVENTREE_CONFIG_FILE=/home/inventree/data/config.yaml
INVENTREE_DATA_DIR=/home/inventree/data
INVENTREE_HOME=/home/inventree
INVENTREE_DEBUG=False
INVENTREE_DOCKER=true
INVENTREE_MEDIA_ROOT=/home/inventree/data/media
INVENTREE_STATIC_ROOT=/home/inventree/data/static
INVENTREE_BACKUP_DIR=/home/inventree/data/backup
INVENTREE_PLUGIN_DIR=/home/inventree/data/plugins
INVENTREE_PLUGIN_FILE=/home/inventree/data/plugins.txt
INVENTREE_SECRET_KEY_FILE=/home/inventree/data/secret_key.txt
INVENTREE_OIDC_PRIVATE_KEY_FILE=/home/inventree/data/oidc.pem
INVENTREE_BACKGROUND_WORKERS=4
INVENTREE_WEB_ADDR=0.0.0.0
INVENTREE_WEB_PORT=8000

⚠️ 高频坑：INVENTREE_DEBUG=False 是运行包内置的环境变量。你在 config.yaml 里写 debug: True 想开调试模式，永远不生效（env > yaml），溯源接口会告诉你 INVENTREE_DEBUG | source: env。同理，改 static_root/media_root/backup_dir 等路径键之前先想想要不要改环境变量。

3.5 运行时设置回显汇总（部署实例实测）

以下为部署实例的运行时设置快照（python manage.py shell -c 逐项打印）：

cd /opt/inventree/src/backend/InvenTree && python manage.py shell -c "
from django.conf import settings as s
print('DEBUG =', s.DEBUG)
print('TIME_ZONE =', s.TIME_ZONE)
print('LANGUAGE_CODE =', s.LANGUAGE_CODE)
print('MEDIA_ROOT =', s.MEDIA_ROOT)
print('STATIC_ROOT =', s.STATIC_ROOT)
print('ALLOWED_HOSTS =', s.ALLOWED_HOSTS)
print('CSRF_TRUSTED_ORIGINS =', s.CSRF_TRUSTED_ORIGINS)
print('EMAIL_BACKEND =', s.EMAIL_BACKEND)
print('DB =', s.DATABASES['default']['ENGINE'], s.DATABASES['default']['NAME'], s.DATABASES['default']['HOST'], s.DATABASES['default']['PORT'])
print('CACHE default =', s.CACHES['default'].get('LOCATION'))
print('LOG_LEVEL =', s.LOGGING['loggers']['inventree']['level'])
"

INVE-W3: Could not detect git information.
116 objects imported automatically (use -v 2 for details).

DEBUG = False
TIME_ZONE = UTC
LANGUAGE_CODE = en-us
MEDIA_ROOT = /home/inventree/data/media
STATIC_ROOT = /home/inventree/data/static
ALLOWED_HOSTS = ['*', '192.168.146.128']
CSRF_TRUSTED_ORIGINS = ['http://192.168.146.128:8146']
EMAIL_BACKEND = InvenTree.backends.InvenTreeMailLoggingBackend
DB = django.db.backends.postgresql inventree inventree-db 5432
CACHE default = redis://inventree-cache:6379/0
LOG_LEVEL = WARNING

两个值得注意的联动：

ALLOWED_HOSTS 自动出现站点主机 192.168.146.128：settings 层会把 site_url 的主机部分追加进白名单（模板默认 allowed_hosts: ['*'] 之外叠加）。
CSRF_TRUSTED_ORIGINS = ['http://192.168.146.128:8146']：site_url（含端口）自动进 CSRF 白名单——这就是部署篇强调 INVENTREE_SITE_URL 要写用户实际访问 URL（含端口）的原因。
默认 EMAIL_BACKEND = InvenTree.backends.InvenTreeMailLoggingBackend：未配置邮件时不投递，只写日志。

四、config.yaml 逐节详解

以下按模板（278 行）自上而下的节顺序逐节拆解。每节给出：官方默认值、对应环境变量、行为说明；标注「实测」的条目有部署实例回显支撑。

4.1 密钥与站点基础（模板 1~30 行）

配置键	默认	环境变量	说明
`secret_key`	自动生成	`INVENTREE_SECRET_KEY` / `INVENTREE_SECRET_KEY_FILE`	Django SECRET_KEY；未配置时系统写入数据目录 `secret_key.txt`（部署实例已见该文件）。丢失会导致会话与令牌全部失效
`oidc_private_key`	无	`INVENTREE_OIDC_PRIVATE_KEY` / `INVENTREE_OIDC_PRIVATE_KEY_FILE`	OIDC 供给（1.6 新特性）签名私钥；部署实例数据目录已有 `oidc.pem`
`database.*`	见下表	`INVENTREE_DB_*`	数据库连接节，引擎可选 `mysql`/`postgresql`/`sqlite3`（模板注释原文）
`site_url`	注释态	`INVENTREE_SITE_URL`	站点对外 URL；进 `ALLOWED_HOSTS` 与 `CSRF_TRUSTED_ORIGINS`（3.5 实测）

database 子键（模板 19~30 行）：engine/name/user/password/host/port。部署实例全部经 INVENTREE_DB_* 注入（3.5 节回显：postgresql / inventree / inventree-db / 5432）。SQLite 形态不设 host/port，仅用于评估场景。

4.2 调试与诊断（模板 34~41 行）

配置键	默认	环境变量	说明
`debug`	`False`	`INVENTREE_DEBUG`	生产模式开关；运行包已内置 `INVENTREE_DEBUG=False`（3.4 节），yaml 层改 True 无效——这是最常见的配置困惑点
`debug_querycount`	`False`	—	查询计数诊断
`debug_silk`	`False`	—	Silk 性能剖析面板
`debug_silk_profiling`	`False`	—	Silk 函数级剖析
`debug_shell`	`False`	—	shell 增强（富交互 REPL）

4.3 管理界面与首启管理员（模板 47~57 行）

配置键	默认	环境变量	说明
`admin_enabled`	`True`	`INVENTREE_ADMIN_ENABLED`	Django Admin 后台开关
`admin_url`	`admin`	`INVENTREE_ADMIN_URL`	Admin 后台路径（改路径属常规加固）
`admin_user`/`admin_email`/`admin_password`	无	`INVENTREE_ADMIN_USER/EMAIL/PASSWORD`	首启自动建号；三项齐备才创建（部署篇排障 12.3 实证）；也可指向文件

4.4 日志体系（模板 59~74 行）

配置键	默认	环境变量	说明
`log_level`	`WARNING`	`INVENTREE_LOG_LEVEL`	级别：DEBUG/INFO/WARNING/ERROR/CRITICAL；实测回显 `LOG_LEVEL = WARNING`
`json_log`	`False`	`INVENTREE_JSON_LOG`	日志 JSON 化（便于采集器解析）
`db_logging`	`False`	`INVENTREE_DB_LOGGING`	数据库层日志（排慢查询用，量大会拖性能）
`write_log`	`False`	`INVENTREE_WRITE_LOG`	落盘日志文件（目录由 `log_file_dir` 决定）
`console_log`	`True`	`INVENTREE_CONSOLE_LOG`	控制台输出（部署篇 4.5 节的日志即来自它）

4.5 语言与时区（模板 76~80 行）

配置键	默认	环境变量	说明
`language`	`en-us`	`INVENTREE_LANGUAGE`	界面默认语言，实测回显 `LANGUAGE_CODE = en-us`；中文 `zh-cn`
`timezone`	`UTC`	`INVENTREE_TIMEZONE`	系统时区；3.2/3.3 节完整实测了 yaml 生效与 env 覆盖全过程

4.6 邮件（模板 82~110 行）

配置键	默认	说明
`email.sender`	`''`	发件地址，如 `inventree@example.org`
`email.backend`	注释态	三选一：SMTP（`django.core.mail.backends.smtp.EmailBackend`）/ console / anymail
`email.host`/`port`	`''`/`25`	SMTP 服务器与端口
`email.username`/`password`	`''`	SMTP 认证
`email.tls`/`ssl`	`False`	加密开关

对应环境变量前缀 INVENTREE_EMAIL_（模板注释原文：INVENTREE_EMAIL_HOST / INVENTREE_EMAIL_PORT / INVENTREE_EMAIL_USERNAME）。未配置时后端为 InvenTreeMailLoggingBackend（3.5 节实测）——邮件只记日志不发送。

4.7 可观测性：Sentry 与 OpenTelemetry（模板 111~124 行）

配置键	默认	说明
`sentry_enabled`	`False`	错误上报官方 Sentry；自建 DSN 可配 `sentry.dsn`
`sentry_send_pii`	`False`	是否含 PII（用户 id/邮箱/IP），默认关闭
`tracing.enabled`	`false`	OpenTelemetry 链路/指标导出（对接 OTLP 兼容后端）

4.8 插件与自动迁移（模板 125~132 行）

配置键	默认	环境变量	说明
`plugins_enabled`	`False`	`INVENTREE_PLUGINS_ENABLED`	插件总开关；部署实例为 True（`.env` 注入）
`plugin_file`	注释态	—	插件清单文件（部署实例 `/home/inventree/data/plugins.txt` 由运行环境变量指定）
`plugin_dir`	注释态	—	插件目录（部署实例 `/home/inventree/data/plugins`）
`plugin_noinstall`	注释态	—	跳过插件安装步骤（离线场景）
`auto_update`	`False`	`INVENTREE_AUTO_UPDATE`	启动时自动跑数据库迁移；部署实例为 True；官方注释明确它不取代手动 `invoke update`（静态文件收集等仍要 update，见命令篇）

4.9 主机白名单与代理头（模板 134~150 行）

配置键	默认	环境变量	说明
`allowed_hosts`	`['*']`	`INVENTREE_ALLOWED_HOSTS`	模板注释原文警告「Default behaviour is to allow all hosts (THIS IS NOT SECURE!)」；部署实例运行时叠加了 site_url 主机
`trusted_origins`	注释态	`INVENTREE_TRUSTED_ORIGINS`	CSRF 白名单补充（site_url 已自动加入，3.5 节实测）
`use_x_forwarded_host`/`port`/`proto`	注释态	`INVENTREE_USE_X_FORWARDED_HOST/PORT/PROTO`	反代转发头开关；部署实例三项均 True

配置键	默认	说明
`cookie.secure`/`samesite`	`false`/`false`（注释态）	Cookie 安全属性，HTTPS 站点建议 `secure: true`
`cors.allow_all`	`true`	允许所有跨域来源（默认开着，生产建议收紧）
`cors.allow_credentials`	`true`	跨域携带凭据
`cors.whitelist`	注释态	白名单列表，如 `https://example.com`
`cors.regex`	注释态	正则匹配跨域来源

4.11 API 限流（模板 168~172 行）

throttle.anon/throttle.user（注释态，官方示例 20/minute、60/second）——API 默认带限流防 DoS，显式设 None 可关闭。

4.12 存储路径（模板 173~181 行）

配置键	默认	环境变量	说明
`media_root`	注释态	`INVENTREE_MEDIA_ROOT`	上传文件目录（部署实例 `/home/inventree/data/media`）
`static_root`	注释态	`INVENTREE_STATIC_ROOT`	静态资源目录（部署实例 `/home/inventree/data/static`）
`backup_dir`	注释态	`INVENTREE_BACKUP_DIR`	备份目录（部署实例 `/home/inventree/data/backup`）

三个路径实测均有对应目录落盘（见部署篇 5.2 节数据目录清单）。

4.13 后台任务（模板 182~186 行）

配置键	默认	说明
`background.workers`	`4`	django-q2 工作线程数；运行环境变量 `INVENTREE_BACKGROUND_WORKERS` 可覆盖
`background.timeout`	`90`	单任务超时（秒）；实测运行时 `Q_CLUSTER timeout = 90`
`background.max_attempts`	`5`	失败重试上限

实测运行时快照（python manage.py shell -c）：

Q_CLUSTER workers = 4
Q_CLUSTER timeout = 90
Q_CLUSTER name = InvenTree

4.14 缓存（模板 188~193 行）

配置键	默认	环境变量	说明
`cache.enabled`	`false`	`INVENTREE_CACHE_ENABLED`	部署实例 True
`cache.host`	`inventree-cache`	`INVENTREE_CACHE_HOST`	部署实例同值（栈内服务名）
`cache.port`	`6379`	`INVENTREE_CACHE_PORT`	实测运行时 `CACHE default = redis://inventree-cache:6379/0`

4.15 登录与会话（模板 194~211 行）

配置键	默认	说明
`login_confirm_days`	`3`	邮箱确认链接有效期
`login_attempts`	`5`	登录失败锁定阈值
`login_default_protocol`	`http`	登录链接协议
`remote_login_enabled`/`remote_login_header`	`False`/`HTTP_REMOTE_USER`	代理层认证（Remote User 头），官方注释警示配置不当有安全风险
`logout_redirect_url`	`index`	登出跳转；远程登录场景常需改

4.16 SSO 与 LDAP（模板 213~227 行）

配置键	默认	说明
`social_backends`	注释态	注册 allauth 社交登录提供方，如 `allauth.socialaccount.providers.google`、`...providers.github`
`social_providers`	注释态	提供方参数，如 `github: {VERIFIED_EMAIL: true}`
`ldap.*`	注释态	LDAP 认证（官方 advanced 文档专节）

4.17 定制与锁定（模板 230~251 行）

配置键	默认	说明
`customize.site_header`/`login_message`/`navbar_message`	注释态	界面文案定制（管理面板标题/登录页提示/导航栏信息）
`customize.hide_admin_link`/`hide_password_reset`/`disable_theme_storage`	注释态	界面元素隐藏开关
`customize.logo`/`splash`	注释态	自定义 logo 与启动页图（相对媒体目录）
`global_settings_override`	注释态	锁定管理员中心设置，示例 `INVENTREE_DEFAULT_CURRENCY: 'CNY'`；锁定后 UI 不可改
`plugin_settings`	注释态	按插件 slug 锁定插件设置（同样 UI 不可改）

4.18 对象存储（模板 253~267 行）

配置键	默认	说明
`storage.backend`	注释态	本地存储之外可切 S3 兼容对象存储
`storage.s3.*`	注释态	`access_key`/`secret_key`/`bucket_name`/`region_name`/`endpoint_url`/`location`/`default_acl`/`verify_ssl`/`overwrite`/`virtual`——官方模板示例以 Hetzner Object Storage 端点示范

五、配置变更生效规则速查

变更对象	生效方式	实测依据
config.yaml	改文件 + 重启服务进程与 worker	3.2 节（timezone）
环境变量（`.env`）	改文件 + 重建/重启对应进程	3.3 节（INVENTREE_TIMEZONE）
管理员中心设置	UI/API 即时生效（存数据库）	模板 `global_settings_override` 注释
config.yaml 的 `global_settings_override`/`plugin_settings`	重启后锁定对应设置	模板注释「cannot be changed via the UI」
Caddy 反代规则文件	改文件 + 重启反代进程	部署篇 8.2 节

六、常见问题

6.1 为什么 config.yaml 里的 debug: True 不生效？

运行包内置 INVENTREE_DEBUG=False 环境变量优先级更高（3.4 节）。用 /api/admin/config/ 查来源即可自证。正确做法：改环境变量层（.env 中 INVENTREE_DEBUG=True）并重启。

6.2 改了配置但行为没变

先分三步：① 查 /api/admin/config/ 确认该键当前来源（env/yaml/default）与期望层级是否一致；② 确认该配置是「启动时读取」型（config.yaml 层全部需要重启，如 3.2 节）而非管理员中心热设置；③ 确认改的是部署实例实际加载的那份 config.yaml（INVENTREE_CONFIG_FILE 指向的文件，部署实例在数据目录而非源码树）。

6.3 数据库配置能写进 config.yaml 吗

能（4.1 节 database 节就是干这个的），但部署篇的栈形态下数据库凭据由 .env 注入并传给数据库端，两处必须一致——建议数据库配置只维护一处（环境变量层），避免「改了 yaml 没改 .env」导致的连接失败。另注意官方模板注释：包安装形态请用 inventree config 命令改数据库段，不要手改此节。

6.4 配置来源能不能批量看

/api/admin/config/ 一次返回全部已访问配置项的来源（2.2 节实测 146 项：env 29 / yaml 29 / default 88）。注意该接口属管理员中心 API，需超管账号（示例账号见部署篇）。

七、参考链接

官方配置文档：https://docs.inventree.org/en/latest/start/config/
配置模板（1.6.1 tag）：https://github.com/inventree/InvenTree/blob/1.6.1/src/backend/InvenTree/config_template.yaml
配置加载源码：https://github.com/inventree/InvenTree/blob/1.6.1/src/backend/InvenTree/InvenTree/config.py
环境变量参考：https://docs.inventree.org/en/latest/start/advanced/
站内关联：《InvenTree 1.6.1 Docker Compose 部署指南》

InvenTree 1.6.1 配置参数详解

InvenTree 1.6.1 配置参数详解

一、环境信息

二、配置体系总览

2.1 配置文件定位

2.2 配置来源溯源接口（本次实测的核心工具）

三、环境变量覆盖机制（实测）

3.1 映射规则

3.2 实测一：config.yaml 修改生效流程（timezone）

3.3 实测二：环境变量覆盖 config.yaml（优先级证明）

3.4 安装包内置环境变量（部署实例实查）

3.5 运行时设置回显汇总（部署实例实测）

四、config.yaml 逐节详解

4.1 密钥与站点基础（模板 1~30 行）

4.2 调试与诊断（模板 34~41 行）

4.3 管理界面与首启管理员（模板 47~57 行）

4.4 日志体系（模板 59~74 行）

4.5 语言与时区（模板 76~80 行）

4.6 邮件（模板 82~110 行）

4.7 可观测性：Sentry 与 OpenTelemetry（模板 111~124 行）

4.8 插件与自动迁移（模板 125~132 行）

4.9 主机白名单与代理头（模板 134~150 行）

4.10 Cookie 与 CORS（模板 152~167 行）

4.11 API 限流（模板 168~172 行）

4.12 存储路径（模板 173~181 行）

4.13 后台任务（模板 182~186 行）

4.14 缓存（模板 188~193 行）

4.15 登录与会话（模板 194~211 行）

4.16 SSO 与 LDAP（模板 213~227 行）

4.17 定制与锁定（模板 230~251 行）

4.18 对象存储（模板 253~267 行）

五、配置变更生效规则速查

六、常见问题

6.1 为什么 config.yaml 里的 debug: True 不生效？

6.2 改了配置但行为没变

6.3 数据库配置能写进 config.yaml 吗

6.4 配置来源能不能批量看

七、参考链接