MintHCM Debian 12 安装部署指南（Apache + MariaDB + Elasticsearch 实测）

MintHCM 4.3.5 在 Debian 12 单机实测部署：Apache 2.4（8147 端口）+ PHP 8.2 + MariaDB 10.11 + Elasticsearch 7.17 四环依赖链全流程，MintCLI 交互问答实录、AH00124 重写死循环等 4 条排障实录，全部命令与回显真机照抄。

MintHCM人力资源管理Debian122026/10/28

MintHCM Debian 12 安装部署指南（Apache + MariaDB + Elasticsearch 实测）

本文在一台 Debian 12（bookworm） 服务器上完整部署 MintHCM 4.3.5（2026-10-28 查证的官方最新稳定版，构建日期 2026-10-23），部署形态为裸机单机一体：Apache 2.4 + PHP 8.2 + MariaDB 10.11 + Elasticsearch 7.17 全部同机安装，Web 服务监听 8147 端口，安装路径采用官方 CLI 安装器 MintCLI install。文中所有命令与回显均为真实服务器上的实测记录，可直接照抄执行；示例中数据库账号 root / q1w2e3r4、Mint 管理员账号 admin / q1w2e3r4，实测服务器内网 IP 以 10.89.71.2 代指，读者请替换为自己的服务器 IP。

选型与版本依据见《MintHCM 介绍与选型指南》；安装完成后的参数调优见《MintHCM 配置参数详解》；管理命令详见《MintHCM 常用 CLI 命令详解》。

一、部署形态与依赖链总览

MintHCM 4.x 的单机依赖链是理解整个安装过程的钥匙，四环缺一不可：

浏览器 ──> Apache 2.4（含 rewrite/headers 模块）
              │  托管三层代码：vue/（SPA 前端）+ api/（REST API）+ legacy/（业务后端，PHP 8.2）
              ▼
        MariaDB 10.11（业务数据库，安装后 341 张表）
              ▲
        legacy/cron.php（每分钟计划任务，负责后台调度与 ES 索引管道）
              ▼
        Elasticsearch 7.17（列表查询与全局搜索，安装即建索引）

三条来自官方文档的硬性口径（两处官方页面交叉核对）：

组件官方要求本文实测
Web 服务器Linux + Apache2，启用 Rewrite、Headers，AllowOverride AllApache/2.4.68（Debian）
PHP8.2PHP 8.2.35（Debian 12 官方仓库原生版本，无需第三方源）
数据库MySQL 8.0 或 MariaDB 10.5/10.6/10.10/10.11MariaDB 10.11.19（Debian 12 仓库默认版本，恰好落在支持列表）
Elasticsearch安装指南写 7.9，仓库 README 写 7.10+Elasticsearch 7.17.28（7.x 系列最终版，两个口径同时满足）

提示：Elasticsearch 不要装 8.x，Mint 4.3.5 的索引器按 7.x 客户端实现；8.x 会直接连不上（见第十节排障实录第 4 条的官方口径差异说明）。

二、系统准备

以 root 执行。Debian 12 最小安装后先补齐基础工具与 PHP 全家桶（Mint 的 legacy 后端与环境检查页会逐项核查这些扩展）：

apt-get update
apt-get install -y apache2 mariadb-server unzip curl ca-certificates cron sudo wget \
  php8.2 php8.2-cli php8.2-mysql php8.2-gd php8.2-curl php8.2-mbstring \
  php8.2-xml php8.2-zip php8.2-intl php8.2-imap php8.2-ldap php8.2-soap \
  php8.2-bcmath php8.2-opcache

实测装完后的版本回显：

$ php -v | head -1
PHP 8.2.35 (cli) (built: Oct 21 2026 06:29:51) (NTS)
$ apache2 -v
Server version: Apache/2.4.68 (Debian)
$ mariadb --version
mariadb  Ver 15.1 Distrib 10.11.19-MariaDB, for debian-linux-gnu (x86_64) using  EditLine_wrapper

各 PHP 扩展的用途：mysql（MariaDB 驱动）、gd（头像/图片处理）、curl（外部集成）、mbstring/intl（多字节与国际化，多语言包必需）、imap（邮件集成）、ldap（企业目录认证）、soap/xml/zip（API 与导入导出）、bcmath（薪资档位等精度计算）、opcache（生产加速）。

内存建议：实测机 19 GB 内存，其中 Elasticsearch 是大头。最小可跑配置为 4 GB（ES 堆 512 MB + MariaDB + Apache），生产建议 8 GB 起步。

三、安装并初始化 MariaDB

mariadb-server 已随上节装好，启动并设为开机自启：

systemctl enable --now mariadb

