DomainMOD 4.23 Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用 Docker Compose 从零部署 DomainMOD 4.23（自托管域名与 SSL 证书资产管理台账），覆盖官方镜像选型、MariaDB 数据库编排、Web 安装向导、初始账号交接、数据持久化、升级与备份的完整闭环。全流程已在 Ubuntu 22.04 + Docker Engine 29.9.2 + Docker Compose v5.6.1 环境实测通过（应用版本 v4.23.0 为官方最新稳定版，2026-10-26 经官方 Releases 核实）。软件定位与选型背景见 《DomainMOD 4.23 介绍与选型指南》；运行参数逐项说明见 《DomainMOD 4.23 配置参数详解》。

一、环境信息

本篇实测部署所用的服务器环境与组件版本如下：

架构关系：Compose 编排两个服务——app（DomainMOD 应用，内置 Apache 2.4.69 + PHP 8.2 + cron 计划任务）与 db（MariaDB 10.11），同挂一个自定义 bridge 网络，app 依赖 db 健康检查通过后再启动。

二、镜像与部署形态选型

DomainMOD 官方提供四种获取方式（来源：官方仓库 README「Downloading」，2026-10-26 核实）：

选 Docker 镜像的关键理由：官方 README 明确的 PHP 支持窗口是 8.1–8.2.9，而 2026 年主流发行版软件源里的 PHP 已是 8.3/8.4，zip 方式需要自己卡版本；官方镜像内置 PHP 8.2.35 与每 10 分钟一次的 cron 计划任务，任务调度器（到期邮件、汇率刷新等）开箱即用，是自托管场景的最短路径。

镜像版本固定用 4.23.0 标签而不是 latest，保证升级动作显式可控。镜像实测大小：

docker images domainmod/domainmod --format '{{.Repository}}:{{.Tag}}  {{.Size}}'

domainmod/domainmod:4.23.0  918MB  9d50d450ad4d

三、前置条件

1. Docker Engine 与 Compose v2 插件。验证（实测回显）：

docker compose version

Docker Compose version v5.6.1

2. 端口可用：应用映射服务器 8131，先确认未被占用：

ss -ltn | grep 8131

LISTEN 0      4096         0.0.0.0:8131       0.0.0.0:*
LISTEN 0      4096            [::]:8131          [::]:*

⚠️ 若输出为空则端口空闲可放行；若已被其他进程占用（上面两行为本篇部署完成后的自身监听状态），把 compose 文件里 "8131:80" 改为其他空闲端口即可。

3. 外发邮件通道（可选但建议）：DomainMOD 的核心价值之一是到期邮件提醒。默认用 PHP mail() 本机发信，多数服务器需要转外部 SMTP——部署完成后在系统设置里配置（步骤见 《DomainMOD 4.23 配置参数详解》配置篇的 SMTP 节，本篇不展开）。

四、部署步骤

本节从空目录开始，完成「编排文件 → 启动 → Web 安装向导 → 初始账号交接 → 部署验证」的完整主线。

4.1 建部署目录与编排文件

mkdir -p /opt/domainmod && cd /opt/domainmod

创建 docker-compose.yml（完整内容如下，逐项说明见第六、七节）：

name: domainmod-4.23.0-stack

services:
  app:
    image: domainmod/domainmod:4.23.0
    container_name: domainmod-4230-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: "Asia/Shanghai"
      DOMAINMOD_WEB_ROOT: ""
      DOMAINMOD_DATABASE_HOST: db
      DOMAINMOD_DATABASE: domainmod
      DOMAINMOD_USER: domainmod
      DOMAINMOD_PASSWORD: q1w2e3r4
    ports:
      - "8131:80"
    volumes:
      - ./temp:/var/www/html/temp
      - ./uploads:/var/www/html/uploads
    networks:
      - domainmodnet

  db:
    image: mariadb:10.11
    container_name: domainmod-4230-db
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: domainmod
      MARIADB_USER: domainmod
      MARIADB_PASSWORD: q1w2e3r4
      TZ: "Asia/Shanghai"
    volumes:
      - ./db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 5s
      retries: 20
    networks:
      - domainmodnet

