HumHub 1.19.3 Docker Compose 部署指南

本指南以官方部署仓库 humhub/docker 提供的 compose 形态为准，在主机上实测走通"拉取 → 起栈 → Web 安装向导 → 登录验收 → 备份"全流程。所有命令输入为主机侧实际操作，所有输出为实测回显逐行照抄（2026-11-02）。版本 v1.19.3 为 GitHub Releases 当日查询的最新稳定版。认知与选型见《HumHub 1.19.3 介绍与选型指南》，配置参数语义见《HumHub 1.19.3 配置参数详解》，运维命令见《HumHub 1.19.3 常用 CLI 命令与工具详解》。

一、环境与版本确认

1.1 版本实查

以 GitHub Releases API 查询最新稳定版（2026-11-02）：

curl -s "https://api.github.com/repos/humhub/humhub/releases/latest" | head -30

回显（节选）：

{
  "url": "https://api.github.com/repos/humhub/humhub/releases/425742169",
  "html_url": "https://github.com/humhub/humhub/releases/tag/v1.19.3",
  "id": 425742169,
  "tag_name": "v1.19.3",
  "target_commitish": "master",

同期 releases.atom 顺序为 1.19.3 → 1.19.2 → 1.19.1 → 1.19.0（维护线 1.18.7），确认 1.19.3 为最新稳定版。

1.2 官方 compose 形态

官方 README（humhub/docker 仓库）给出的最小栈是应用服务 + mariadb：应用发行包 humhub/humhub（基于 dunglas/frankenphp:1-php8.4，内置 Web 服务器、PHP 8.4、全部必需扩展、调度器与队列进程，自动 HTTPS），数据库发行包 mariadb（utf8mb4 + InnoDB，官方要求 MariaDB 10.11+ / MySQL 8.0+）。README 的 DSN 写作 mysql:host=db;...，即 HumHub 的 mysql 驱动连 mariadb 服务——MySQL 与 MariaDB 两种数据库形态均被官方支持。

1.3 主机资源与端口规划

项目	本次取值
栈名	humhub-1.19.3-stack
应用发行包	humhub/humhub:1.19.3（1.83GB）
数据库发行包	mariadb:11
专用网络	10.89.64.0/24（显式子网）
Web 端口	8138（映射到应用 80）

二、获取发行包

docker pull humhub/humhub:1.19.3
docker images | grep -E 'humhub|mariadb'

回显：

humhub/humhub:1.19.3    21458d2f294e   1.83GB   415MB
mariadb:11              c4124d1afa87   458MB    108MB

三、编写 compose 文件

主机目录 /opt/humhub（示例）下创建 docker-compose.yml，在官方 README 最小栈基础上做三处生产化调整：显式栈名与子网、本地端口映射、口令替换：

name: humhub-1.19.3-stack

services:
  humhub:
    image: humhub/humhub:1.19.3
    restart: unless-stopped
    ports:
      - "8138:80"
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./humhub-data:/data
    environment:
      - SERVER_NAME=:80
      - HUMHUB_DEBUG=true
      - HUMHUB_CONFIG__COMPONENTS__DB__DSN=mysql:host=db;dbname=humhub
      - HUMHUB_CONFIG__COMPONENTS__DB__USERNAME=root
      - HUMHUB_CONFIG__COMPONENTS__DB__PASSWORD=q1w2e3r4

  db:
    image: mariadb:11
    restart: unless-stopped
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    user: root
    volumes:
      - ./mysql-data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=q1w2e3r4
    expose:
      - "3306"
    healthcheck:
      test: ["CMD", "/usr/local/bin/healthcheck.sh", "--su-mysql", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  backup:
    image: humhub/humhub:1.19.3
    profiles: ["manual"]
    restart: "no"
    command: /app/bin/humhub-backup.sh
    user: root
    volumes:
      - ./humhub-data:/data
      - ./humhub-backup:/backup
    environment:
      - HUMHUB_CONFIG__COMPONENTS__DB__DSN=mysql:host=db;dbname=humhub
      - HUMHUB_CONFIG__COMPONENTS__DB__USERNAME=root
      - HUMHUB_CONFIG__COMPONENTS__DB__PASSWORD=q1w2e3r4

networks:
  default:
    name: humhub-1.19.3-net
    ipam:
      config:
        - subnet: 10.89.64.0/24

要点说明：

SERVER_NAME=:80：让内置 Caddy 以纯 HTTP 监听 80，便于内网/IP 直连场景；生产域名场景写 SERVER_NAME=https://humhub.example.com 即启用自动 HTTPS（官方 README 默认形态）。
三个 HUMHUB_CONFIG__COMPONENTS__DB__* 变量一旦同时给出 DSN 与用户名，入口脚本自动开启安装器免检模式（详见 5.2 排障实录第 3 条），数据库连接信息不再需要在向导里手填。
backup 服务挂在 manual profile 下，平时不启动，备份时一次性运行（见第七章）。
官方示例中 changeMe 类占位口令必须全部替换；本文统一使用示例口令 q1w2e3r4，生产环境请换强口令。

四、启动栈

docker compose up -d

回显（逐行照抄）：

 Network humhub-1.19.3-net Creating 
 Network humhub-1.19.3-net Created 
 Container humhub-1193-stack-db-1 Creating 
 Container humhub-1193-stack-db-1 Created 
 Container humhub-1193-stack-humhub-1 Creating 
 Container humhub-1193-stack-humhub-1 Created 
 Container humhub-1193-stack-db-1 Starting 
 Container humhub-1193-stack-db-1 Started 
 Container humhub-1193-stack-db-1 Waiting 
 Container humhub-1193-stack-db-1 Healthy 
 Container humhub-1193-stack-humhub-1 Starting 
 Container humhub-1193-stack-humhub-1 Started

数据库先经过健康检查（depends_on: condition: service_healthy），确认就绪后才拉起应用。约 30 秒后核对状态：

docker compose ps

NAME                         IMAGE                  COMMAND                  SERVICE   CREATED          STATUS                             PORTS
humhub-1193-stack-db-1       mariadb:11             "docker-entrypoint.s…"   db        31 seconds ago   Up 30 seconds (healthy)            3306/tcp
humhub-1193-stack-humhub-1   humhub/humhub:1.19.3   "docker-php-entrypoi…"   humhub    30 seconds ago   Up 20 seconds (health: starting)   443/tcp, 2019/tcp, 443/udp, 0.0.0.0:8138->80/tcp, [::]:8138->80/tcp

五、Web 安装向导

5.1 向导七步实测

浏览器打开 http://<主机IP>:8138/ 会 302 到 /installer/index。实测用 curl 同样可逐步走通（每步表单带 _csrf），逐步回显如下：

HTTP 302 -> http://localhost:8138/ (redirect: http://localhost:8138/installer/index)
follow: HTTP 200 http://localhost:8138/installer/index

语言选择：ChooseLanguage[language]=en，POST 后进入欢迎页（"Welcome to HumHub ... To continue, click Next."）。
欢迎页：Next 是 GET 链接 /installer/index/go，回显 go: 302 → /installer/setup/prerequisites，随后 final: 200 http://localhost:8138/installer/config/basic——环境预检与数据库两步自动通过并跳过（预检全绿；数据库连接信息已由环境变量注入）。
网络命名（/installer/config/basic，字段 ConfigBasicForm[name]）：填 HumHub Demo，回显 POST basic: 200 → /installer/config/mail。
邮件投递（/installer/config/mail）：1.19 新增独立邮件步，默认 No Delivery (Debug Mode, Save as file) 传输（字段 MailingSettingsForm[transportType]=file），发件人填 admin@example.com 即可先跳过 SMTP，回显 POST mail: 200 → /installer/config/localisation。
语言/时区（/installer/config/localisation，字段 LocalisationForm[language]、LocalisationForm[timeZone]）：选 en-US + Asia/Shanghai，回显 POST localisation: 200 → /installer/config/use-case。
用例预设（/installer/config/use-case，单选 UseCaseForm[useCase]）：提供 intranet（My company）/education/club/community/other 五档，选 intranet，回显 POST usecase: 200 → /installer/config/security。
安全策略（/installer/config/security）：勾选"允许外部注册 + 新注册用户需管理员审批"（SecurityForm[internalAllowAnonymousRegistration]=1、SecurityForm[internalRequireApprovalAfterRegistration]=1），回显 POST security: 200 → /installer/config/admin。
管理员账号（/installer/config/admin，字段 User[username]、User[email]、Password[newPassword]、Password[newPasswordConfirm]、Profile[firstname]、Profile[lastname]）：建 admin / q1w2e3r4，回显 POST admin: 200 → /installer/config/sample-data。
示例内容（/installer/config/sample-data）：勾选后提交，回显 POST sample: 200 → /installer/config/finished，页面输出：

Congratulations . You're done.
The installation completed successfully!

5.2 排障实录

raw.githubusercontent.com 拉取超时。抓官方 compose 示例时 curl https://raw.githubusercontent.com/... 直连与代理均超时（exit 28）。解法：改走 api.github.com/repos/humhub/docker/contents/<path>，返回 base64 的 content 字段解码即得原文。GitHub API 限流时再退到 releases.atom / shields.io。
登录被 302 到 /user/auth/password。用向导里设的 admin / q1w2e3r4 登录，POST /user/auth/login 返回 Location: http://localhost:8138/user/auth/password——HumHub 对安装器创建的账号强制首登改密。在 /user/auth/password 页面再次提交同一组 Login[username]/Login[password] 后回显 Location: http://localhost:8138/dashboard，会话即正常。注意字段名：登录表单是 Login[username]/Login[password]，用成 Username[...] 会原地回到登录页（实测踩坑）。
欢迎页 POST 不前进。对欢迎页盲发 _csrf POST 返回 200 但页面不变——该步 Next 不是表单按钮而是 GET 链接 /installer/index/go，浏览器点 Next 即跳。
启动日志里 HumHub not installed yet. Waiting... 不是故障。应用进程组（调度器/队列）会等待安装与迁移完成再启动，这是官方等待脚本的预期行为，装完自动放行。
Caddy 提示 server is listening only on the HTTP port, so no automatic HTTPS will be applied。SERVER_NAME=:80 纯 HTTP 模式的正常告警；配成 https://域名 后自动证书接管。

5.3 安装结果核验

数据库侧（mariadb 客户端）：

Database
humhub
information_schema
mysql
performance_schema
sys

COUNT(*) tables_humhub
45

humhub 库由安装器自动建库建表（compose 未设 MYSQL_DATABASE），45 张核心表就位。

仪表盘：

dashboard: 200
<title>Dashboard - HumHub Demo</title>

后台进程组随安装完成自动开工（应用日志实测回显）：

[humhub-worker_00] 2026-11-02 06:18:37 [5] humhub\modules\marketplace\jobs\RefreshPendingModuleUpdateCountJob (attempt: 1, pid: 216) - Started
[humhub-worker_01] 2026-11-02 06:18:37 [7] humhub\modules\live\jobs\DatabaseCleanup (attempt: 1, pid: 233) - Started
[humhub-worker_01] 2026-11-02 06:18:37 [7] humhub\modules\live\jobs\DatabaseCleanup (attempt: 1, pid: 233) - Done (0.015 s, 13.95 MiB)
[humhub-worker_00] 2026-11-02 06:18:40 [5] humhub\modules\marketplace\jobs\RefreshPendingModuleUpdateCountJob (attempt: 1, pid: 216) - Done (2.663 s, 13.93 MiB)

队列状态：

Jobs
- waiting: 0
- delayed: 0
- reserved: 0
- done: 0

六、升级与回滚

官方入口脚本在安装完成后每次启动自动执行：cache/flush-all → 核心 migrate/up → module/update-all → 模块 migrate/up --includeModuleMigrations=1（humhub/docker 仓库脚本逻辑，2026-11-02 查阅）。因此升级动作只有三步：

# 1. 先做一次备份（见第七章）
# 2. 改 compose 中的版本 tag，如 1.19.3 -> 1.19.4
sed -i 's/humhub\/humhub:1.19.3/humhub\/humhub:1.19.4/' docker-compose.yml
docker compose up -d humhub
# 3. 观察日志确认迁移完成
docker compose logs --tail 50 humhub

回滚即把 tag 改回旧版本再 up -d；若新版本已执行过数据库迁移，回滚代码版本前必须先用备份恢复数据库，HumHub 不支持数据库降级。

七、备份实测

backup 服务（profiles: manual）挂载数据目录与备份目录后一次性运行官方备份脚本：

docker compose run --rm backup

实测回显：

==== Backup Check Started ====
OK: Running as PID 1
OK: /data is mounted
OK: /backup is mounted
Source /data: /dev/sda2
Source /backup: /dev/sda2
WARNING: Both mountpoints reference the same source!

Expected backup size:         1M
Optimal minimum storage size: 2M
Available storage size:       123647M
OK: Available backup storage is sufficient
OK: Database connection successful.

All checks completed successfully.
==== Backup Check Finished ====

==== Backup Started  ====

 - mariadb-dump ... OK
 - storage-dump ... OK
 - backup-tar ... OK

==== Backup Finished ====

产物：

-rw-r--r-- 1 root root 133120 Nov  2 14:26 humhub_backup_20261102062609.tar

备份包含数据库 dump + 上传/配置目录打包。回显中 WARNING: Both mountpoints reference the same source! 是脚本在提示 /data 与 /backup 落在同一磁盘——功能不受影响，但生产环境应把备份目录放独立磁盘/异地。定时化很简单：给该服务挂一条主机 crontab 或用带 --rm 的 systemd timer 周期触发即可。

八、下线与清理

docker compose down          # 停栈删服务实例与网络（数据目录在主机，保留）
docker compose down -v       # 额外删除匿名卷（本项目数据在 bind mount，谨慎）

九、部署检查清单

发行包 tag 固定为具体版本（如 1.19.3），生产勿裸用 latest
MYSQL_ROOT_PASSWORD 与 HUMHUB_CONFIG__COMPONENTS__DB__PASSWORD 已换成强口令（本文 q1w2e3r4 仅为示例）
生产 SERVER_NAME 配 https 域名，443/443/udp 端口放行以启用自动证书与 HTTP/3
邮件传输在向导第 4 步或管理后台配置真实 SMTP（file 调试模式仅适合装完验收）
备份目录独立于数据盘，docker compose run --rm backup 已进定时任务
首登管理员后完成强制改密（见 5.2 第 2 条）