MintHCM 配置参数详解

MintHCM 4.3.5 的配置分三层：legacy/config.php（主配置，单一事实来源）→ legacy/config_override.php（升级安全覆盖层）→ PHP/Apache 运行层。本文基于 Debian 12 实测部署出的环境，逐段讲解主配置文件全部关键参数的语义与取值，并对 6 组关键参数做了改动→观察→恢复的生效性验证，验证实录全部照实引用。前置认知见《MintHCM 介绍与选型指南》，参数修改后的排障与命令操作见《MintHCM 常用 CLI 命令详解》。

实测环境基线：Debian 12 / Apache 2.4.68 / PHP 8.2.35 / MariaDB 10.11.19 / Elasticsearch 7.17.28 / MintHCM 4.3.5，应用根 /var/www/minthcm，管理员 admin / q1w2e3r4。

一、三层配置总览

层	文件	职责	生效方式
主配置	`/var/www/minthcm/legacy/config.php`	安装器生成（实测 511 行），数据库、站点、日志、搜索、cron 全部运行参数	PHP 每次请求即读，改动即生效，无需重启
覆盖层	`/var/www/minthcm/legacy/config_override.php`	SuiteCRM 血统的升级安全机制：手工/工具写在这里的键会覆盖 config.php 同名键，版本升级不会冲掉	同上，删除文件即还原
运行层	`/etc/php/8.2/apache2/php.ini`、`/etc/apache2/...`、`/var/www/minthcm/.htaccess`	上传上限、内存、安全响应头、重写路由	php.ini 改后需 `systemctl restart apache2`；.htaccess 即改即生效

实测确认覆盖层：向 config_override.php 写入 $sugar_config["list_max_entries_per_page"] = 7; 后 Users 列表立即从 19 行变为 7 行；删除文件后恢复 19 行（第九节实录 4）。

二、legacy/config.php 逐段详解

以下参数名、默认值均摘自实测环境安装器生成的 config.php（行号为实测文件行号），语义按官方代码行为描述。

2.1 数据库段（第 134~155 行）

'dbconfig' => array (
    'db_host_name' => 'localhost',
    'db_host_instance' => '',
    'db_user_name' => 'root',
    'db_password' => 'q1w2e3r4',
    'db_name' => 'minthcm',
    'db_type' => 'mysql',        // 实为 MariaDB/MySQL 通用驱动
    'db_port' => '3306',
    'db_manager' => 'MysqliManager',
),
'dbconfigoption' => array (
    'persistent' => true,        // 持久连接，降低连接开销
    'autofree' => false,
    'debug' => 0,                // 置 1 可在日志打印 SQL
    'ssl' => false,              // 数据库 TLS，跨机部署建议开启
    'collation' => 'utf8mb4_general_ci',
    'charset' => 'utf8mb4',
),

要点：db_type 值叫 mysql，但驱动管理器是 MysqliManager，MariaDB 10.11 实测完全兼容；dbconfigoption.debug 置 1 后 SQL 会打进 minthcm.log，是排查数据问题的第一开关，排查完务必改回 0。

2.2 站点段

参数	实测默认值	语义
`site_url`（403 行）	`http://10.89.71.2:8147/`	对外访问根地址，MintCLI 安装时从 System URL Address 写入；改端口/域名必须同步改它，否则登录跳转与 OAuth 回调会错乱
`host_name`（258 行）	`10.89.71.2`	服务器标识，用于生成绝对链接
`default_language`（168 行）	`en_us`	默认界面语言，取值必须存在于 `languages` 数组
`languages`（280 行）	`array('en_us' => 'English (US)')`	已安装语言包清单；装新语言包（官方 Crowdin 分发）后数组自动多一项，才可被 default_language 引用
`default_module`（171 行）	`Home`	登录后默认落地的模块
`default_theme`（187 行）	`SuiteP`	默认皮肤
`max_dashlets_homepage`（309 行）	`15`	首页仪表板最多小部件数

2.3 日志段（第 293~302 行）

'log_file' => 'minthcm.log',      // 落在 legacy/ 目录下
'log_memory_usage' => false,
'logger' => array (
    'level' => 'fatal',           // fatal|error|warn|info|debug，级别从紧到松
    'file' => array ('ext' => '.log', 'name' => 'minthcm', 'dateFormat' => '%c', ...),
),

安装器默认 fatal——出问题才看日志时几乎总是空文件，这是新手排障最常踩的坑。验证实录见第九节：debug 级别下一轮 cron.php 即产出 38 行 DEBUG。另有独立的 legacy/search_index.log 记录 ES 索引管道（ElasticSearchIndexer.DEBUG/INFO 前缀）。

2.4 列表与分页段

参数	实测默认值	语义
`list_max_entries_per_page`（287 行）	`20`	列表视图每页行数，改动即时生效（第九节实录 1）
`list_max_entries_per_subpanel`（288 行）	`10`	子面板（如员工详情下的关联列表）每页行数
`save_query`（364 行附近）	`all`	列表查询缓存策略

2.5 搜索与 Elasticsearch 段

