DomainMOD 4.23 配置参数详解

目标：把 DomainMOD 4.23（自托管域名与 SSL 证书资产台账）的全部可调参数摸清楚——参数分布在哪几层、每一项在哪个页面/文件、默认值是什么、改完怎么验证。本文所有参数与回显均在 Ubuntu 22.04 + Apache 2.4.69 + PHP 8.2.35 + MariaDB 10.11.19 的单机部署上实测（应用版本 4.23.0，2026-10-26），部署过程见 《DomainMOD 4.23 Docker Compose 部署指南》。管理账号沿用演示约定：admin（初始 admin/admin，首登改为 q1w2e3r4）。

一、环境信息

二、前置条件

1. 已完成部署与首次安装（未部署先走部署篇）。
2. 管理员登录。所有系统级参数都在 Web 管理界面修改，实测登录：

curl -s -c /tmp/dmck.txt -b /tmp/dmck.txt -o /dev/null -w '%{http_code}->%{redirect_url}\n' \
  -d "new_username=admin&new_password=q1w2e3r4" http://127.0.0.1:8131/

302->http://127.0.0.1:8131/checks.php

登录成功后服务端 302 到 checks.php 完成会话初始化，再跟随跳转即进入工作台。

3. 命令行数据库访问（用于核对落库结果；密码为演示值）：

mariadb -u domainmod -pq1w2e3r4 domainmod -e 'SELECT 1;'

三、参数总览

DomainMOD 的参数分四层，修改通道各不相同：

优先级与关系：连接层决定应用连哪个库；系统层与调度层是全站生效；用户层只影响当前账号的界面体验。下面逐层展开。

四、连接层参数：config.inc.php

应用唯一需要文件级配置的文件是 /var/www/html/_includes/config.inc.php（由 config.SAMPLE.inc.php 模板生成）。Docker 官方镜像在启动时用环境变量自动生成该文件（机制与生成结果见部署篇 7.1），手写安装（zip/源码方式）则需手工复制模板修改。文件全部参数就五项：

// Path Settings
$web_root = ''; // don't include trailing slash (if you're installing in the root just leave this blank)

// Database Settings
$dbhostname = 'db';
$dbname = 'domainmod';
$dbusername = 'domainmod';
$dbpassword = 'q1w2e3r4';

4.1 $web_root —— 应用部署路径

• 作用：应用部署在域名的子路径时填写，如 https://apps.example.com/domainmod 则写 $web_root = '/domainmod'；部署在站点根（本篇实测形态）保持空字符串。
• 默认值：''（空，站点根）。
• 注意：官方注释明确"结尾不带斜杠"。改错会导致全部静态资源 404，改完刷新浏览器确认页面样式正常即为通过。

4.2 $dbhostname / $dbname / $dbusername / $dbpassword —— 数据库四项

• $dbhostname：数据库主机名。单机部署为本机 localhost；分离部署填数据库服务器地址（镜像部署下是同网络的 db 服务名）。
• $dbname：库名，官方初始化脚本创建 domainmod。
• $dbusername / $dbpassword：连接账号。应用只需要对该库的读写权限。
• 验证闭环：改后重启 Apache（systemctl restart apache2），再登录应用；命令行侧直接核对连库是否通：

mariadb -u domainmod -pq1w2e3r4 -h localhost domainmod -e 'SHOW TABLES;' | head -8

goal_activity
maintenance
migrations
queue
scheduler
settings
ssl_accounts
ssl_certs

五、系统层参数：System Settings 逐项详解

页面路径：Administration → System Settings（/admin/settings/）。一页 15 个字段，分三块：系统设置、错误/调试设置、SMTP 服务器设置。改完点击页面底部 Save，成功统一回显：

The System Settings were updated

以下逐项列出（默认值均为 4.23.0 安装后实测值）。

5.1 Full DomainMOD URL（new_full_url）

• 作用：应用对外访问的完整 URL，邮件里的链接（如到期提醒）用它拼接。
• 默认值：安装向导不填则为空；为空时保存会被拒绝（源码校验原文：Enter the full URL of your DomainMOD installation）。
• 修改-验证闭环（实测）：在页面填入 http://127.0.0.1:8131 保存后核对落库：

mariadb -u domainmod -pq1w2e3r4 domainmod -e 'SELECT full_url FROM settings;'

full_url
http://127.0.0.1:8131

生产环境应填对外正式地址（如 https://domainmod.example.com）；前面挂反向代理终结 HTTPS 后，这里必须填 HTTPS 地址，否则邮件链接可点性差且浏览器报警。

5.2 System Email Address（new_email_address）

• 作用：系统"署名"邮箱，安装向导第五步填的值落在这里（本环境实测 noreply@example.com）；到期提醒等系统邮件的默认 FROM 地址。
• 验证闭环：改后保存 → 设置页重新加载显示新值，同时 settings 表 email_address 字段同步。

5.3 Expiration Days to Display（new_expiration_days）

