Mobilizon 5.2.4 配置参数详解

目标：把 Mobilizon 5.2.4 的配置体系一次讲透——三层配置模型（.env 环境变量 → config.exs → 管理 UI 运行时设置）的优先级、Docker 镜像内 263 行 config.exs 模板暴露的全部 MOBILIZON_* 环境变量、官方 configure/reference 文档的全参数域语义，以及"改参 → 重启 → 验证"的实测闭环。所有实测基于 2026-11-02 部署的 kaihuri/mobilizon:5.2.4-amd64 实例（宿主端口 8160）。部署步骤见站内文章 《Mobilizon Docker Compose 部署指南》。

一、三层配置模型与优先级

Mobilizon 的配置自下而上有三层，上层覆盖下层：

关键认知（官方 reference 反复出现的措辞）：:name、:description、:registrations_open、:languages 等 config 项都是 "fallback … if not configured into the admin UI"——即文件配置只是兜底默认值，管理员在 UI 里设置过之后，改 .env 将不再体现到前台。排查"改了没生效"先查这一层。

验证生效值的权威入口（实测）：管理员 JWT 调 GraphQL config 查询：

curl -s http://127.0.0.1:8160/api -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"{config{name description registrationsOpen federating demoMode version}}"}'
# → {"name":"C1 ParamTest Renamed","registrationsOpen":false,...,"version":"5.2.4"}

纠偏：GraphQL 里的 instance(domain: ID!) 查询是查远端联邦实例的（instances 表存已知远端域），查本地域名实测返回 404 not_found，且 instances 列表本地实例并不在其中（空表 total=0）；本地实例生效配置请用 config（需管理员登录态，匿名查询被拒 unauthenticated）。

二、改参 → 重启 → 验证 实测闭环

以 MOBILIZON_INSTANCE_NAME 与 MOBILIZON_INSTANCE_REGISTRATIONS_OPEN 为例（2026-11-02 实测）：

# 1. 改 .env
#    MOBILIZON_INSTANCE_NAME=C1 ParamTest Renamed
#    MOBILIZON_INSTANCE_REGISTRATIONS_OPEN=false
# 2. 重建容器（注意：restart 不够，env_file 变更需 up -d 重建）
docker compose up -d mobilizon
# 3. 三点验证
curl -s http://127.0.0.1:8160/ | grep '<title>'
#   → <title>C1 ParamTest Renamed - Mobilizon</title>
curl -s http://127.0.0.1:8160/.well-known/nodeinfo/2.0 | jq .openRegistrations
#   → false
#   GraphQL config 查询 → name/registrationsOpen 同步为新值（见上）
# 4. 回滚 .env → up -d → title 恢复 "G25 Mobilizon Test"、openRegistrations=true

结论：env 层参数改后必须 docker compose up -d（触发 recreate），docker compose restart 不会重读 .env；本例未在 UI 覆盖过 name/registrations，故 env 值直接透传到前台 title、nodeinfo 与 config 三处，行为一致。

三、Docker 镜像 .env 全键表

下表逐行取自镜像内 /etc/mobilizon/config.exs（263 行）的 System.get_env 调用，是 env 键的权威清单（官方 env.template 未列全）。格式：env 键 →（config 落点，默认值）。

3.1 实例与端点

3.2 数据库与日志

3.3 邮件 SMTP

发信验证：docker compose exec mobilizon mobilizon_ctl maintenance.testemails（实测存在，官方 CLI 页未列）。

3.4 地理编码与地图

3.5 上传、导出、时区、推送

3.6 错误上报与分析

四、config.exs 高级参数域（env 未暴露，需挂卷覆盖）

覆盖方法：docker cp mobilizon-mobilizon-1:/etc/mobilizon/config.exs ./config.exs → 编辑 → compose 挂载到同路径 → up -d。重要域（源自官方 configure/reference，2026-09-18 版）：

