Plausible 配置参数详解

‍‍​​‌​> 目标：逐个讲清 Plausible CE 的核心配置参数：怎么查看生效值、改哪些文件、每个参数改值后应用行为如何变化。本文所有 "改值 → 重启 → 行为对比" 均在实际部署环境实测（实测版本 Plausible CE v3.2.1），回显照抄；部署过程见《Plausible Docker Compose 部署指南》。

一、环境信息

二、参数查看与修改

① 查看生效值（最可靠，运行时真实配置）：

# 服务环境变量（在应用服务内执行，含默认值展开）
printenv | sort

# 应用运行时某项配置（应用内置 CLI：plausible rpc，以 BASE_URL 展开结果为例）
/app/bin/plausible rpc \
  'IO.inspect(Application.get_env(:plausible, PlausibleWeb.Endpoint)[:url])'

📌 以上命令均在应用服务内执行（应用自带 plausible 命令行，支持 rpc 直达运行时）。

实测回显（BASE_URL=http://192.168.146.128:13910 时）：

[path: "", host: "192.168.146.128", scheme: "http", port: 13910]

② 修改方法（编排部署）：编辑 ~/plausible-lab/.env（或编排文件 compose.yml 的 environment: 段）→ 执行 compose up -d 重建应用服务。

⚠️ 实测关键结论：compose restart 不会重新读取 .env（变量在服务创建时注入），必须 compose up -d 触发服务重建。本文所有改值实验均按此执行。

③ 官方参数总表：https://github.com/plausible/community-edition/wiki/configuration

三、网络监听参数

3.1 LISTEN_IP

• 默认值：0.0.0.0（官方源码 runtime.exs）
• 作用：应用 HTTP 监听地址。保持默认即可，对外暴露用编排的端口映射控制。

3.2 HTTP_PORT / HTTPS_PORT

• 默认值：80 / 443（官方源码 runtime.exs）
• 作用：不是监听端口，而是生成外部链接（埋点脚本、邮件链接）时使用的对外端口。
• 实测：监听端口由编排端口映射决定（13910:8000 → 应用监听 8000）；BASE_URL 中已含 :13910 时，埋点脚本地址与 BASE_URL 一致（实测安装页给出的脚本为 http://192.168.146.128:13910/js/pa-IhP1_HJykpkMhQKcTIukr.js）。端口意图仅在没有指定端口的域名 BASE_URL（如 https://stats.example.com）时需要额外设置。

3.3 端口映射（编排层）

实测配置 ports: "13910:8000"：宿主 13910 → 应用内 8000；compose ps 实测回显 0.0.0.0:13910->8000/tcp, [::]:13910->8000/tcp。修改对外端口改这里，不改 HTTP_PORT。

四、安全与访问控制参数

4.1 SECRET_KEY_BASE（⚠️ 一次变更全员掉线）

• 默认值：无（必填，缺失时启动失败）
• 生成：openssl rand -base64 48
• 作用：会话 cookie 的签名/加密密钥。
• 实测（改值 → up -d → 行为对比）：保持旧登录会话 cookie 不变，将 SECRET_KEY_BASE 换成新值并 compose up -d，访问 /sites：

GET /sites(旧会话) -> 401 -> http://127.0.0.1:13910/login

换回原值并重建后，同一会话恢复可用（实测 GET /sites -> 200）。结论：变更即全量登出；该密钥一旦投产不可随意轮换，且必须妥善保管。

4.2 DISABLE_REGISTRATION（默认值实测：invite_only）

• 官方 Wiki 写的默认：true
• 实测结论：v3.2.1 源码 runtime.exs 实际默认为 invite_only（仅受邀注册），这是文档与代码不一致的重要发现。
• 实测三态对比（每次改值后 compose up -d，全新未登录会话）：

📌 全新实例的首个账号在默认 invite_only 下仍可创建（首次启动放行）；之后的新用户需管理员邀请。开放自助注册请显式设 DISABLE_REGISTRATION=false。

4.3 ENABLE_EMAIL_VERIFICATION

• 默认值：false
• 作用：开启后新注册用户必须输入邮件验证码激活。
• 实测（true → 注册 → 行为对比）：设 ENABLE_EMAIL_VERIFICATION=true 并 up -d 后：
  • 新建用户 verif@example.com 注册流程走到「输入激活码」页（页面提示查收邮件）；
  • 由于默认 SMTP 不可用（见 6.1），验证码邮件发送失败，用户停留在未激活状态，无法进入仪表盘；
  • 恢复 false 后该限制消失。
• 结论：开启前必须先配好可用 SMTP（第 6 章），否则用户卡死在激活环节。

4.4 TOTP_VAULT_KEY

• 默认值：无（可选；启用 2FA 时需要）
• 实测故障注入：编排透传了一个 37 字节的 Base64 值启动应用，实测启动即崩溃：

ERROR! Config provider Config.Reader failed with:
** (ArgumentError) errors were found at the given arguments:

  * 1st argument: invalid option: 4

    12:13:43.677 [error] GenServer :'Elixir.Config.Provider.Agent' terminating

💡 追因：runtime.exs 中该值被 Base.decode64!() 后作为 :crypto 选项解析，要求恰好 32 字节；37 字节解码后内容被当成非法选项。正确生成方式：openssl rand -base64 32（32 字节）。未启用 2FA 可不设置。

五、数据库连接参数

5.1 DATABASE_URL