networks:
  domainmodnet:
    name: domainmod-4.23.0-net
    driver: bridge

编排要点解读：

• depends_on + condition: service_healthy：应用等数据库健康检查通过才启动，避免 PHP 连库失败；
• 数据库三个 MARIADB_* 变量与 app 的三个 DOMAINMOD_DATABASE* 变量一一对应（库名 domainmod、账号 domainmod、密码一致）；
• MariaDB 自带 healthcheck.sh（官方 10.11 镜像内置），--innodb_initialized 表示 InnoDB 初始化完成，是可靠的就绪信号；
• 两个服务的 restart: unless-stopped 保证服务器重启后栈自动拉起。

4.2 启动编排栈

docker compose up -d

实测输出（逐行照抄）：

 Network domainmod-4.23.0-net Creating
 Network domainmod-4.23.0-net Created
 Container domainmod-4230-db Creating
 Container domainmod-4230-db Created
 Container domainmod-4230-app Creating
 Container domainmod-4230-app Created
 Container domainmod-4230-db Starting
 Container domainmod-4230-db Started
 Container domainmod-4230-db Waiting
 Container domainmod-4230-db Healthy
 Container domainmod-4230-app Starting
 Container domainmod-4230-app Started

关键节点是 Container domainmod-4230-db Healthy：Compose 等待健康检查通过后才启动 app，这正是 service_healthy 条件生效的证据。首启动时 MariaDB 初始化约需 10–30 秒（建系统表 + 应用库 domainmod），app 随后自动启动。

验证两个服务的状态：

docker compose ps

NAME                 IMAGE                        COMMAND                  SERVICE   CREATED          STATUS                    PORTS
domainmod-4230-app   domainmod/domainmod:4.23.0   "docker-php-entrypoi…"   app       36 minutes ago   Up 36 minutes             0.0.0.0:8131->80/tcp, [::]:8131->80/tcp
domainmod-4230-db    mariadb:10.11                "docker-entrypoint.s…"   db        36 minutes ago   Up 36 minutes (healthy)   3306/tcp

db 显示 (healthy)、app 映射 0.0.0.0:8131->80，编排栈就绪。

4.3 Web 安装向导（六步）

⚠️ 数据库连接无需在向导里填写——app 启动时已由环境变量自动生成配置文件（机制见第七节），向导只负责语言、环境检查与时区、邮箱。

浏览器打开 http://<服务器IP>:8131，自动跳转到安装向导，逐步进行：

第一步：选择语言。页面标题 DomainMOD :: Select Your Language，v4.23.0 已内置 30 余种界面语言（عربي、বাংলা、中文（简体）、中文（繁體)、Deutsch、English (US)、Español、Français、हिन्दी、日本語、한국인、Português、Русский язык、Türkçe、Tiếng Việt 等）。本篇选择 English (US)，点击 Begin Installation。

第二步：软件需求自检。页面标题 DomainMOD :: Software Requirements，逐项检查运行环境，全部应为 Pass / Enabled。本环境实测回显（原文照抄）：

Server Software
PHP 8.1-8.2.9: Pass
MariaDB (10.4-11.1.2) or MySQL (5.7-8.1.0): Pass
PHP Extensions
PDO: Enabled
cURL: Enabled
OpenSSL: Enabled
gettext: Enabled
PHP Settings
allow_url_fopen: Enabled

七项全绿后点击 Next Step。若有 Fail/Disabled 项，按提示补装对应 PHP 扩展或调整 php.ini 后重试。

第三步：选择时区。页面标题 DomainMOD :: Select Your Time Zone，在完整 IANA 时区列表中选择（本篇选 Asia/Shanghai），点击 Next Step。

第四步：管理员邮箱。页面标题 DomainMOD :: Administrator Email Address——该邮箱用于安装过程中创建的第一个管理员账号。填入并确认（本篇演示用 admin@example.com），点击 Next Step。

第五步：系统邮箱。页面标题 DomainMOD :: System Email Address——用于系统各处的发件地址，例如到期提醒邮件的 FROM 地址。填入并确认（本篇演示用 noreply@example.com），点击 Proceed With Installation。

