Keila 0.30.3 配置参数详解

Keila 0.30.3 环境变量配置详解：必填项与启动报错、数据库/Web 端点/SMTP 邮件/管理员种子/验证码/文件存储/运行开关逐项说明，均附实测回显与生效验证方法。

KeilaKeila邮件服务邮件列表PostgreSQL2026/10/26

Keila 0.30.3 配置参数详解

一、配置机制总览

Keila 0.30.3 的全部配置通过环境变量完成，没有配置文件。实现在 config/runtime.exs：每次应用启动（含 bin/keila start/daemon/eval）时读取环境变量并构建运行时配置。由此推出三条使用规则：

  1. 修改环境变量后必须重启进程才生效；
  2. 必填项在启动时强校验：缺失直接打印错误并退出（System.halt(1)），配置错误不可能「带病运行」；
  3. 可选项缺失会打印 [warning] 行但服务照常启动，默认值兜底。

本文所有行为均在 Debian 12 源码部署的 Keila 0.30.3 上实测（部署过程见《Debian 12 安装 Keila 0.30.3 指南》，环境变量写入 env 文件供启动脚本 source）。

二、必填变量

2.1 DB_URL（数据库连接串）

格式 postgres://user:password@host:port/database。Keila 把业务表与 Oban 作业队列都存在这个库里，是唯一的外部服务依赖。

实测缺失时的启动报错：

2026-10-26T06:49:51.603 [error] could not fetch environment variable "DB_URL" because it is not set
2026-10-26T06:49:51.604 [error] You must provide the DB_URL environment variable in the format:
postgres://user:password/database

数据库组还有三个可选变量控制 TLS 与 schema：

变量默认说明
DB_ENABLE_SSLfalse设 true 启用 PostgreSQL 连接 TLS
DB_VERIFY_SSL_HOSTTRUE是否校验服务器证书主机名（自签证书场景配合 DB_CA_CERT 或显式设 false）
DB_CA_CERT空PEM 格式 CA 证书内容（整串 PEM 文本直接写进变量，非路径）
DB_SCHEMA空数据库 schema 前缀（多实例共用一个库时隔离用，同时作用于 Oban 队列表）

2.2 SECRET_KEY_BASE（会话签名密钥）

至少 64 字符的强随机串，参与登录会话签名，并派生 LiveView signing salt。官方推荐的生成方式：

head -c 48 /dev/urandom | base64

实测缺失时的启动报错（尾部）：

You must set SECRET_KEY_BASE.

This should be a strong secret with a length
of at least 64 characters.

One way to create a strong secret is running the following command:
head -c 48 /dev/urandom | base64

必须固化：该值还派生联系人 Hashid 盐（未显式设置 HASHID_SALT 时，盐 = sha256(SECRET_KEY_BASE <> "hashid_salt")），中途更换会让登录会话全部失效、联系人的外部标识全部变化。

2.3 MAILER_*（系统邮件通道）

系统邮件（注册激活、密码重置）的发信通道。MAILER_TYPE 默认 smtp（0.30.3 生产可用类型即 SMTP），其中两个必填：

  • MAILER_SMTP_HOST：SMTP 中继主机；
  • MAILER_SMTP_FROM_EMAIL：系统邮件发件人地址。

实测缺失 MAILER_SMTP_HOST 时的启动报错（尾部）：

You must configure a mailer for system emails.

Use the following environment variables:
- MAILER_TYPE (defaults to "smtp")
- MAILER_SMTP_HOST (required)
- MAILER_SMTP_USER
- MAILER_SMTP_PASSWORD (required unless MAILER_SMTP_AUTH_METHOD=none)
- MAILER_SMTP_PORT (optional, defaults to 587)
- MAILER_SMTP_AUTH_METHOD (optional, defaults to "auto", options: "password", "none", "auto")
- MAILER_SMTP_TLS_MODE (optional, defaults to "auto", options: "tls", "starttls", "none", "auto")

逐项说明：

变量默认说明
MAILER_SMTP_USER取 FROM_EMAILSMTP 用户名
MAILER_SMTP_PASSWORD空SMTP 密码（AUTH_METHOD=none 时可省）
MAILER_SMTP_PORT587SMTP 端口
MAILER_SMTP_AUTH_METHODautopassword 强制认证 / none 强制匿名 / auto 由适配器协商
MAILER_SMTP_TLS_MODEautotls 隐式 TLS(465) / starttls 明文升级(587) / none 不加密 / auto 协商
MAILER_ENABLE_SSL / MAILER_ENABLE_STARTTLSfalse旧变量，已被 MAILER_SMTP_TLS_MODE 取代，仅在后者未设时生效