• 作用：仪表盘与列表页"即将到期"高亮窗口（天数）。默认 60 天。
• 修改-验证闭环（实测，前任测试记录）：把 60 改为 90 保存，回显 The System Settings were updated；落库核对：

mariadb -u domainmod -pq1w2e3r4 domainmod -e 'SELECT expiration_days FROM settings;'

expiration_days
90

同时仪表盘 Expiring in the next 90 days 标题随之变化。到期邮件提醒的发送节奏由 Task Scheduler 的 Send Expiration Email 任务决定（见第六节），这个参数只控制"提前多久开始显示/进入提醒范围"的窗口口径。

5.4 Email Signature（new_email_signature）

• 作用：追加到系统发出邮件（到期提醒、测试邮件）末尾的签名文本，官方模板默认 Sent by DomainMOD。

5.5 Currency Converter（new_currency_converter）

• 作用：汇率数据源开关。v4.23.0 内置选项为 Free Currency Rates API（免费汇率接口），打开后 System → Update Conversion Rates 任务才能自动刷新汇率。
• 默认值：开启（1）。
• 依赖：需要外网可访问 api.frankfurter.app 等免费源；离线环境关闭后汇率需手工维护。

5.6 Large Mode（new_large_mode）

• 作用：大数据量模式开关（官方描述：数据量大时提高部分页面性能的显示模式）。默认关。资产量过万再考虑打开。

5.7 Debugging Mode（new_debug_mode）

• 作用：调试模式开关，打开后系统把错误/SQL 细节写入 Debug Log（Administration → Debug Log 查看页）。
• 默认值：关。排障时临时打开，问题复现后立即关闭。
• 配套项 Local PHP Log（new_local_php_log）：是否把 PHP 错误记录到应用目录本地日志（/var/www/html/temp 下），同样默认关。

5.8 SMTP 服务器设置（八项）

到期邮件能否发出取决于这一组参数。字段与默认值：

修改-验证闭环（实测记录）：打开 Use SMTP Server?，填入 SMTP Server smtp.example.com、协议 TLS、端口 1025、账号 domainmod、密码（演示值）保存；随后到 Administration → Tools → Send Test Email 发一封测试邮件到管理员邮箱，实测回显：

Test Email Sent!

收到邮件即 SMTP 链路打通。注意 4.23 的端口与协议是自由组合（587+TLS、465+SSL 均常见），以邮件服务商文档为准；测试失败时先临时打开 5.7 的调试模式看 Debug Log 的 SMTP 会话错误。

六、调度层参数：Task Scheduler 与到期提醒

页面路径：Administration → Task Scheduler（/admin/scheduler/）。这里不是"参数文件"，而是六个内置任务的运行编排——DomainMOD 的到期提醒、汇率刷新等一切自动化都在此驱动。

6.1 六个内置任务总览（scheduler 表实测）

mariadb -u domainmod -pq1w2e3r4 domainmod \
  -e 'SELECT id,name,expression,active FROM scheduler ORDER BY id;'

id  name                          expression     active
1   Domain Queue Processing       */5 * * * *    1
2   Send Expiration Email         0 0 * * *      1
3   Update Conversion Rates       0 0 * * *      1
4   System Cleanup                0 0 * * *      1
5   Check For New Version         0 0 * * *      1
6   Data Warehouse Build          0 0 * * *      1

逐个说明：

6.2 驱动机制：cron 每 10 分钟一次

Task Scheduler 只是"编排"，真正执行靠系统 cron 每 10 分钟跑一次调度入口（系统 crontab 实测）：

*/10 * * * * domainmod /usr/local/bin/php -q /var/www/html/cron.php > /dev/null

cron.php 每次运行时按 scheduler 表的 expression 判断哪些任务到点。因此：页面里把任务改到某个时刻，实际执行时刻存在 0–10 分钟的调度粒度误差，属正常现象。Docker 官方镜像已内置该 cron；zip 方式手工安装的必须自己加这条 crontab（官方 README「Cron Job」一节明确要求），否则所有任务永远不执行。

6.3 修改任务运行时间（实测闭环）

页面点击任务名进入编辑（如 Send Expiration Email），Runs 段选 Daily、运行时间下拉 00:00–23:00 选 15:00（对应 expression 0 15 * * *），保存回显：

Task Updated

落库核对（页面显示时间与时区见 6.5）：

name                    expression
Send Expiration Email   0 15 * * *

⚠️ 每日任务的运行时间下拉粒度是整点小时；要更细的节奏（如每半小时）需直接改 scheduler 表 expression，官方不保证界面兼容。

6.4 停用 / 启用 / 立即运行（实测闭环）

• 任务行 Disable 按钮 → 回显 Task Disabled（active 落库为 0）；再点 Enable → 回显 Task Enabled。
• Run Now 按钮：立即触发一次任务，不等待到点。Send Expiration Email 立即运行的实测回显：

Expiration Email Sent

Last Run 列同时刷新。这是验证到期提醒链路（SMTP + 窗口 + 订阅）最直接的手段。

6.5 Last Run / Next Run 与时区差异

