hitobito 2.10 配置参数详解

目标：系统梳理 hitobito 2.10 的配置通道（环境变量文件、初始化代码、wagon 设置）与全部关键参数的含义、默认值和本实例实测生效值，给出生产配置模板。本文全部命令与回显在已部署 hitobito 2.10.0 的 Ubuntu 22.04 服务器（应用目录 /opt/hitobito/app，本实例环境文件 /etc/hitobito/hitobito.env，服务地址 http://localhost:8152）实测。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• 应用：hitobito core 2.10.0（cat VERSION 实测），wagon generic（rake wagon:list 实测）
• 运行时：Ruby 3.3.13、Rails 8.0.5、Bundler 4.0.13
• 依赖服务：PostgreSQL 16（主机 postgres，库 hitobito_development）、Redis 8（主机 redis，库 1）
• 应用目录：/opt/hitobito/app；本实例环境文件：/etc/hitobito/hitobito.env
• 服务地址：http://localhost:8152（由 RAILS_HOST_NAME 决定，实测生效）
• 演示账号：admin@hitobito.ch / q1w2e3r4

二、前置条件

本文命令分两类，均可在运行中的实例上独立执行：

1. 应用目录内命令：cd /opt/hitobito/app 后执行 bundle exec rake / bundle exec rails 系列命令，要求 Ruby 依赖已安装完毕（bundle exec rails runner 能正常输出即满足，本文实测环境如此）；
2. HTTP 验证命令：curl 访问本实例 http://localhost:8152。

参数生效的统一前提是应用进程重启：环境变量与初始化器都在进程启动时读取，改完不重启不生效（见"常见问题"7.2 实测）。

三、参数查看与修改方式

3.1 环境文件（主通道）

hitobito 应用侧参数几乎全部来自 RAILS_*/HITOBITO_* 等环境变量（官方运维文档 doc/operator/01_deployment.md 给出权威清单）。本实例环境文件实测内容（节选，另有 1 项开发环境专用开关不在本文范围）：

RAILS_DB_ADAPTER=postgresql
RAILS_DB_HOST=postgres
RAILS_DB_PORT=5432
RAILS_DB_USERNAME=hitobito
RAILS_DB_PASSWORD=hitobito
RAILS_DB_NAME=hitobito_development
RAILS_ACTIONCABLE_REDIS_URL=redis://hitobito_redis@redis:6379/1
RAILS_HOST_NAME=localhost:8152
RAILS_MAIL_DOMAIN=localhost
RAILS_MAIL_DELIVERY_METHOD=smtp
RAILS_MAIL_DELIVERY_CONFIG=address: mailcatcher, port: 1025
ANNOTATERB_SKIP_ON_DB_TASKS=1
RAILS_LOG_TO_STDOUT=1
DISABLE_SPRING=true

修改方式：编辑该文件后重启应用进程。本实例实测一次"改 devise.rb + 重启"的完整生效周期：重启后 /healthz 约 165 秒恢复 200。

3.2 验证参数是否生效

不看配置文件、直接验证运行时行为，是本实例实测的三种判定：

# RAILS_HOST_NAME 生效：未登录跳转的 host 即该参数值
$ curl -s -I http://localhost:8152/ | grep -i '^location'
location: http://localhost:8152/de/users/sign_in

# 数据库参数生效：能连上并读出 schema 版本
$ bundle exec rake db:version
database: hitobito_development
Current version: 20260701094113

# 密钥类参数生成（SECRET_KEY_BASE 用）
$ bundle exec rails secret
1198ab6d94a0aa8d930ff6784aecfedf33384709f66446d2cc82f22763e0151b93d9c94d8e603ca02af0d324eb092efaa7545fee5213a9da6a8e03cbe6ea5126

rails secret 实测输出 128 位十六进制串，正是官方文档对 SECRET_KEY_BASE 的格式要求。

3.3 代码级参数（初始化器）

少数策略参数硬编码在 config/initializers/，不走环境变量。实测密码长度策略位置：

$ grep -n 'password_length' config/initializers/devise.rb
170:  config.password_length = 12..128

改动示例（本实例为演示账号 8 位口令临时放宽为 8..128）与默认值报错实测见"常见问题"7.1。同文件实测 config.email_regexp 为单 @ 校验。

3.4 配置自检任务

内置任务检查必需配置是否齐备（实测末行）：

$ bundle exec rake hitobito:check_config
...（逐项检查 SQL 与输出，实测节选）
✅ SelfRegistrationRoleTypes configured correctly