Debian 的 MariaDB 默认给 root 用 unix_socket 认证——本地无密码即可登录，但 TCP/密码方式连不上，会直接导致后面 MintCLI 安装中断。这里把 root 改为 mysql_native_password 口令认证（示例口令 q1w2e3r4）：

mariadb -e "ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('q1w2e3r4'); FLUSH PRIVILEGES;"

验证密码方式可登录（这一步必须成功再继续）：

$ mariadb -u root -pq1w2e3r4 -e 'SELECT VERSION();'
VERSION()
10.11.19-MariaDB-0+deb12u1

库名不用手动建：MintCLI install 会按输入的 Database Name（本文用 minthcm）自行建库建表。

四、安装 Elasticsearch 7.17

从 Elastic 官方制品库下载 7.x 最终版 deb 包（约 325 MB，实测下载件 elasticsearch-7.17.28-amd64.deb，325,463,356 字节）：

curl -fL -o /root/elasticsearch-7.17.28-amd64.deb \
  https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.17.28-amd64.deb
dpkg -i /root/elasticsearch-7.17.28-amd64.deb

dpkg -i 结束时会有官方提示（不出意外，只提示如何用 systemd 启动）：

### NOT starting on installation, please execute the following statements to configure elasticsearch service to start automatically using systemd
 sudo systemctl daemon-reload
 sudo systemctl enable elasticsearch.service
### You can start elasticsearch service by executing
 sudo systemctl start elasticsearch.service
Created elasticsearch keystore in /etc/elasticsearch/elasticsearch.keystore

限制 JVM 堆为 512 MB（单机与其他服务共存时的稳妥值，生产可调到机器内存一半）：

printf -- '-Xms512m\n-Xmx512m\n' > /etc/elasticsearch/jvm.options.d/heap.options
systemctl daemon-reload
systemctl enable --now elasticsearch.service

启动约需 20~30 秒，验证：