'elasticsearch_index_prefix' => '1e4a',   // 201 行，ES 索引名前缀，安装时随机生成
'search' => array (
    'controller' => 'UnifiedSearch',
    'defaultEngine' => 'BasicSearchEngine',
    'pagination' => array ('min' => 10, 'max' => 50, 'step' => 10, 'default_limit' => 1000),
),

elasticsearch_index_prefix 是实例级索引前缀：本文实例的全部索引形如 1e4a_users、1e4a_goals（_cat/indices 实录见《安装部署指南》第七节）。改它必须紧跟一次全量重索引（MintCLI elasticsearch:reindex，见 CLI 篇），否则列表与全局搜索指向一套不存在的空索引。验证实录见第九节实录 3。

2.6 cron 段（第 96~100 行）

'cron' => array (
    'max_cron_jobs' => 10,       // 单轮 cron.php 最多执行作业数
    'max_cron_runtime' => 30,    // 单轮最长运行秒数
    'min_cron_interval' => 30,   // 相邻两轮最小间隔秒数
    'max_repeat_count' => 1000,  // 日历重复事件最多生成次数
),

配合每分钟一次的系统 crontab（部署篇第九节）：单轮最多处理 10 个作业、跑满 30 秒让位，防止长任务阻塞调度。实测连续两次手动运行 cron.php 会得到 FATAL Job runs too frequently, throttled to protect the system.——即 min_cron_interval 的保护在起作用。

2.7 安全与集成段

参数	实测默认值	语义
`oauth2_encryption_key`（322 行）	44 字符 Base64（安装时生成）	OAuth2 令牌/客户端凭据加密密钥；丢失 = 全部已发令牌失效，备份必须包含
`passwordsetting`（323 行起）	安装器默认	密码策略（长度、过期、找回方式）
OAuth2 RSA 密钥	`/var/www/minthcm/api/configs/private.key`（1708 B）与 `public.key`（451 B）	安装器 `writing RSA key` 产物，JWT 签名用；私钥权限应仅 www-data 可读

2.8 目录段

参数	实测默认值	语义
`upload_dir`（486 行）	`upload/`（相对 legacy/）	全部上传附件落盘处，备份必含
`cache_dir`（76 行）	`cache/`	模板/元数据缓存，可整体清空重建
`tmp_dir`（458 行）	`cache/xml/`	导入导出临时目录
`session_dir`（394 行）	`''`（空 = PHP 默认 /var/lib/php/sessions）	会话存储，多机部署时改用 Redis/共享存储才需要动

三、api 层配置：api/configs/mint/config.php