第六步：执行安装。系统自动建库表、写入初始数据，完成后跳转登录页。若此时再次访问 /install/ 路径，会看到明确的防重复安装提示（原文照抄）：

Alert!
Installation failed
DomainMOD is already installed
You should delete the /install/ folder

这条提示说明安装标记已生效：系统已拒绝重复安装。

4.4 初始账号与首次改密

安装完成后的默认管理员账号由安装程序写死：用户名 admin、密码 admin（安装完成提示原文：The default username and password are "admin", and you'll be prompted to change the password after logging in）。

在登录页输入 admin / admin 登录，系统强制跳转到修改密码页（DomainMOD :: Change Password）。设置新密码（本篇演示统一用 q1w2e3r4，生产环境请使用强密码）并提交，成功后自动回主界面。

命令行侧同样可以验证这套登录与改密流程（curl 实测，登录成功后服务端 302 到 checks.php 完成会话初始化）：

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

随后跟随 checks.php 完成→dashboard，即进入正常工作台。

4.5 部署验证

以 admin 登录后，进入 Administration → System Information，核对整栈版本与运行环境（实测原文照抄）：

DomainMOD Version: 4.23.0 (4.23.0)
Web Server Software: Apache/2.4.69 (Debian)
PHP Version: 8.2.35
MySQL Version: 10.11.19-MariaDB-ubu2204
MySQL Mode: NO_ENGINE_SUBSTITUTION
Server Software: PHP 8.1-8.2.9: Pass, MariaDB (10.4-11.1.2) or MySQL (5.7-8.1.0): Pass
PHP Extensions: PDO: Enabled, cURL: Enabled, OpenSSL: Enabled, gettext: Enabled
PHP Settings: allow_url_fopen: Enabled

四项关键值与选型一致（应用 4.23.0、Apache 2.4.69、PHP 8.2.35、MariaDB 10.11.19），且需求自检全部 Pass/Enabled——部署闭环完成。

💡 说明：System Information 页的 Web Server OS 会显示服务器内核信息（如 Linux ... 7.0.0-38-generic ... x86_64），可用于确认应用确实跑在预期机器上。

五、数据持久化说明

编排文件共三个 bind mount 持久化点，删除/重建应用服务都不丢数据：

实测数据目录规模（初始安装即约 216MB，主要为 MariaDB 系统表空间）：

du -sh /opt/domainmod/db

216M    /opt/domainmod/db

⚠️ 应用代码目录不挂载、不持久化——应用版本完全由镜像 tag 决定，升级走「换镜像 + 应用自升级目录」机制（见第 10.3 节），不要手工改动应用目录。

六、环境变量表

6.1 app 服务（domainmod/domainmod:4.23.0）

6.2 db 服务（mariadb:10.11）

⚠️ MARIADB_* 变量只在数据目录首次初始化时生效；改密码后重建栈不会自动改已初始化实例的密码，需用 root 登库手工改。

七、配置参数说明

7.1 应用配置文件的自动生成

官方镜像的入口脚本在每次启动时，把模板 /var/www/html/_includes/config.SAMPLE.inc.php 里的占位值替换成环境变量，生成实际生效的 /var/www/html/_includes/config.inc.php（入口脚本核心逻辑，原文照抄）：

SAMPLE_CONFIG_FILE="/var/www/html/_includes/config.SAMPLE.inc.php"
OUTPUT_CONFIG_FILE="/var/www/html/_includes/config.inc.php"

sed -e "s|/dm|${DOMAINMOD_WEB_ROOT}|g" \
    -e "s|localhost|${DOMAINMOD_DATABASE_HOST}|g" \
    -e "s|db_name|${DOMAINMOD_DATABASE}|g" \
    -e "s|db_username|${DOMAINMOD_USER}|g" \
    -e "s|dbPassword123|${DOMAINMOD_PASSWORD}|g" \
    $SAMPLE_CONFIG_FILE > $OUTPUT_CONFIG_FILE

本环境实测生成的 config.inc.php 内容（口令部分为演示值）：

// 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';

五个变量正好对应 compose 里的五个 DOMAINMOD_* 环境变量。因此改数据库连接的唯一正确姿势是改 compose 环境变量并重建 app 服务，直接手改 config.inc.php 会在下次启动被覆盖。