auto 模式下还会启用证书校验（tls_certificate_check），对内网自建中继没有受信证书时，要显式设 MAILER_SMTP_TLS_MODE=none。实测本文用内网测试收信端的配置即：

export MAILER_SMTP_HOST="10.89.60.3"
export MAILER_SMTP_PORT="1025"
export MAILER_SMTP_FROM_EMAIL="newsletter@keila.local"
export MAILER_SMTP_AUTH_METHOD="none"
export MAILER_SMTP_TLS_MODE="none"

三、Web 端点变量

变量默认说明
PORT4000应用 HTTP 监听端口
URL_HOST空对外访问主机名/地址，用于生成邮件内链接与站点 URL
URL_PORT取 PORT，URL_SCHEMA=https 时 443对外端口
URL_SCHEMA端口 443 → https，否则 http对外协议
URL_PATH/部署在子路径时设置（如反代 /keila/）
HASHID_SALT由 SECRET_KEY_BASE 派生联系人 Hashid 盐

URL_HOST 缺失时不会失败，只警告并以 http://localhost 对外（实测回显，见下节启动日志块）。反代场景的要点：PORT 是应用真实监听端口，URL_* 是用户浏览器看到的地址，两者经常不同。

四、管理员与初始化种子

变量默认说明
KEILA_USERroot@localhost首次初始化创建的实例管理员邮箱
KEILA_PASSWORD随机生成管理员密码

三个实测得出的硬约束：

  1. 种子只在数据库为空时执行一次（守卫条件是 groups 表为空；已初始化的库再次启动日志会打 Database already populated, not populating database.），所以 KEILA_USER/KEILA_PASSWORD 必须在首次启动前设置，错过只能清库重来；
  2. 密码最少 10 个字符——User changeset 硬校验 password, min: 10，8 位的 q1w2e3r4 不通过，实测使用 q1w2e3r4q1；
  3. 未设 KEILA_USER 时会以 root@localhost 建号并把随机密码打印在启动日志的 warning 行：
[warning] KEILA_USER not set. Creating root user with email: root@localhost
[warning] KEILA_PASSWORD not set. Setting random root user password: <随机串>
[info] Created root user with admin@keila.local

首次启动自动跑完全部数据库迁移（约 30 张表）再执行种子，日志依次出现 Running ... change/0 forward、Migrations already up（二次启动）、Created root user with <邮箱>。

五、验证码变量

注册、登录等表单默认挂 hCaptcha，相关变量：

变量说明
CAPTCHA_SITE_KEY（或 HCAPTCHA_SITE_KEY）验证码站点密钥
CAPTCHA_SECRET_KEY（或 HCAPTCHA_SECRET_KEY）验证码服务端密钥
CAPTCHA_PROVIDERhcaptcha（默认）或 friendly_captcha
CAPTCHA_VERIFY_URL校验接口（默认 hCaptcha 官方）
CAPTCHA_SCRIPT_URL前端脚本地址

未配置时不会失败，但启动日志会警告，且 Keila 回退到 hCaptcha 的 staging 密钥对——验证码可通过任意响应，生产环境等于没有验证码，必须配置：

[warning] Captcha not configured.
Keila will fall back to using hCaptcha's staging configuration.

六、文件存储变量

变量默认说明
USER_CONTENT_DIR./uploads用户内容（联系人头像、Campaign 附件等）的本地存储目录，相对路径相对 release 工作目录
USER_CONTENT_BASE_URL空用独立域名/服务提供用户内容时设置；设置后应用不再自己对外提供这些文件

缺失时的警告（两行分别对应目录与独立域名两项）：

[warning] You have not configured a directory for user uploads.
[warning] You have not configured a separate URL for untrusted content uploaded by

开源版只有本地文件存储适配器；USER_CONTENT_BASE_URL 的安全意义是让不可信的用户内容走独立域名，与应用主域隔离（cookie 不随请求发送）。

七、运行行为开关

以下变量均为「设了就开/关」的布尔开关（大小写不敏感的 true/1，或仅非空即生效的见注明）：

变量语义
DISABLE_REGISTRATION非空且非 0/false 即生效：关闭 Web 界面自助注册
DISABLE_SENDER_CREATION关闭普通用户自建发件人（只能用管理员共享的发件人）
ENABLE_QUOTAS需显式 true/1：启用账户发送配额
DISABLE_UPDATE_CHECKS关闭版本更新检查的外呼
DISABLE_TZDATA_UPDATES关闭 IANA 时区数据自动更新
DISABLE_PRECEDENCE_HEADER关闭投递邮件的 Precedence: bulk 头
MESSAGE_RETENTION_DAYS数字：已发消息正文的保留天数（省空间）