3.5 wagon 设置文件

组织级参数（如根用户邮箱 root_email）在 wagon 的 config/settings.yml；核心侧根用户亦可用 RAILS_ROOT_USER_EMAIL 指定。生产环境首次登录官方建议走"忘记密码"流程设置密码。

💡 技术拓展：Rails 应用参数通道对比——

通道	载体	适合	注意
环境变量（hitobito 主通道）	进程环境/env 文件	部署相关、多实例差异	启动时读取，改后需重启
Rails credentials（credentials.yml.enc）	master.key 加密 YAML	少量机密	与 ENV 混用易漏配
YAML 配置文件（wagon settings.yml）	仓库内文件	组织业务参数	随 wagon 版本管理
初始化器硬编码	代码	策略常量（如密码长度）	改动即代码变更，需重启

hitobito 实测采用"环境变量为主 + wagon YAML + 少量硬编码"三层结构，本文第四章按此归类。

四、参数总览

对应用 config/ 目录做 ENV 引用普查（实测命令）：

$ cd /opt/hitobito/app && grep -rhoE '\bENV\b[^A-Z]*[A-Z][A-Z0-9_]{2,}' config \
    | grep -oE '[A-Z][A-Z0-9_]{3,}' | sort -u
ADDRESSES_TOKEN AWS_REGION BUNDLE_GEMFILE ... PROMETHEUS_EXPORTER_HOST
PROMETHEUS_EXPORTER_PORT RAILS_ACTIONCABLE_REDIS_URL RAILS_AIRBRAKE_API_KEY
RAILS_BULK_MAIL_BATCH_TIMEOUT RAILS_BULK_MAIL_SIZE RAILS_CACHE_REDIS_CONFIG
RAILS_CACHE_REDIS_URL RAILS_DB_ADAPTER RAILS_DB_CHECKOUT_TIMEOUT RAILS_DB_NAME
RAILS_DB_POOL RAILS_DB_SCHEMA ... RAILS_HOST_SSL RAILS_LOG_LEVEL
RAILS_LOG_TO_STDOUT RAILS_MAIL_DELIVERY_CONFIG RAILS_MAIL_DELIVERY_METHOD
RAILS_MAIL_DOMAIN RAILS_MAIL_RETRIEVER_CONFIG RAILS_MAIL_RETRIEVER_TYPE
RAILS_MAX_THREADS RAILS_ROOT_USER_EMAIL RAILS_S3_ACCESS_KEY RAILS_S3_BUCKETNAME
RAILS_S3_ENDPOINT RAILS_S3_SECRET_KEY RAILS_SERVE_STATIC_FILES SECRET_KEY_BASE
SENTRY_DSN WEB_CONCURRENCY ...（输出节选，实测共 60 项应用相关变量）

按用途归类（默认值列取自官方运维文档与代码实测）：

解读：与多数 Rails 应用不同，hitobito 把收信（RAILS_MAIL_RETRIEVER_*）也作为一等配置——邮件列表的入站处理依赖它，官方文档标注"列表功能必需"；漏配不会让 Web 挂掉，只会让"发信正常、收信静默失败"，排查成本高，第五章 5.3 展开。

五、核心参数分类详解

5.1 数据库参数

生效验证实测（同 3.2）：bundle exec rake db:version 返回 database: hitobito_development 与 schema 版本 20260701094113。

⚠️ 注意：官方运维文档要求 PostgreSQL ≥ 16。实例规模实测：111 张表、generic 种子下 Person 224 / Group 29 / Event 79 / Role 225。

5.2 Redis 与缓存参数

实测 URL 中直接内嵌 Redis 密码（hitobito_redis@），对应 Redis 以 requirepass 启动的形态。Action Cable 承载页面实时推送，URL 配错表现为"页面能用但实时更新失效"。

💡 技术拓展：Rails 缓存后端选型——

后端	依赖	特点
Memcached	memcached 服务	纯 KV、无持久化、多实例共享
Redis	redis 服务	KV + 数据结构，可同时喂 Action Cable
memory_store	无	进程私有，多实例不一致
LRU/文件	无	开发用

hitobito 官方文档给的是"Memcached 或 Redis"二选一；本实例实测走 Redis（一份服务同时承担缓存与 Action Cable），Memcache 参数保持默认未启用。

5.3 邮件参数（发信与收信）