7.2 内置 cron 计划任务

入口脚本随后 service cron start 拉起计划任务，系统 crontab 实测内容（原文照抄）：

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

即每 10 分钟以 domainmod 用户执行一次调度器入口 cron.php，驱动 Task Scheduler 里的六个内置任务（域名队列处理、到期邮件、汇率刷新、系统清理、新版本检查、数据仓库构建）。没有这条 cron，Web 界面里配好的任务永远不会真正执行——这是 DomainMOD 可用性的命门，官方镜像已内置，无需手工配置。

7.3 应用目录权限

入口脚本最后执行 chown -R domainmod:domainmod /var/www/html 与 chmod 777 /var/www/html/temp：temp 目录全局可写是 Web 端 Backup & Restore 功能的硬性前置（官方备份页原文：Before you can use Backup & Restore you must update the permissions on the /var/www/html/temp folder）。镜像已自动完成，zip 手工安装的用户需自己执行。

八、配置文件挂载

本部署形态不需要额外挂载配置文件——数据库连接由环境变量生成（7.1），系统参数全部存数据库、Web 界面修改（见配置篇），cron 内置（7.2）。需要定制 PHP 参数（如 upload_max_filesize）或反向代理 TLS 时，再按需追加挂载：

九、等价 docker run

不使用 Compose 时，两条 docker run 可复现等价部署（先自建网络，再分别起库与应用；逐条给出、每条独立可执行）：

docker network create domainmod-4.23.0-net

docker run -d --name domainmod-4230-db \
  --network domainmod-4.23.0-net \
  -e MARIADB_ROOT_PASSWORD=q1w2e3r4 \
  -e MARIADB_DATABASE=domainmod \
  -e MARIADB_USER=domainmod \
  -e MARIADB_PASSWORD=q1w2e3r4 \
  -e TZ=Asia/Shanghai \
  -v /opt/domainmod/db:/var/lib/mysql \
  mariadb:10.11

docker run -d --name domainmod-4230-app \
  --network domainmod-4.23.0-net \
  -e PUID=1000 -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e DOMAINMOD_WEB_ROOT="" \
  -e DOMAINMOD_DATABASE_HOST=db \
  -e DOMAINMOD_DATABASE=domainmod \
  -e DOMAINMOD_USER=domainmod \
  -e DOMAINMOD_PASSWORD=q1w2e3r4 \
  -p 8131:80 \
  -v /opt/domainmod/temp:/var/www/html/temp \
  -v /opt/domainmod/uploads:/var/www/html/uploads \
  domainmod/domainmod:4.23.0

⚠️ 等价命令需先等数据库完成初始化再启动 app（Compose 的 service_healthy 自动做了这件事），手工执行时建议 db 启动约 30 秒后再起 app。日常使用仍推荐 Compose 编排。

十、常用运维命令

10.1 状态与日志

docker compose ps          # 两服务状态（db 应为 healthy）
docker compose logs -f app # 应用日志（Apache/PHP 访问与错误）
docker compose logs -f db  # 数据库日志
docker compose restart app # 仅重启应用
docker compose down        # 停止并移除栈（保留 ./db 数据目录）

10.2 数据库备份（命令行）

docker exec domainmod-4230-db sh -c \
  'mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" domainmod' > domainmod-$(date +%F).sql

ls -la domainmod-2026-10-26.sql

-rw-r--r-- 1 root root 96617 Oct 26 10:37 domainmod-2026-10-26.sql

⚠️ 输出文件头会标明 -- Server version 10.11.19-MariaDB-ubu2204，可用于核对备份完整性。Web 端还有一键全库备份（下载 domainmod-backup.sql），用法详见 《DomainMOD 4.23 常用 CLI 命令详解》命令篇的备份节。

10.3 升级

DomainMOD 的升级是「换镜像 + 启动时自动合并新版本代码」：

1. 修改 compose 文件中的镜像标签（如 4.23.0 → 新版本号）；
2. 执行 docker compose pull && docker compose up -d。

官方入口脚本内置升级机制：镜像内携带新版本代码包 /var/www/new_version，启动时若该目录非空则整体复制覆盖到应用目录再清空（入口脚本原文）：

