Databunker 0.8.37 配置参数详解

Databunker 的配置由三层构成：命令行参数（启动/初始化动作）、环境变量（密钥与数据库连接、部分 YAML 覆盖）、YAML 配置文件（服务行为）。本文逐段拆解 0.8.37 的配置面，关键开关全部实测验证——包括一个容易踩坑的加载顺序：YAML 文件优先于环境变量。适合已完成部署（见《Databunker 0.8.37 Docker Compose 部署指南》）、需要按合规要求调参的运维与后端工程师。

一、配置体系总览

服务进程启动时的处理顺序（源码 src/service.go loadService()，0.8.37）：

ReadEnv(&cfg)              // ① envconfig 先用环境变量填充配置结构
ReadConfFile(&cfg, confPtr) // ② 再解析 YAML——同名键会覆盖①的结果

由此得出两条实际规则：

1. YAML 里显式写出的键，环境变量覆盖不了。官方默认 databunker.yaml 显式设置了 server.port: 3000，实测注入 BUNKER_PORT=3001 后监听端口仍是 3000：

docker compose exec -T -e BUNKER_PORT=3001 databunker sh -c \
  '/bin/busybox timeout 3 /databunker/bin/databunker -start -db databunkerdb -conf /databunker/conf/databunker.yaml 2>&1'

2026/11/03 03:49:00 Databunker version: 0.8.37-20261030100830-7667c5056897
2026/11/03 03:49:00 Loading configuration file: /databunker/conf/databunker.yaml
2026/11/03 03:49:00 Open HTTP listener 0.0.0.0:3000
2026/11/03 03:49:00 ListenAndServe(): listen tcp 0.0.0.0:3000: bind: address already in use

（末行 bind: address already in use 是因为常驻实例正占用 3000，属预期；关键是第二行证明端口取的是 YAML 值。）

2. YAML 中未写（或被注释）的键，环境变量才生效。例如 generic.admin_email 在默认 YAML 中不存在，ADMIN_EMAIL 环境变量可直接注入。

因此调参的正确姿势是：改 databunker.yaml（挂载替换）为主，环境变量仅用于密钥、数据库连接和 YAML 未占位的字段。

二、命令行参数

二进制 /databunker/bin/databunker 无子命令体系，仅 8 个 flag（flag 定义见源码，全部实测）：

-start 的健壮行为（源码 + 实测）：

• 数据库尚未就绪时每秒重试、最多 60 次（Trying to open db [1]…），适配 PostgreSQL 冷启动；实测把 PGSQL_HOST 置空触发 SQLite 回落时同样进入该循环：

docker compose exec -T -e PGSQL_HOST= databunker sh -c \
  '/bin/busybox timeout 3 /databunker/bin/databunker -start -db databunkerdb -conf /databunker/conf/databunker.yaml 2>&1'

2026/11/03 03:49:53 Databunker version: 0.8.37-20261030100830-7667c5056897
2026/11/03 03:49:53 Loading configuration file: /databunker/conf/databunker.yaml
2026/11/03 03:49:54 Trying to open db [1]
2026/11/03 03:49:55 Trying to open db [2]

• 60 次后仍无库：输出 Database is not initialized 并提示先跑 -init，进程退出。

三、运行时环境变量（密钥与数据库）

这组变量不走 YAML，由 os.Getenv 直接读取，是部署编排的必配项：

后端选择逻辑（src/storage.go initStorage()）：MYSQL_HOST 非空 → MySQL；否则 PGSQL_HOST 非空 → PostgreSQL；否则 SQLite（数据文件落在 -db 指定的文件名）。实测清空 PGSQL_HOST 后进程即按 SQLite 路径找库文件（上节回显）。

主密钥校验（实测两类失败回显）：

docker compose exec -T databunker sh -c 'DATABUNKER_MASTERKEY=tooshort /databunker/bin/databunker -start -db databunkerdb'