• :instance 补充项：extra_categories（%{id: :protest, label: "Protest"} 追加活动分类）；upload_limit/avatar_upload_limit/banner_upload_limit；remove_orphan_uploads + orphan_upload_grace_period_hours（孤儿上传周期清理，配合 media.cleanorphan）；remove_unconfirmed_users + unconfirmed_user_grace_period_hours；activity_expire_days + activity_keep_number（群组活动时间线保留策略）；duration_of_long_event（天，0=不区分长短活动）。
• :instance :groups/:events：enabled: false 可整体关闭群组或活动功能。
• :instance :media_proxy：enabled/proxy_opts/redirect_on_failure/max_body_length/max_read_duration/follow_redirect——代理远程图片防泄漏 IP。
• :instance :html_hooks：app_index_html_head_first/head_last/body_first/body_last 注入原始 HTML（自定义样式/脚本/统计代码），值可以是任意返回字符串的 Elixir 表达式（如 File.read!("/path/snippet.html")）。
• :instance :restrictions：only_admin_can_create_groups、only_groups_can_create_events（强制活动必须挂群组——实测个人代发群组活动本就会被 GraphQL 拒绝，此开关把限制前移到创建入口）。
• Endpoint :http_security：enabled/sts/sts_max_age/csp_policy/referrer_policy——安全头与 CSP 主开关。
• Uploads :uploader/:filters：Uploader.Local 之外可配远程；过滤器 Dedupe（哈希去重）与 Optimize（ExOptimizer 压缩）；allow_list_mime_types、link_name。
• 认证：Mobilizon.Service.Auth.Authenticator 可切 LDAPAuthenticator（找不到用户自动回落默认库认证）；:auth oauth_consumer_strategies 配 OAuth 登录。
• Federation :activitypub：actor_stale_period（远端 actor 刷新周期）、actor_key_rotation_delay（密钥轮换延迟）、sign_object_fetches（签名拉取请求）。
• 匿名参与 :anonymous：participation allowed + validation（email.enabled/confirmation_required、captcha.enabled）；reports.allowed。
• Oban：队列 search/mailers/background/default（实测日志 Oban peer became leader）；周期任务 BuildSiteMap、RefreshGroups、CleanOrphanMediaWorker、CleanUnconfirmedUsersWorker。
• 富媒体：rich_media parsers（OEmbed/OGP/TwitterCard/Fallback）；resource_providers/external_resource_providers。
• 反垃圾（两选一，不能同时启用）：
  • Akismet：config :mobilizon, Mobilizon.Service.AntiSpam, service: Mobilizon.Service.AntiSpam.Akismet + Akismet key: "…"；
  • Keyword（5.2.4 新增）：service: Mobilizon.Service.AntiSpam.Keyword + Keyword keywords: ["casino","viagra","buy now"]。

五、高频配方速查

六、坑与纠偏清单

1. UI 优先：name/description/registrations 等是 fallback，UI 配过之后 env 改动无效（第一节）。
2. up -d vs restart：.env 变更必须 recreate（第二节实测）。
3. 布尔语义严格：*_OPEN/SSL/ENABLED 类只认字符串 "true"，TRUE/1/yes 都算 false。
4. LOGLEVEL 非法值静默回落 error；GEOSPATIAL_SERVICE 非法值直接崩（模板一个有兜底、一个没有）。
5. instance(domain:) 不是本地配置查询（第一节纠偏）；本地生效值用 config（admin token）。
6. SECRET_KEY 改动 = 全员登出：所有 JWT 立即失效，属高影响操作。
7. 地图瓦片/CSP/媒体代理/HTML hooks/认证集成均无 env 入口，必须走 config.exs 挂卷路径。

取证说明：环境变量表逐行核对自 5.2.4 镜像内 config.exs 模板；参数域语义核对自 docs.mobilizon.org configure/reference（Last update 2026-09-18）；改参闭环与 config/instance/instances 查询行为均为 2026-11-02 实测。CLI 工具详解见同专栏《Mobilizon 5.2.4 常用 CLI 命令与工具详解》。