发信链路端到端实测：触发"忘记密码"（POST /de/users/password）返回 HTTP/1.1 303 See Other，SMTP 捕获端实测收到 1 封，主题 Anleitung für das Setzen Deines Passworts。健康检查还有邮件专项端点（rails routes 实测路由 healthz_mail GET /healthz/mail、healthz_truemail GET /healthz/truemail），可用于监控发信可用性与邮箱校验服务。

💡 技术拓展：邮箱地址校验库（healthz/truemail 端点对应的能力）——

方案	校验深度	特点
email_validator 类正则	语法	便宜，误判多
Truemail	语法 + MX/SMTP 探测	可配置验证等级，hitobito 实测内置端点
第三方验证 API	送达性	收费、有隐私合规问题

hitobito 实测走 Truemail（路由 healthz/truemail 存在），配合 catch-all 邮箱支撑邮件列表场景。

5.4 密钥与安全参数

⚠️ 注意：SECRET_KEY_BASE、数据库口令、SENTRY_DSN 等真实密钥不要明文落库存文档——生产以环境注入方式提供（如部署系统导出后再写 env 文件），本文演示值仅限实验实例。

5.5 进程、日志与监控参数

💡 技术拓展：Rails 应用进程模型——

模型	代表	并发单位	内存特征
多线程	Puma 单进程	线程（RAILS_MAX_THREADS）	省内存，受 GVL 限制
多进程+线程	Puma cluster（WEB_CONCURRENCY）	进程×线程	吞吐高，内存翻倍
应用服务器嵌入	Apache+Passenger（官方文档推荐）	进程按需	与 Apache 共生命周期

hitobito 官方生产文档推荐 Apache + Passenger；本实例运行时为 Puma（PORT/WEB_CONCURRENCY 参数即其环境变量），调这两组参数就是调并发容量。

5.6 业务与扩展参数

💡 技术拓展：Rails 附件存储后端（ActiveStorage）——

后端	依赖	适用
Disk	本地文件系统	单机、备份随应用盘
S3 兼容	RAILS_S3_* 参数	多实例共享、对象存储
GCS/Azure	对应 SDK	云厂商绑定

hitobito 代码实测同时引用 Disk 与 S3 参数组（RAILS_STORAGE_SERVICE 选择），多实例部署建议切 S3 兼容后端避免头像/附件分裂在各自本地盘。

六、生产配置模板

适用画像：16 GB 内存 / 4 vCPU / NVMe SSD、万级会员、单实例应用 + 独立 PostgreSQL/Redis（本实验实例为开发画像，标注"实测"的值为实验值，生产值请按模板注释替换）：

# /etc/hitobito/hitobito.env —— hitobito 2.10 生产示例（16GB/4vCPU/万级会员）
RAILS_ENV=production

# —— 必填：128 位 hex，生成命令 bundle exec rails secret（实测）
SECRET_KEY_BASE=${SECRET_KEY_BASE}          # 由部署系统注入，勿明文入库

# —— 数据库（实测值: hitobito_development；生产建议 hitobito_production）
RAILS_DB_ADAPTER=postgresql
RAILS_DB_HOST=db01.internal
RAILS_DB_PORT=5432
RAILS_DB_USERNAME=hitobito
RAILS_DB_PASSWORD=${RAILS_DB_PASSWORD}      # 密钥注入
RAILS_DB_NAME=hitobito_production
RAILS_DB_POOL=25                            # 默认未设；4vCPU×(线程+worker) 估算

# —— 主机与 TLS
RAILS_HOST_NAME=members.example.org
RAILS_HOST_SSL=true

# —— Redis（实测值: redis://hitobito_redis@redis:6379/1）
RAILS_ACTIONCABLE_REDIS_URL=redis://:${REDIS_PASSWORD}@redis01.internal:6379/1
MEMCACHE_SERVERS=memcache01.internal:11211  # 仅当缓存后端选 Memcached 时启用

# —— 邮件：发信走真实 SMTP；收信器为邮件列表必需
RAILS_MAIL_DELIVERY_METHOD=smtp
RAILS_MAIL_DELIVERY_CONFIG=address: smtp.example.org, port: 587, user_name: hitobito, password: ${SMTP_PASSWORD}, authentication: plain, enable_starttls: true
RAILS_MAIL_DOMAIN=members.example.org
RAILS_MAIL_RETRIEVER_TYPE=imap
RAILS_MAIL_RETRIEVER_CONFIG=host: imap.example.org, port: 993, ssl: true, username: list-catchall, password: ${IMAP_PASSWORD}