• 默认值：postgres://postgres:postgres@plausible_db:5432/plausible_db（官方编排服务名）
• 作用：元数据库（用户/站点/API Key 等）连接串。
• 实测库名确认：应用侧打印 database: "plausible_db"；库内表 users/sites/teams/api_keys 等。自建 PostgreSQL 时改成实际连接串即可。

5.2 CLICKHOUSE_DATABASE_URL

• 默认值：http://plausible_events_db:8123/plausible_events_db（HTTP 接口 8123，库名 plausible_events_db）
• 实测故障注入：改为错误端口 http://plausible_events_db:9999/plausible_events_db 并 up -d：
  • 应用启动命令 /entrypoint.sh db createdb 阶段即无法就绪，plausible 服务进入反复重启；
  • curl http://127.0.0.1:13910/api/health 无响应（服务未起来）；
  • 恢复正确 URL 并 up -d 后，健康检查恢复：

{"sessions":"ok","postgres":"ok","clickhouse":"ok","sites_cache":"ok"}

📌 注意是 HTTP 协议（8123 端口），不是 ClickHouse 原生 TCP 9000。

5.3 CLICKHOUSE_FLUSH_INTERVAL_MS / CLICKHOUSE_INGEST_POOL_SIZE

• 默认值：5000 / 5（官方源码 runtime.exs）
• 作用：采集事件先入应用内存缓冲，按该间隔批量刷入 ClickHouse；连接池控制并发写。
• 实测现象：向 /api/event 发送事件后立即查 events_v2 可能查不到，等待约 5 秒后再查即出现——与默认 5000ms 刷盘间隔吻合（实测发送 3 条 pageview，约 30 秒内仪表盘实时访客从 0 变 3）。中小站点不建议调整；调小会提高实时性但增加小批次写入开销。

六、注册与邮件认证参数

6.1 MAILER_EMAIL

• 默认值：未设置时按 BASE_URL 主机名自动拼接为 plausible@<host>。
• 实测故障注入：BASE_URL=http://192.168.146.128:13910 且未显式设置时，触发需要发信的流程（注册验证），应用日志实测报错：

Expected "at" at position 20 in "plausible@192.168.146.128"

原因：IP 带端口的主机名被拼进邮箱本地域，192.168.146.128:13910 不是合法域名，SMTP 库直接拒绝。修复：显式设置 MAILER_EMAIL=analytics@example.com 这类合法地址。

6.2 SMTP_* 系列

• 实测结论：默认配置（Bamboo.Mua + localhost:25）在未部署本地 MTA 的服务器上必然发信失败（连接拒绝），涉及注册验证、忘记密码、邮件报表等全部邮件功能；生产环境必须配置外部 SMTP。SMTP 相关变量同样遵守「改 .env → up -d」的生效规则。

6.3 双因素（2FA）相关

TOTP_VAULT_KEY 见 4.4；启用 2FA 后恢复码用该 key 加密存储，启用后不可再更换（否则已存恢复码无法解密）。

七、地理信息参数

默认 Purchased MaxMindDB 且无 key 时，地理维度（国家/城市）不会有数据（应用日志会出现下载失败提示），不影响其余统计；改 IP_GEOLOCATION_DB=ep offline 即可用免key离线库（来源：官方配置 Wiki）。

八、性能与资源参数

• ClickHouse 内存限制：本环境在编排层 mem_limit: 512m 限流，资源统计实测常驻 217.3MiB / 512MiB（应用 399.3MiB、PostgreSQL 92.4MiB）；配合官方 low-resources.xml/default-profile-low-resources-overrides.xml 降低后台任务内存。实测中小流量完全够用。
• 聚合缓存：仪表盘/Stats API 查询带窗口级缓存，同窗口重复查询直接命中（实测连续同参数请求返回相同 JSON）；排查数据问题时可换个时间窗口或等待窗口滚动。
• 采集链路：CLICKHOUSE_FLUSH_INTERVAL_MS=5000 决定事件落库延迟（实测 5.3）。

九、常见问题（FAQ）

Q1：改了 .env 不生效？

compose restart 不重读 .env，用 compose up -d 重建服务（本文所有实验均实测验证）。

Q2：改了 SECRET_KEY_BASE 后所有用户掉线？

预期行为（实测 4.1），重新登录即可；不建议随意轮换。

Q3：注册页 302 跳登录，没有注册表单？

默认 invite_only（实测 4.2），设 DISABLE_REGISTRATION=false 后 up -d。

Q4：邮件发不出去 / 日志报 Expected "at" at position ...？

未显式设置 MAILER_EMAIL 且 BASE_URL 是 IP 形式，拼出非法发件人地址（实测 6.1）；设置合法 MAILER_EMAIL 并配置外部 SMTP（6.2）。

Q5：/js/script.js 与 /js/pa-<随机串>.js 有什么区别？

实测两者均返回 200：/js/script.js 为通用兼容路径，/js/pa-<随机串>.js 为安装页按站点生成的地址（更利于代理缓存），埋点用哪个都行，data-domain 参数务必匹配站点域名。

Q6：CLICKHOUSE_DATABASE_URL 配错端口会怎样？

应用起不来（实测 5.2），健康检查无响应；注意用 HTTP 8123 而非原生 TCP 9000。

十、参考链接

• 配置 Wiki（官方全量参数表）：https://github.com/plausible/community-edition/wiki/configuration
• 源码默认值（本文大量默认值出处）：https://github.com/plausible/analytics/blob/v3.2.1/config/runtime.exs
• 官方自托管文档：https://plausible.io/docs/self-hosting（2026-10-18 抓取）
• 本系列：《Plausible 介绍与选型指南》《Plausible Docker Compose 部署指南》《Plausible API 使用详解》