新版 REST API（Vue 前端走 /api/*）有独立配置 $mint_config，发行包模板即生效值：

$mint_config = array(
    "search" => array(
        "default_engine" => 'ElasticSearch',
        "default_page_size" => 25,               // api 列表默认页大小
        "engines" => array( "ElasticSearch" => array(
            array('host' => 'localhost', 'user' => '', 'pass' => '', 'port' => '9200'),
        )),
    ),
    "database" => array('driver' => 'pdo_mysql', 'host' => "localhost", 'port' => '3306',
        'dbname' => '', 'user' => '', 'password' => '', 'charset' => 'utf8mb4'),
    'oauth2_encryption_key' => 'MintHCM-DEFKEY',
    'session_grant_interval' => 'PT4H',          // 会话授权间隔（ISO 8601 时长）
);

要点：database 的库名/口令留空属正常——api 通过 legacy 连接器复用 config.php 的数据库段，不需要在此重复填写；ES 走无认证 7.x 时 user/pass 留空即可；session_grant_interval 为 ISO 8601 时长（PT4H = 4 小时）。同目录 configs/private.key|public.key 即 2.7 节的 RSA 密钥对。

四、PHP 运行层：php.ini 上传链

默认 Debian 的 upload_max_filesize = 2M、post_max_size = 8M（实测文件 /etc/php/8.2/apache2/php.ini 第 855、703 行），对附件密集的 HR 场景明显不够。改为 20M/25M 后重启：

sed -i 's/^upload_max_filesize = 2M$/upload_max_filesize = 20M/; s/^post_max_size = 8M$/post_max_size = 25M/' /etc/php/8.2/apache2/php.ini
systemctl restart apache2

验证（读取 Apache 模块所用的 ini）：

$ php -c /etc/php/8.2/apache2 -i | grep -E '^(upload_max_filesize|post_max_size)'
post_max_size => 25M => 25M
upload_max_filesize => 20M => 20M

三个值要成链：upload_max_filesize ≤ post_max_size ≤ Apache LimitRequestBody（默认 0 不限）。memory_limit 同理需 ≥ post_max_size。

五、.htaccess 安全响应头（4.3.5 新增）

4.3.5 起根目录 .htaccess 为 SPA 增加了完整安全头（<Files "index.html"> 段），实测对 / 与 /vue/dist/index.html 均生效：

$ curl -sI http://localhost:8147/ | grep -iE 'content-security|x-frame|x-content-type|referrer'
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://www.google.com https://www.gstatic.com; style-src 'self' 'unsafe-inline' https://cdn.materialdesignicons.com https://cdn.jsdelivr.net https://fonts.googleapis.com https://www.gstatic.com; img-src 'self' data: blob:; font-src 'self' data: https://cdn.materialdesignicons.com https://cdn.jsdelivr.net https://fonts.gstatic.com; connect-src 'self' https://cdn.jsdelivr.net; frame-src 'self' https:; frame-ancestors 'self'; object-src 'none'; base-uri 'self'; form-action 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Referrer-Policy: strict-origin-when-cross-origin

如需接入 CDN 或第三方字体，要同步扩 script-src/style-src/font-src/connect-src 白名单——这些指令与 legacy/include/utils.php 中 get_default_csp_directives() 保持同步（官方注释原话）。

六、参数生效性验证实录

以下 6 组均为本文实测机的"改动 → 观察 → 恢复"完整记录。

实录 1：list_max_entries_per_page（列表页大小，改完即时生效，无需任何重启）

$ grep -n "list_max_entries_per_page" legacy/config.php
287:  'list_max_entries_per_page' => 20,
$ # 默认 20：登录 admin 后拉取 Users 列表，数表格行（odd/evenListRowS1 类）
$ grep -c 'oddListRowS1\|evenListRowS1' users20.html
19
$ sed -i "s/'list_max_entries_per_page' => 20,/'list_max_entries_per_page' => 5,/" legacy/config.php
$ # 同一会话重新拉取 Users 列表
$ grep -c 'oddListRowS1\|evenListRowS1' users5.html
5

19 ≈ 20（首页行因分页起始标记略少 1），改 5 后精确 5 行——参数直通渲染层。

实录 2：logger.level（fatal → debug）

$ # 级别 fatal：清空日志跑一轮 cron.php
$ grep -c 'DEBUG' minthcm.log
0
$ sed -i "s/'level' => 'fatal',/'level' => 'debug',/" legacy/config.php
$ # 清空日志再跑一轮
$ grep -c 'DEBUG' minthcm.log
38
$ head -2 minthcm.log
Wed Oct 28 13:35:54 2026 [1921][-none-][DEBUG] current_language is: en_us
Wed Oct 28 13:35:54 2026 [1921][-none-][DEBUG] Found cache backend SugarCacheAPC

生产常年保持 fatal，排障时临时改 debug。

实录 3：elasticsearch_index_prefix（索引命名根参数）

$ sed -i "s/'elasticsearch_index_prefix' => '1e4a',/'elasticsearch_index_prefix' => 'c1test',/" legacy/config.php
$ printf 'Users\n' | sudo -u www-data ./MintCLI elasticsearch:reindexModule
Reindexing ElasticSearch
$ curl -s 'localhost:9200/_cat/indices/c1test*?v'
health status index        uuid                   pri rep docs.count docs.deleted store.size pri.store.size
yellow open   c1test_users lbDsWo0HQ7mubptpizx21w   1   1          0            0       227b           227b

前缀一改，新索引即刻按新前缀命名。恢复 1e4a 并重索引后 1e4a_users 回到 69 条文档——该参数决定索引命名空间，改前缀 = 换一套索引，务必跟重索引。

实录 4：config_override.php 覆盖层

$ printf '<?php\n$sugar_config["list_max_entries_per_page"] = 7;\n' > legacy/config_override.php
$ # 重新拉取 Users 列表
$ grep -c 'oddListRowS1\|evenListRowS1' users7.html
7
$ rm legacy/config_override.php
$ # 再拉取
$ grep -c 'oddListRowS1\|evenListRowS1' usersr.html
19

覆盖层压过主配置同名键，删除即还原——升级安全的正确用法：自己的改动全写 override，config.php 交给安装器/升级器。

实录 5：php.ini 上传链（见第四节，2M/8M → 20M/25M，systemctl restart apache2 后经 Apache 侧 ini 读出）

实录 6：CSP 安全头（见第五节，4.3.5 默认即带，四头齐全）

七、生产建议速查

目标	改哪里
换域名/端口	`config.php` 的 `site_url` + `host_name`，再核对 `.htaccess` RewriteBase（部署篇排障实录 1）
上传大附件	php.ini 三值成链（第四节）
查不到数据/搜索空	`logger.level=debug` + `dbconfigoption.debug=1` 双开，看 `minthcm.log`；确认 cron 在跑、`elasticsearch_index_prefix` 未动过
数据库慢	`dbconfigoption.persistent=true` 保持；跨机时开 `ssl`
升级版本	自定义参数进 `config_override.php`（实录 4），`./MintCLI upgrade` 前先跑 `instance:rebuild`（见 CLI 篇）

参考来源（查询日期 2026-10-28）

实测环境：/var/www/minthcm/legacy/config.php（4.3.5 安装器生成，511 行）、api/configs/mint/config.php、.htaccess、/etc/php/8.2/apache2/php.ini
官方安装指南（crontab 与 AllowOverride 要求）：https://minthcm.org/support/minthcm-installation-guide/
官方 System Configuration Wiki：https://wiki.minthcm.org/index.php?title=Process:System_configuration
Releases v4.3.5 安全更新说明（CSP/SSO）：https://github.com/minthcm/minthcm/releases