$ curl -s http://localhost:9200
{
  "name" : "minthcm-lab",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "wi5S8uECSXqmGyrwR_bxOg",
  "version" : {
    "number" : "7.17.28",
    "build_flavor" : "default",
    "build_type" : "deb",
    "build_hash" : "139cb5a961d8de68b8e02c45cc47f5289a3623af",
    "build_date" : "2025-02-20T09:05:31.349013687Z",
    ...

7.x 的 deb 包默认不开安全认证，MintCLI 里 ES 用户名/密码可保留默认值直接回车。

五、配置 Apache 2.4（监听 8147）

5.1 端口与站点

把默认 80 端口改为 8147（/etc/apache2/ports.conf）：

sed -i 's/^Listen 80$/Listen 8147/' /etc/apache2/ports.conf

新建虚拟主机 /etc/apache2/sites-available/minthcm.conf（与官方安装指南给出的示例一致，仅加了日志名）：

<VirtualHost *:8147>
    DocumentRoot /var/www/minthcm

    <Directory /var/www/minthcm>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/minthcm_error.log
    CustomLog ${APACHE_LOG_DIR}/minthcm_access.log combined
</VirtualHost>

启用模块与站点：

a2enmod rewrite headers
a2dissite 000-default
a2ensite minthcm

回显（rewrite/headers 首次启用会显示 Enabling）：

Enabling module rewrite.
Enabling module headers.

顺手消除 AH00558 域名告警（不影响功能，但日志干净些）：

echo 'ServerName minthcm-lab' > /etc/apache2/conf-available/servername.conf
a2enconf servername

语法检查与重启：

$ apachectl configtest
Syntax OK
$ systemctl restart apache2

AllowOverride All 是硬要求：Mint 根目录的 .htaccess 承担 /api、/legacy、/mcp 的全部路由重写，禁用后整个前端与 API 都会 404。

5.2 关键：.htaccess 的 RewriteBase 必须改为 /

4.3.5 发行包根目录 .htaccess 第 9 行出厂值是 RewriteBase /minthcm，它假设应用部署在站点子路径 /minthcm/ 下；而官方安装指南的示例 vhost 是把 DocumentRoot 直接指向应用根目录。两者冲突，后果是所有 /api/* 请求触发内部重定向死循环，Apache 日志出现：

[core:error] AH00124: Request exceeded the limit of 10 internal redirects due to probable configuration error.

按本文形态（DocumentRoot 直指应用根）修复：

sed -i 's|RewriteBase /minthcm|RewriteBase /|' /var/www/minthcm/.htaccess

实测修复前 POST /api/... 返回 500（AH00124 循环），改完即恢复正常（第七节末的接口回显）。

六、部署 MintHCM 4.3.5 程序包

官网 Download 按钮实际指向的直链为 https://ma.minthcm.cloud/asset/46:minthcm-release-4-3-5（302 到 minthcm-4.3.5.zip，实测 120,649,701 字节）。在服务器上直接下载：

$ curl -fL -o /root/minthcm-4.3.5.zip "https://ma.minthcm.cloud/asset/46:minthcm-release-4-3-5"
$ ls -l /root/minthcm-4.3.5.zip
-rw-r--r-- 1 root root 120649701 Oct 28 13:04 /root/minthcm-4.3.5.zip

解压到 /var/www/minthcm（zip 内自带一层 minthcm-4.3.5/ 目录，摊平）并设置属主权限——官方指南要求 Apache 运行用户（Debian 为 www-data）全权持有：

mkdir -p /var/www/minthcm
cd /var/www/minthcm
unzip -q /root/minthcm-4.3.5.zip
mv minthcm-4.3.5/* minthcm-4.3.5/.[!.]* .
rmdir minthcm-4.3.5
chown -R www-data:www-data /var/www/minthcm
chmod -R 755 /var/www/minthcm

解压后应用占用实测 511 MB，顶层结构：

$ ls /var/www/minthcm
api  index.php  install  kanban  legacy  LICENSE  MintCLI  mcp  upgrade  vue ...

各目录职责：legacy/ 是业务后端（SuiteCRM 血统，含 cron.php 与配置文件），api/ 是新版 REST API，vue/ 是编译好的 SPA 前端（vue/dist），mcp/ 是 MCP 服务入口，MintCLI 就是下一节的安装器。

七、运行 MintCLI 安装器

所有前置服务就绪后，以 www-data 身份在应用根目录执行安装器：

cd /var/www/minthcm
sudo -u www-data ./MintCLI install

交互问答实录（方括号内为默认值，直接回车即取默认；本文实测逐项输入如下）：

安装器提问本文输入说明
System Administrator Name [admin]adminMint 管理员账号
System Administrator Passwordq1w2e3r4管理员口令
Database Host [localhost]回车数据库同机
Database Port [3306]回车MariaDB 默认端口
Database Username [root]回车第三节改好的 root
Database Passwordq1w2e3r4与第三节一致
Database Name [minthcm]回车库名，自动建库
Database Collation [utf8mb4_general_ci]回车排序规则
Elasticsearch Host [localhost]回车ES 同机
Elasticsearch Port [9200]回车ES 默认端口
Elasticsearch Username [elastic]回车7.x 未开认证，留默认
Elasticsearch Password [changeme]回车同上
Install Demo Data (yes/no) [no]yes实测选了演示数据，便于后续验证
SSL (yes/no) [no]no未上证书（生产建议 yes 或前置网关）
System URL Addresshttp://10.89.71.2:8147/对外访问地址，含端口
Application Root Directory [/var/www]回车应用所在上级目录
Rebuild Frontend (requires Node.js) (yes/no) [no]no发行包已带编译产物，无需 Node.js

安装全程数分钟，末尾实测回显（原文照录，含官方拼写）：

Create OAuth2 keys and Frontend client...
-----------------------------------------

writing RSA key
Setting up files permissions...
-------------------------------

 [OK] Installation finished successfuly

安装器完成三件核心工作：写入 legacy/config.php（数据库、site_url 等全部运行参数）、生成 /api/configs 下的 OAuth2 RSA 公私钥与 frontend 客户端、按输入建库并初始化。建表规模实测 341 张表；ES 侧同步建出带实例前缀（形如 1e4a_）的索引，演示数据索引实况节选：

$ curl -s 'localhost:9200/_cat/indices?v' | head -4
health status index       uuid                   pri rep docs.count docs.deleted store.size pri.store.size
yellow open   1e4a_users  iJnjIMRcQVCeatqxY1gOug   1   1         69            0     44.2kb         44.2kb
yellow open   1e4a_goals  rtBGO5nyT8iFNEZ9w3jv-A   1   1          2            0     12.7kb         12.7kb
yellow open   1e4a_ideas  NA61OX6wSDiRbcDd78Ap0Q   1   1          7            0     19.7kb         19.7kb

接口层冒烟测试（重写修复生效的直接证据）：

$ curl -s -X POST http://localhost:8147/api/access_token -H 'Content-Type: application/json' -d '{}'
{"error":"invalid_client","error_description":"Client authentication failed","message":"Client authentication failed"}

这条 401 是预期结果：空请求体没有客户端凭据，但能返回 JSON 说明 /api 重写、api 服务、数据库连接全链路已通。

八、登录验证

浏览器打开 http://10.89.71.2:8147/，用 admin / q1w2e3r4 登录即可进入工作台（官方指南第七步）。

无浏览器的环境下可用 legacy 登录接口做等价验证（实测实录，302 落点 Home 即为认证成功，随后携会话 Cookie 取回 MintHCM 标题页）：

$ curl -s -c /tmp/cj -o /dev/null -w "HTTP %{http_code} -> %{redirect_url}\n" \
    -X POST "http://localhost:8147/legacy/index.php" \
    -d "module=Users&action=Authenticate&user_name=admin&username_password=q1w2e3r4&should_login=true"
HTTP 302 -> http://localhost:8147/legacy/index.php?module=Home&action=index
$ curl -s -b /tmp/cj "http://localhost:8147/legacy/index.php?module=Home&action=index" | grep -oE "<title>[^<]*"
<title>MintHCM

九、配置后台任务 crontab

Elasticsearch 索引与调度依赖每分钟一次的 cron.php，官方指南要求挂在 www-data 名下：

crontab -u www-data -e

写入一行：

* * * * * cd /var/www/minthcm/legacy; php -f cron.php > /dev/null 2>&1

确认：

$ crontab -u www-data -l
* * * * * cd /var/www/minthcm/legacy; php -f cron.php > /dev/null 2>&1

手动执行一轮验证退出码为 0（输出中可能出现一条 PHP Notice，属发行包已知噪音，不影响任务执行）：

$ cd /var/www/minthcm/legacy && sudo -u www-data php -f cron.php; echo exit=$?
PHP Notice:  Only variables should be passed by reference in /var/www/minthcm/legacy/include/utils.php on line 1224
exit=0

十、排障实录

1. /api 返回 500，日志 AH00124 内部重定向 10 次循环 现象：POST /api/access_token 得到 Apache 500 页；tail /var/log/apache2/minthcm_error.log 见 AH00124: Request exceeded the limit of 10 internal redirects。 根因：4.3.5 发行包 .htaccess 出厂 RewriteBase /minthcm（假设子路径部署），与官方指南的 DocumentRoot 直指应用根的写法冲突，每轮重写都多拼一层 /minthcm 前缀导致死循环。 修复：sed -i 's|RewriteBase /minthcm|RewriteBase /|' /var/www/minthcm/.htaccess，无需重启 Apache（.htaccess 即改即生效）。修复后同接口返回 JSON 401（见第七节）。

2. MintCLI 在 Database Password 后中断 现象：填完数据库口令安装即停。 根因：Debian 的 MariaDB root 默认 unix_socket 认证，不接受 TCP 密码登录。 修复：按第三节 ALTER USER ... mysql_native_password 后重跑安装器。

3. Elasticsearch 起不来或启动即被 OOM 杀掉 单机内存紧张时 ES 默认堆可能占满剩余内存。处理：写入 /etc/elasticsearch/jvm.options.d/heap.options（内容 -Xms512m 与 -Xmx512m 两行）后 systemctl restart elasticsearch。判定 ES 就绪的标准是 curl -s localhost:9200 返回含 "number" : "7.17.28" 的 JSON。

4. ES 版本口径注意 官方仓库 README 写 Elasticsearch 7.10+，安装指南页写 7.9——两处口径不一致时取高者；本文用 7.17.28（7.x 最终版）实测通过。若误装 8.x，Mint 索引器无法兼容，需卸载后改装 7.x。

十一、日常运维要点

开机自启清单（本文全部已 enable）：

$ systemctl is-enabled apache2 mariadb elasticsearch cron
enabled enabled enabled enabled
  • 日志位置：Apache /var/log/apache2/minthcm_error.log、minthcm_access.log；Mint 业务日志 legacy/ 下按 config 中 logger 设置落盘；ES 日志 /var/log/elasticsearch/。
  • 备份三件套：mariadb-dump minthcm 业务库 + /var/www/minthcm 中的上传目录与 legacy/config.php + ES 可靠 elasticsearch:reindex 全量重建（命令见《MintHCM 常用 CLI 命令详解》）。
  • 版本升级：./MintCLI upgrade（详见 CLI 篇），跨大版本（3.x → 4.x）走官方升级指引，不要直接覆盖代码。

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

  1. 官方安装指南（要求/手动流程/crontab/AllowOverride 示例）：https://minthcm.org/support/minthcm-installation-guide/
  2. 官方 CLI 安装指南（MintCLI install 交互项原文）：https://minthcm.org/support/installing-minthcm-via-command-line-interface-cli/
  3. GitHub README 环境要求与许可：https://github.com/minthcm/minthcm
  4. Releases v4.3.5（安全修复与 Node.js 构建说明）：https://github.com/minthcm/minthcm/releases
  5. 下载直链（官网 Download 按钮解析）：https://ma.minthcm.cloud/asset/46:minthcm-release-4-3-5
  6. Elasticsearch 7.17.28 deb：https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.17.28-amd64.deb