2026/11/03 03:47:01 Databunker version: 0.8.37-20261030100830-7667c5056897
2026/11/03 03:47:01 Loading configuration file: databunker.yaml
2026/11/03 03:47:01 Error: Master key length is wrong

docker compose exec -T databunker sh -c 'DATABUNKER_MASTERKEY=zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz /databunker/bin/databunker -start -db databunkerdb'

2026/11/03 03:47:01 Error: Failed to decode master key

长度不足 48 与非法 hex 都会在启动期快速失败——不会带着坏密钥提供服务，也不会静默生成新密钥。

四、密钥优先级与派生链

主密钥/根令牌的取值优先级由 utils.GetArgEnvFileVariable 决定：

命令行参数（-masterkey / -roottoken） > 环境变量 > *_FILE 文件

拿到主密钥后的内部派生（源码级）：

• 记录加密：AES-256-GCM，密钥 = 主密钥(24B) + 每条记录随机密钥(8B)；
• 检索索引盐值与验证码密钥：md5(masterKey)——loginidx/emailidx/phoneidx 列即 base64(SHA-256(salt + 归一化值))，登录验证码串用该派生密钥 AES-GCM 加密；
• 0.8.37 起 -init 日志中密钥一律打码（Master key: ****），密钥管理必须依赖 env_file/文件挂载，不能靠抄日志（见《Databunker 0.8.37 Docker Compose 部署指南》第七节）。

⚠️ 换主密钥 = 旧数据永久不可解。DATABUNKER_MASTERKEY 变更不会触发任何迁移提示，解密直接失败。备份该值是运维第一优先级。

五、YAML 配置文件逐段详解

官方默认 databunker.yaml（3241 字节，挂载于 /databunker/conf/databunker.yaml）全文分 10 段。以下按段说明，标注默认值与实测行为。

5.1 generic —— 全局 API 行为

generic:
  create_user_without_access_token: true
  # use_separate_app_tables: true
  # list_users: true
  # disable_audit: true

5.2 selfservice —— 用户自助权限

selfservice:
  #forget_me: false
  #user_record_change: true
  app_record_change: ["*"]

5.3 notification —— 事件外推

notification:
  #notification_url: "https://httpbin.org/post"

notification_url 接收 JSON 事件：登录失败、forget me、资料变更、同意变更。合规告警接入点。另有 magic_sync_url/magic_sync_token（跨实例同步，Pro 场景）。

5.4 policy —— 数据保留期

policy:
  max_user_retention_period: "3m"
  max_audit_retention_period: "6m"
  max_session_retention_period: "1h"
  max_shareable_record_retention_period: "1m"

后台清理任务每 10 分钟跑一次（源码 dbCleanup ticker）。单位语义：h 小时、d 天、m 月、y 年。源码默认值分别为 1m/12m/1h/1m，官方 YAML 把用户保留期收紧到 3m、审计 6m。到期记录由清理任务删除——这是 GDPR "存储限制原则"的落地开关。

5.5 ssl —— TLS 监听

ssl:
  ssl_certificate: "/databunker/certs/server.cer"
  ssl_certificate_key: "/databunker/certs/server.key"

存在即启用：服务启动时 os.Stat 检查证书路径（源码 service.go:132），文件存在则 Open HTTPS listener，否则 Open HTTP listener——没有单独的 enable 开关。TLS 最低版本 1.2，套件白名单硬编码（TLS1.3 AES-GCM/CHACHA20 + ECDHE-RSA AES-GCM 等）。环境变量 SSL_CERTIFICATE/SSL_CERTIFICATE_KEY 因 YAML 显式赋值而无效（见第一节规则），改路径请直接改 YAML 或挂载到固定路径。私钥权限坑与实测过程见《Databunker 0.8.37 Docker Compose 部署指南》第九节。

5.6 sms —— 短信网关