DISABLE_REGISTRATION 实测生效验证——设为 true 重启后，/auth/register 页面从注册表单变为提示页：

curl -s http://192.168.146.131:8139/auth/register | grep -oE "Registration disabled\.|Please contact an administrator\."

实测回显：

Please contact an administrator.
Registration disabled.

DISABLE_UPDATE_CHECKS 与时区更新的外呼行为可从启动日志观察：不设时每次启动有 Tz is fetching the latest IANA time zone data version at https://data.iana.org/time-zones/tzdb/version 行，离线服务器建议设 DISABLE_TZDATA_UPDATES=true 与 DISABLE_UPDATE_CHECKS=true 消除对外依赖。

八、日志变量

LOG_LEVEL 支持 info（默认）、error、debug。

实测注意事项：设 LOG_LEVEL=error 后，通过 bin/keila eval 检查确认环境变量已读入且 :logger 的 Application env 已置为 :error（{"error", :error}），但守护进程启动期的 [info] 行（迁移、Bandit 绑定等）仍照常写入日志——Logger 的运行时级别在 config provider 评估前已初始化，0.30.3 的该项配置对启动期日志未产生肉眼可见的抑制效果。依赖它降噪的读者请以自己的实测为准。

九、启动日志诊断（生效验证方法）

一次干净的启动，日志会依次给出所有可选项的生效状态。下面是实测中最简配置（仅必填项）下的完整启动块，可直接当诊断清单用：

2026-10-26T06:50:13.269 [info] Loading 148 CA(s) from :otp store
2026-10-26T06:50:13.270 [warning] Captcha not configured.
2026-10-26T06:50:13.270 [warning] You have not configured a Hashid salt. Defaulting to
2026-10-26T06:50:13.270 [warning] You have not configured the application URL. Defaulting to http://localhost.
2026-10-26T06:50:13.270 [warning] You have not configured a directory for user uploads.
2026-10-26T06:50:13.270 [warning] You have not configured a separate URL for untrusted content uploaded by
2026-10-26T06:50:13.270 [info] PORT environment variable unset. Running on port 4000.
2026-10-26T06:50:13.295 [info] Migrations already up
2026-10-26T06:50:13.300 [info] Database already populated, not populating database.
2026-10-26T06:50:13.308 [info] Running KeilaWeb.Endpoint with Bandit 1.12.0 at 0.0.0.0:4000 (http)
2026-10-26T06:50:13.309 [info] Access KeilaWeb.Endpoint at http://localhost:4000

读法：每条 [warning] 都是一个未配置的可选项及其兜底默认值；Running KeilaWeb.Endpoint ... at 0.0.0.0:4000 是实际监听端口（PORT 生效点）；Access KeilaWeb.Endpoint at http://localhost:4000 是 URL_* 生效点（上例未配置 URL_HOST，所以站点地址回落为 localhost——这就是邮件内链接会指向 localhost 的原因）。

十、常见问题

10.1 服务反复重启，日志只有一句 must provide

必填变量四缺一：DB_URL、SECRET_KEY_BASE、MAILER_SMTP_HOST、MAILER_SMTP_FROM_EMAIL。完整报错文本会指明缺哪个，按上文逐项补齐。

10.2 改了环境变量没生效

runtime.exs 只在启动时评估一次，改完必须重启进程。另外注意 env 文件的加载方式：systemd 用 EnvironmentFile=，shell 脚本用 source，不要混用两种机制导致部分变量没进环境。

10.3 邮件内链接全是 localhost

URL_HOST 未设置，回落 http://localhost（见上文启动日志 Access KeilaWeb.Endpoint at http://localhost:4000）。设置后重启即可。

10.4 密码重置邮件没发出

MAILER_* 指向的中继不可达、认证参数不匹配，或 TLS 模式与中继不兼容。先用 MAILER_SMTP_TLS_MODE=none 排除证书因素；中继需要认证时按 AUTH_METHOD=password 补 MAILER_SMTP_USER/PASSWORD。

10.5 想用环境变量直接建管理员没生效

KEILA_USER/KEILA_PASSWORD 只在数据库为空的首次启动时被种子读取。已初始化的实例要换管理员，进 Web 界面用现有管理员在 /admin/users 管理，或清库重来。

10.6 SECRET_KEY_BASE 可以随便换吗

不可以。会话签名与 Hashid 盐都派生自它，更换即全员掉线、联系人外部标识变化。首次部署生成后固化进配置。

十一、参考链接