HumHub 1.19.3 配置参数详解

HumHub 1.19.3 的配置分四层：内置默认配置、主机上的本地覆盖文件、数据库运行设置、环境变量注入。本文逐层拆解参数语义，关键结论均为主机侧实测验证（2026-11-02），实例由 《HumHub 1.19.3 Docker Compose 部署指南》 的官方 compose 形态部署。CLI 操作细节见 《HumHub 1.19.3 常用 CLI 命令与工具详解》。

一、配置体系总览

1.1 四个来源与合并顺序

服务启动时按固定顺序合并配置（官方发行包源码 BootstrapService::getConfig()，2026-11-02 查阅）：

1. 内置默认：应用包内 config/common.php + config/web.php/config/console.php（Web 与控制台分别取用）；
2. dynamic.php：/data/config/dynamic.php，安装器/后台写入的动态配置；
3. 本地覆盖文件：/data/config/common.php + /data/config/web.php 或 console.php（运维手工维护层）；
4. 环境变量：HUMHUB_CONFIG__* 系列，优先级最高。

后一层覆盖前一层，即：环境变量 > 本地覆盖文件 > dynamic.php > 内置默认。

1.2 实测证据：环境变量改写数据库连接

内置默认里 components.db.dsn 是 mysql:host=localhost;dbname=humhub（源码实测读取），而 compose 只给了环境变量：

- HUMHUB_CONFIG__COMPONENTS__DB__DSN=mysql:host=db;dbname=humhub

实例实际连上了数据库服务 db 主机名——环境变量层生效。进一步用配置打印脚本实测（主机侧执行，进入服务进程上下文读取合并后的配置）：

=== baseline ===
cron_time=18:00
dsn=mysql:host=db;dbname=humhub
=== with env override ===
cron_time=03:00
dsn=mysql:host=db;dbname=humhub

基线 dailyCronExecutionTime 为内置默认 18:00；追加 HUMHUB_CONFIG__PARAMS__DAILY_CRON_EXECUTION_TIME=03:00 后合并结果变为 03:00，映射与优先级同时得到验证。

二、环境变量映射规则

服务内 EnvHelper 源码（2026-11-02 查阅）定义了五条前缀规则：

键名转换规则：以双下划线 __ 分隔层级，每段先转小写再驼峰化（variablize）。例：

HUMHUB_CONFIG__COMPONENTS__DB__DSN
  → components.db.dsn
HUMHUB_CONFIG__PARAMS__DAILY_CRON_EXECUTION_TIME
  → params.dailyCronExecutionTime
HUMHUB_CONFIG__MODULES__INSTALLER__ENABLE_AUTO_SETUP
  → modules.installer.enableAutoSetup

值归一化规则：先尝试按 JSON 解码（所以数组/对象直接写 JSON，如 MODULE_BLACKLIST='["updater"]'）；字符串 true/false 归一化为布尔；其余按字符串。

2.1 发行包内置的环境变量默认值

官方 Dockerfile 以 ENV 声明全部默认值（2026-11-02 查阅，实测 docker compose 未覆盖时生效）：

拆分部署场景（Web/调度/队列分进程组运行）用 HUMHUB_DOCKER__AUTOSTART_* 三开关把角色拆开，官方多服务示例即按此把 scheduler、worker 拆为独立进程组（worker 用 NUMPROCS_WORKER=1 × 2 副本）。

三、内置默认配置关键参数

应用包 config/common.php（360 行，2026-11-02 从运行实例读取）定义核心组件树，运维最常触碰的参数如下。

3.1 数据库组件 components.db

队列、互斥锁、实时推送都寄生在这个连接上：components.queue 默认 humhub\modules\queue\driver\MySQL（数据库表驱动，无需 Redis），components.mutex 默认 yii\mutex\MysqlMutex，components.live 默认 Poll 驱动（换 Mercure 需 MERCURE_ENABLE 与 Sodium 扩展）。

3.2 缓存与会话

实测 cache/flush-all 回显即列出这两个组件（详见 D1 篇）。

3.3 日志与安全脱敏

components.log.targets 同时启用 FileTarget（写 runtime/logs）与 DbTarget（写数据库 log 表），级别 error/warning，排除 400/401/403/404/405 等预期异常。上下文变量 _GET、_SERVER 会入日志，但内置脱敏词表（实测读取源码）：

PASS, SECRET, KEY, TOKEN, DSN, CREDENTIAL, AUTH, PRIVATE, SALT, COOKIE

变量名命中任一词（不区分大小写）即打码——所以 HUMHUB_CONFIG__COMPONENTS__DB__PASSWORD 这类敏感环境变量不会明文落日志。

3.4 邮件