模板化配置：url 支持 {token}/{from}/{phone}/{msg} 占位符；method GET/POST；POST 体经 body 模板（_TOKEN_/_FROM_/_PHONE_/_MSG_ 修饰符）；支持 basic_auth、custom_header、content_type。default_country: "GB" 用于电话号归一化（libphonenumber 国家码）。不配置则登录短信链路不可用（邮件走 smtp 段）。

5.7 server —— 监听地址

server:
  host: "0.0.0.0"
  port: 3000

对应 BUNKER_HOST/BUNKER_PORT 环境变量名，但官方 YAML 显式赋值使其覆盖失效（实测见第一节）；要改端口请编辑 YAML 本身。

5.8 smtp —— 邮件网关

server/port/user/pass/sender 五键，占位符默认值（email-smtp-server.com 等）需替换。登录验证码邮件依赖此段；环境变量 SMTP_SERVER/SMTP_PORT/SMTP_USER/SMTP_PASS/SMTP_SENDER 同样因 YAML 显式赋值而无效，直接改 YAML。

5.9 ui —— Web 门户品牌化

logo_link、company_title、company_link、term_of_service_title/link、privacy_policy_title/link、custom_css_link、magic_lookup 等，控制内置自助门户的抬头、条款链接与样式。纯展示项，改完刷新页面即生效（进程无需重启的静态资源，但 YAML 加载在启动期，改配置仍需重启）。

5.10 结构体中存在、默认 YAML 未写的键

源码 Config 结构还接受：generic.user_record_schema（记录字段校验 schema 文件）、selfservice 之外的 policy 扩展字段、ui.company_vat/city/country/address 等。YAML 解析为宽松模式，未知键忽略——升级版本时旧 YAML 直接兼容。

六、配置变更与生效方式

七、排障实录

实录 1：BUNKER_PORT 环境变量不生效

见第一节实测。根因是 loadService() 先 ReadEnv 后 ReadConfFile，YAML 显式键覆盖环境变量。解法：改 YAML 的 server.port，而不是注入环境变量。

实录 2：restart 后 HTTPS 状态残留

• 现象：从 compose 中删除 certs 挂载并执行 docker compose restart databunker 后，服务仍是 Open HTTPS listener，HTTP 请求收到 Client sent an HTTP request to an HTTPS server.。
• 根因：restart 只重启进程，不重建挂载；旧证书文件仍在服务视图内，"存在即启用"逻辑继续走 TLS。
• 解法：docker compose up -d --force-recreate databunker。实测重建后恢复 Open HTTP listener 0.0.0.0:3000，curl http://localhost:8134/v1/status 返回 OK。

实录 3：主密钥格式错误快速失败

Error: Master key length is wrong（长度≠48）与 Error: Failed to decode master key（非 hex）——均发生在启动期且进程直接退出，服务不会带病运行。检查 generate-pgsql-env-files.sh 生成值是否被截断/混入换行。

八、常见问题

Q1：想禁用匿名创建用户改哪里？ generic.create_user_without_access_token: false。官方默认值是 true（面向注册场景），内部系统建议关闭。

Q2：POST /v1/users 返回 Access denied 是坏了吗？ 不是，是安全默认值。list_users 默认 false；开启后返回的 private 字段是 base64 明文编码（实测），请仅作为受控导出通道使用。

Q3：审计表会无限膨胀吗？ 有 policy.max_audit_retention_period（官方 YAML 默认 6 个月）+ 每 10 分钟清理任务兜底；也可 disable_audit: true 整体关闭（合规场景慎用）。

Q4：能否只改环境变量不动 YAML？ 密钥与数据库连接类（第三节的 DATABUNKER_*/PGSQL_*/MYSQL_*）可以且必须这样；行为类开关受第一节优先级规则限制，多数只能改 YAML。

Q5：配置里设了弱主密钥会被拒吗？ 只校验格式（48 hex），不校验熵。请用官方脚本或 /dev/urandom 生成，勿手编。