if [ -n "$(ls -A /var/www/new_version)" ]; then

    cp -R /var/www/new_version/. /var/www/html \
    && rm -Rf /var/www/new_version

fi

数据库结构升级由应用在启动访问时自动比对 settings 表中的 db_version 完成。升级前务必先执行 10.2 的备份；回滚就是把 compose 镜像标签改回旧版本再 up -d，并恢复备份 SQL。

10.4 计划任务健康检查

确认内置 cron 与调度器在跑（登录 Web → Administration → Task Scheduler，各任务应显示最近一次的 Last Run 时间戳与 Next Run 下次运行时间）。本环境实测节选（原文照抄）：

Current Timestamp: 2026-10-26 09:40:50
Domain Queue Processing   Runs: Every 5 Minutes   Status: Active   Last Run: 2026-10-26 09:40:01 ( 0s )   Next Run: 2026-10-26 09:45:00
Send Expiration Email     Runs: Daily             Status: Active   Last Run: -                            Next Run: 2026-10-26 15:00:00

Last Run 持续刷新即说明 cron 链路健康；调度任务的逐项含义与运行时间调整见配置篇。

十一、常见问题（FAQ）

Q1：启动时 app 反复重启/页面报数据库连接错误？ 先看 docker compose ps——db 未到 healthy 时 app 不该被拉起；若 db 一直是 restarting，多半是数据目录被旧实例占用或属主异常，检查 /opt/domainmod/db 的磁盘空间与 docker compose logs db。healthcheck 给了 5s×20 次共约 100 秒的初始化窗口，慢盘首次启动超时可把 interval 放宽到 10s、retries 加大。

Q2：浏览器访问 /install/ 提示 "DomainMOD is already installed"？ 安装标记在数据库 settings 表里，说明这套数据目录已经完成过安装。若确要重装：停栈、清空 /opt/domainmod/db、删除 temp 下的备份文件后重新 docker compose up -d，再走向导。

Q3：到期邮件发不出去？ 默认走 PHP mail()，多数服务器不具备直投条件。进入 Administration → System Settings 打开 Use SMTP Server?，填外部 SMTP（服务器、协议 TLS/SSL、端口、账号），保存后用 Administration → Tools → Send Test Email 发一封测试邮件验证。逐字段说明与实测回显见配置篇 SMTP 节。

Q4：页面显示的时间与数据库时间差 8 小时？ 设计如此：页面时间按 TZ 环境变量（Asia/Shanghai）显示，数据库内时间戳按 UTC 存储（如页面 10:35:53 对应库内 02:35:53）。核对日志或排查调度问题时先统一时区基准。

Q5：忘记 admin 密码？ 用数据库 root 账号登库改 users 表超纲且不推荐；正确做法是恢复一份装有已知密码的备份（Administration → Tools → Backup & Restore → Restore Entire Database），恢复后系统会登出并用备份内的账号登录。因此改密后应立即做一次全库备份。

Q6：8131 端口想换成 80/443 直接对外？ 改 compose 的 ports 映射（如 "80:80"）即可；对外标准 HTTPS 建议走反向代理终结 TLS（见第八节），应用侧把 Full DomainMOD URL 改为对外地址，保证邮件里的链接可点。

十二、卸载与清理

cd /opt/domainmod
docker compose down              # 停止并移除容器与网络（数据目录保留）
docker rmi domainmod/domainmod:4.23.0 mariadb:10.11   # 如需释放镜像
rm -rf /opt/domainmod            # 确认不再需要数据后删除全部数据

⚠️ rm -rf /opt/domainmod 会永久删除全部域名/证书台账数据，执行前务必确认已有有效备份 SQL 在部署目录之外。

十三、参考链接

• DomainMOD 官网：https://domainmod.org
• GitHub 仓库（README Requirements / Downloading / Cron Job）：https://github.com/domainmod/domainmod
• Docker Hub 官方镜像：https://hub.docker.com/r/domainmod/domainmod
• 官方文档（用户指南）：https://domainmod.org/docs/
• 本专栏认知篇：《DomainMOD 4.23 介绍与选型指南》