# —— 业务与可观测
HITOBITO_PROJECT=prod
HITOBITO_WALLETS_SYNC_SECONDS=180
RAILS_ROOT_USER_EMAIL=root@example.org
SENTRY_DSN=${SENTRY_DSN}
RAILS_LOG_TO_STDOUT=1
RAILS_SERVE_STATIC_FILES=true
WEB_CONCURRENCY=3
RAILS_MAX_THREADS=8

# —— 附件多实例共享时启用（否则走本地盘）
RAILS_STORAGE_SERVICE=s3
RAILS_S3_ENDPOINT=s3.internal
RAILS_S3_BUCKETNAME=hitobito
RAILS_S3_ACCESS_KEY=${RAILS_S3_ACCESS_KEY}
RAILS_S3_SECRET_KEY=${RAILS_S3_SECRET_KEY}

逐项要点：

• ${...} 为真实密钥占位，注入方式：部署前 export SECRET_KEY_BASE="$(bundle exec rails secret)" 或由密钥管理系统渲染该文件；
• RAILS_MAIL_RETRIEVER_* 两行是官方文档标注"邮件列表必需"的收信配置，模板给 IMAP+SSL 示例，pop3 亦可；
• WEB_CONCURRENCY=3 × RAILS_MAX_THREADS=8 ≈ 24 个 Rails 并发单元，对应 RAILS_DB_POOL=25 留 1 个维护连接——按"连接数 ≥ 进程×线程"原则联动调整；
• 密码策略不在本文件（硬编码 12..128，见 3.3），模板无需也不能配它。

七、常见问题

7.1 设置 8 位密码报错，想放宽策略

默认下限 12 位（devise.rb 实测 config.password_length = 12..128）。本实例为演示账号 q1w2e3r4 改为 8..128 前，实测直接设置会抛：

Gültigkeitsprüfung ist fehlgeschlagen: Passwort ist zu kurz (weniger als 12 Zeichen) (ActiveRecord::RecordInvalid)

改文件并重启应用进程后，重置实测回显 RESET_OK admin@hitobito.ch id=222 sign_in_count=0，登录实测 HTTP/1.1 303 See Other。生产建议保持默认下限而不是放宽。

7.2 改了环境文件/初始化器，行为没变化

环境变量与 initializer 均在进程启动时读取。本实例实测：修改后重启应用进程，/healthz 约 165 秒恢复 200，随后新行为生效（303 登录验证通过）。若用 rails runner 临时验证脚本逻辑，记得本实例设了 DISABLE_SPRING=true，避免预加载缓存读到旧代码。

7.3 API 返回 401，是不是没配对参数

不是配置问题，是认证头缺失。实测未认证 GET /api/people 返回 401，错误体 {"errors":[{"code":"unauthorized","status":"401","title":"Login benötigt",...（节选）；带 Authorization: Bearer <访问令牌> + Accept: application/vnd.api+json 实测 200 返回 JSON:API 数据；令牌取值方法：管理员在应用目录用 bundle exec rails runner 调 Doorkeeper::AccessToken.create! 生成（实测有效期 7200 秒）。另实测 .json 后缀路径不存在（404），媒体类型只能靠 Accept 头声明。

7.4 邮件发得出去，列表却收不到信

发信（RAILS_MAIL_DELIVERY_*）与收信（RAILS_MAIL_RETRIEVER_*）是两组独立参数。本实例实测只配了发信（SMTP 端到端 303+捕获成功），收信组留空——此时 Web 与发信一切正常，但邮件列表入站静默不处理。按 5.3 补 TYPE=pop3|imap 与 CONFIG 后，可用 GET /healthz/mail 端点验证邮件通道。

7.5 如何快速确认"必需配置"是否齐备

用内置自检任务（实测末行输出）：

$ bundle exec rake hitobito:check_config
✅ SelfRegistrationRoleTypes configured correctly

该任务逐项校验自注册角色类型等必需配置组合，失败会以非零退出，适合放进部署流水线的发布前检查。

八、参考链接

• hitobito 仓库（含 doc/operator/01_deployment.md 参数权威表）：https://github.com/hitobito/hitobito
• 官方开发工具箱：https://github.com/hitobito/development
• JSON:API 规范：https://jsonapi.org
• Truemail：https://www.truemail.systems
• Puma 调优（WEB_CONCURRENCY/MAX_THREADS）：https://github.com/puma/puma
• Rails ActiveStorage：https://guides.rubyonrails.org/active_storage_overview.html