页面顶部显示 Current Timestamp，每个任务有 Last Run（上次执行）与 Next Run（下次排期）。核对时注意：页面时间按 PHP 时区（TZ=Asia/Shanghai）显示，数据库 scheduler 表的时间戳按 UTC 存储。实测同一时刻：页面显示 10:35:53，库内 last_run 为 02:35:53——差 8 小时不是 bug，排查调度问题时先统一基准（建议都看页面值）。

七、用户层参数：Profile 与 User Defaults

入口：登录后右上角用户菜单 → Settings → Profile（/settings/profile/）与 Settings → Defaults（/settings/defaults/）。只影响当前账号。

7.1 Profile（个人偏好）

实测字段：

到期邮件的完整链路是：SMTP 配置（5.8）+ 到期窗口（5.3）+ 调度任务（6.1 的 Send Expiration Email）+ 用户订阅（这里）。四者缺一不可，排查"没收到提醒邮件"时按此顺序核对。

7.2 Defaults（默认资产下拉）

预设新增域名/证书/SSL 时的默认选项，实测 13 个下拉：

Default DNS, Default IP Address, Default SSL Type, Default Domain Provider Account,
Default SSL Provider Account, Default Domain Category, Default SSL Category,
Default Domain Host, Default SSL Host, Default Expiration Type (Domain),
Default Expiration Type (SSL), Default Payment Method (Domain), Default Payment Method (SSL)

安装后均为 --- Select ---（空）。团队录入量大时先在这里选好默认注册商账号/分类/托管商，新增页面自动预选，显著减少手误。

八、PHP 环境参数（只读核对项）

以下不是 DomainMOD 自己的参数，而是它对运行环境的硬性要求（安装向导第二步自检项，System Information 页可随时复查）：

改这些要去 php.ini（/etc/php/8.2/apache2/php.ini），改完 systemctl restart apache2 后回 System Information 页复查 Pass/Enabled 即为验证。版本超出窗口（如升到 PHP 8.4）4.23 会拒绝安装——这也是官方镜像形态更省心的原因（见部署篇第二节）。

九、生产配置模板

最小模板（单机自用，够用就好）：

• config.inc.php：保持安装默认五项；
• System Settings：填 full_url（对外地址）+ System Email Address，其余默认；
• Task Scheduler：全默认（到期邮件每日 15:00）；
• 用户 Profile：Time Zone 选 Asia/Shanghai，Expiration Emails 改 Yes。

生产模板（团队使用，域名/证书量大）：

• System Settings：full_url 用 HTTPS 对外地址；Expiration Days 按运维 SOP 提前量调整（如 90 天对应"提前一个季度处理续费"）；SMTP 填内部邮件网关并保存后立即 Send Test Email 验证；Debugging Mode 保持关；
• Task Scheduler：Send Expiration Email 按运维值班时间表定时刻；Data Warehouse Build 保持每日（报表量大时依赖它）；
• Defaults：预设默认注册商账号、分类、DNS/托管商；
• 权限：管理员只建一两个，日常录入用普通账号，减少误改系统参数面。

十、常见问题（FAQ）

Q1：改了 System Settings 保存后部分页面没生效？ System Settings 每次保存会同步刷新会话缓存（源码里写回 $_SESSION['s_system_full_url'] 等），刷新页面即可；个别浏览器缓存了旧页面时强制刷新（Ctrl+F5）。

Q2：Send Expiration Email 到点没发信？ 按链路核对：系统 crontab 里有 */10 的 cron.php 条目吗（6.2）→ scheduler.active=1 且到点（6.1）→ SMTP 测试邮件通过吗（5.8）→ 用户 Profile 的 Expiration Emails 是 Yes 吗（7.1）→ 有域名落在窗口内吗（5.3）。四层依次排除。

Q3：系统时间与本地时间差 8 小时？ 两处时区：部署环境的 TZ 环境变量（页面显示）与 Profile 的 Time Zone（个人显示）。数据库内时间戳一律 UTC（6.5）。三者不一致时页面呈现会"错位"，统一为 Asia/Shanghai 即可。

Q4：汇率刷新任务报错？ Currency Converter 指向的免费汇率源需要外网（5.5）；服务器出网受限时任务会失败并写入 Debug Log，可临时关闭该任务（6.4 Disable）或改走可用的代理出口。

Q5：想直接改数据库行不行？ settings/scheduler 表与页面字段一一对应，直接 UPDATE 也能生效，但会绕过校验（如 expiration_days 填 0 会破坏到期计算）。生产变更建议走页面保存（有校验+回显），数据库直改仅用于排障对照。

十一、参考链接

• 官方文档（Settings 与用户指南）：https://domainmod.org/docs/
• GitHub 源码（settings 校验与调度实现）：https://github.com/domainmod/domainmod
• 部署与运行机制：《DomainMOD 4.23 Docker Compose 部署指南》
• 维护与命令行操作：《DomainMOD 4.23 常用 CLI 命令详解》
• 认知与选型：《DomainMOD 4.23 介绍与选型指南》