components.mailer 为 humhub\components\mail\Mailer。传输方式不在配置文件里，而是数据库设置项（settings 表的 mailerTransportType/mailerDSN 等，安装向导第 4 步写入）；file 模式把邮件写为 .eml 文件，实测落点 runtime/mail/20261102-142350-0722-0172.eml。若要用配置文件锁死 DSN，写 HUMHUB_FIXED_SETTINGS__BASE__MAILER_DSN（固定设置前缀，同时会让安装器跳过邮件步——源码实测逻辑）。

3.5 其他常用 params

四、本地覆盖文件层

/data/config/ 目录实测结构（bind mount 到主机数据目录）：

common.php  console.php  web.php  dynamic.php  messages/  README.md  .gitignore

三个覆盖文件初始为空 return [];，注释直接指向官方高级配置文档；.gitignore 忽略全部本地配置。写法就是 Yii2 配置数组，例如把主缓存换 APCu：

<?php // /data/config/common.php
return [
    'components' => [
        'cache' => ['class' => 'yii\caching\ApcuCache'],
    ],
];

改完执行 CLI 清缓存生效（见 D1 篇）。dynamic.php 由程序写入（实测安装后内容为 <?php return array();），运维不要手工编辑。

五、数据库运行设置（SettingsManager）

站点级运行参数存数据库 setting 表（site/base 模块）与 contentcontainer_setting（空间级），后台"设置"页即读写它。CLI 侧对应三件套（实测回显见 D1 篇）：

/app/yii settings/list-module base        # 列出 base 模块全部设置
/app/yii settings/set base <name> <value> # 写入
/app/yii settings/delete base <name>      # 删除

HUMHUB_FIXED_SETTINGS__BASE__<NAME> 可把某项设置锁死（后台显示为固定值、不可改），适合托管/多实例统一管控。

六、PHP 运行时配置

服务内置 PHP 8.4（实测 php -v 回显 PHP 8.4.27 (cli) (built: Oct 21 2026 15:53:39) (ZTS)，Zend OPcache 已启用）。官方 ini 默认值（实测读取 /usr/local/etc/php/conf.d/50-humhub.ini）：

upload_max_filesize = 1G
post_max_size = 1G
max_input_time = 600
max_execution_time = 600
log_errors = On
display_errors = Off

实测已加载的扩展（php -m，节选）：gd imagick intl ldap mbstring mysqlnd pdo_mysql sodium apcu zip exif fileinfo curl opcache——官方需求页列的必需扩展全部预装，LDAP/Mercure/ImageMagick 等企业特性无需再装。

自定义方式（官方 docs/php-configuration.md，2026-11-02 查阅）：在 compose 同目录建 php.ini 只写要改的项，挂载到 conf.d/99-custom.ini（99 序号晚于 50，后加载覆盖）；或仅 Web 场景用 FRANKENPHP_CONFIG 变量。PHP 无堆上限概念，memory_limit 按单请求峰值设，512M 对多数内网场景足够。

七、Web 服务层参数

八、数据目录布局

主机数据目录（挂载为服务内 /data）实测结构：

/data
├── uploads          # 上传文件（fs 组件 data 挂载点）
├── assets           # 已发布静态资源（assetManager）
├── logs             # app.log / access.log / server.log
├── config           # 第四节覆盖文件
├── modules          # 市场下载模块
├── modules-custom   # 自装模块（autoload 路径第一位）
├── themes           # 自定义主题（1.19 起默认主题不在此目录）
└── caddy            # 证书与 Caddy 持久状态

/data 与 /opt/humhub（程序）分离，意味着升级/重建服务只动程序层，数据全在主机目录——备份、迁移、换版本都以这个布局为前提。

九、配置排障实录

1. 改了覆盖文件不生效：主缓存与设置树有进程内缓存，改 /data/config/*.php 或数据库设置后需 cache/flush-all（实测回显见 D1 篇），或直接重启服务进程组。
2. 环境变量没映射进配置：检查是否用了单下划线——分隔符必须是双下划线 __；段名大小写不敏感（统一转小写驼峰），但前缀必须全大写匹配 HUMHUB_CONFIG__ 等五条之一。
3. params.installed 与实际状态不符：安装标记同时存在于 dynamic.php 与数据库设置，手工恢复备份后若只还原了文件没还原库，服务会回到安装向导——以数据库为准。
4. 日志里看不到上下文变量：命中脱敏词表的变量名（PASS/KEY/TOKEN/DSN 等）会被打码，属预期安全行为，不是丢日志。
5. 上传大文件 413/超时：先查第六节 post_max_size/upload_max_filesize（默认 1G），再查 HumHub 后台"文件"设置里的站点级上限——两层取小者生效。