Openfire 5.1.2 Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Openfire 5.1.2 官方镜像（含可选 MySQL 外部数据库服务），覆盖 compose 编排文件、JVM 堆限制、数据持久化、初始化向导与部署后验证，并沉淀实测中踩到的挂载与属主两个关键坑。

一、环境信息

项目	内容
宿主系统	Ubuntu 24.04
Docker / Compose	Docker 29.9.2，Compose v2
Openfire 镜像	ghcr.io/igniterealtime/openfire:v5.1.2（官方维护）
MySQL 镜像	mysql:8.0（可选外部数据源，预留）
JVM 堆	-Xms256m -Xmx512m
Compose 项目名	openfire-5-1-2-stack
演示域名 / 账号	im.example.com；admin / q1w2e3r4

版本与镜像背景见《Openfire 5.1.2 介绍与选型指南》；裸机安装方式见《Ubuntu 24.04 安装 Openfire 5.1.2 指南》。

二、端口规划

宿主端口从 8137 起连续映射，避开常用服务端口：

宿主端口	目标端口	用途
8137	9090	管理控制台 HTTP
8138	9091	管理控制台 HTTPS
8139	5222	客户端连接（C2S）
8140	5223	客户端连接 TLS
8141	5269	服务器互联（S2S）
8142	7070	HTTP Binding（BOSH）
8143	7443	HTTP Binding TLS（WebSocket）
8144	7777	文件传输代理

三、编写 compose.yml

mkdir -p /opt/openfire-stack/data/{lib,logs,mysql}
cd /opt/openfire-stack

docker-compose.yml 全文（实测可用版本）：

name: openfire-5-1-2-stack
services:
  openfire:
    image: ghcr.io/igniterealtime/openfire:v5.1.2
    container_name: openfire-5-1-2-main
    hostname: openfire-main
    restart: unless-stopped
    environment:
      - OPENFIRE_OPTS=-Xms256m -Xmx512m
    ports:
      - "8137:9090"   # Admin console HTTP
      - "8138:9091"   # Admin console HTTPS
      - "8139:5222"   # Client to server
      - "8140:5223"   # Client to server TLS
      - "8141:5269"   # Server to server
      - "8142:7070"   # HTTP binding
      - "8143:7443"   # HTTPS binding
      - "8144:7777"   # File transfer proxy
    volumes:
      - ./data/lib:/var/lib/openfire
      - ./data/logs:/var/log/openfire
      - openfire-embedded-db:/usr/local/openfire/embedded-db
    networks:
      - openfire-net

  mysql:
    image: mysql:8.0
    container_name: openfire-5-1-2-mysql
    hostname: openfire-mysql
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=q1w2e3r4
      - MYSQL_DATABASE=openfire
      - MYSQL_USER=openfire
      - MYSQL_PASSWORD=q1w2e3r4
    volumes:
      - ./data/mysql:/var/lib/mysql
    networks:
      - openfire-net

networks:
  openfire-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

volumes:
  openfire-embedded-db:

三个编排要点（均为实测结论）：

JVM 堆：官方镜像通过 OPENFIRE_OPTS 传递 JVM 参数，固定 -Xms256m -Xmx512m 防止内存失控；后续在管理台可见堆上限 512MB 生效。
必须整体挂载 /var/lib/openfire：官方镜像的入口脚本把 conf/、logs/、plugins/ 三个子目录软链到 /var/lib/openfire 下并在缺失时复制初始模板。⚠️ 若只单独挂载 conf 子目录，软链判断失效、模板不复制，服务启动报 Critical Error! The home directory has not been configured（详见常见问题 1）。
embedded-db 必须单独命名卷：内嵌数据库位于 /usr/local/openfire/embedded-db，不在上述软链清单内，挂载 /var/lib/openfire 不会使其持久化；同时空命名卷默认 root 属主，会因 openfire.lck 权限不足启动失败（详见常见问题 2）。
网段 10.89.61.0/24 为显式指定，用于规避与宿主上其他网络的地址冲突，可按环境调整或删除整段 ipam 配置。

四、启动

docker compose up -d

查看状态（Up (healthy) 来自 5.1.0 起镜像自带的 healthcheck，OF-3184）：

docker compose ps

实测回显：

NAME                   IMAGE                                    COMMAND                  SERVICE    CREATED          STATUS                    PORTS
openfire-5-1-2-main    ghcr.io/igniterealtime/openfire:v5.1.2   "/sbin/entrypoint.sh"    openfire   46 minutes ago   Up 46 minutes (healthy)   3478-3479/tcp, 5005/tcp, 5229/tcp, 5262-5263/tcp, 5275-5276/tcp, 0.0.0.0:8139->5222/tcp, 0.0.0.0:8140->5223/tcp, 0.0.0.0:8141->5269/tcp, 0.0.0.0:8142->7070/tcp, 0.0.0.0:8143->7443/tcp, 0.0.0.0:8144->7777/tcp, 0.0.0.0:8137->9090/tcp, 0.0.0.0:8138->9091/tcp
openfire-5-1-2-mysql   mysql:8.0                                "docker-entrypoint.s…"   mysql      46 minutes ago   Up 46 minutes             3306/tcp, 33060/tcp

五、初始化向导

浏览器访问 http://<宿主IP>:8137 进入 Openfire Setup 向导，五步：

语言选择：默认 English；
服务器设置：域名 im.example.com（生产填真实对外域名），其余默认；
数据源：本篇实测选择默认 Embedded Database（数据落在 openfire-embedded-db 命名卷）；如需外部库可选 Standard Database Connection，JDBC 主机填 openfire-mysql:3306、库名 openfire、账号 openfire/q1w2e3r4（compose 已预留该服务与库；MySQL 外部库路径未在本篇实测展开，以官方文档为准）；
用户资料：默认数据库存储；
管理员账户：跳过（默认 admin/admin）。

⚠️ 脚本化驱动向导时注意：数据源步骤第一次 POST 返回 200 但库并未初始化，页面中还有隐藏的 followup 表单（csrf/next/mode/continue 字段），需两段式提交才能完成数据源写入；浏览器人工操作则无感。

完成后登录管理台并立即改密：Users/Groups → admin → Password 改为 q1w2e3r4，返回：

user-password.jsp?success=true&username=admin

六、部署验证

用 admin / q1w2e3r4 登录 http://<宿主IP>:8137，控制台首页（Server Information）实测显示：

Version: Openfire 5.1.2  Server Directory: /usr/local/openfire  XMPP Domain Name: im.example.com
Java Version: 17.0.19 Eclipse Adoptium -- OpenJDK 64-Bit Server VM
Appserver: jetty/12.0.38  Server Host Name (FQDN): im.example.com  OS / Hardware: Linux / amd64
Memory 147.88 MB of 512.00 MB (28.9%) used

Memory … of 512.00 MB 证明 OPENFIRE_OPTS 的堆上限已生效。再从宿主确认关键端口映射连通：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8137/login.jsp

5222 等 XMPP 端口在向导完成后才会开始监听，用 nc -zv <宿主IP> 8139 或直接跑一个 XMPP 客户端验证。

七、日常运维

docker compose logs -f openfire      # 跟踪日志
docker compose restart openfire      # 重启 Openfire
docker compose stop && docker compose up -d   # 停止与再启动
docker compose down                  # 停止并移除（命名卷保留）

数据持久化清单：

挂载点	宿主位置	内容
/var/lib/openfire	./data/lib	conf/（openfire.xml 等）、plugins/
/var/log/openfire	./data/logs	运行日志
/usr/local/openfire/embedded-db	命名卷 openfire-embedded-db	内嵌数据库全部文件
/var/lib/mysql	./data/mysql	MySQL 数据（启用外部库时使用）

升级时替换 image 标签后 docker compose up -d 重建即可，以上持久化数据均不随重建丢失。

八、常见问题

1. 启动报 Critical Error! The home directory has not been configured 原因：只把 conf 子目录单独挂载到 /var/lib/openfire/conf，入口脚本判断 conf 目录"已存在"而跳过模板复制。解决：整体挂载 /var/lib/openfire（如本篇 compose），删除该子目录挂载后 docker compose up -d 重建。

2. 内嵌库启动报 Permission denied（openfire.lck） 原因：openfire-embedded-db 空命名卷默认 root 属主，Openfire 进程以 uid 100/gid 101 运行无法写入。解决：

docker run --rm -v openfire-5-1-2-stack_openfire-embedded-db:/db busybox chown -R 100:101 /db
docker compose restart openfire

3. 管理台登录报 500（Database setup or configuration error） 原因：向导数据源步骤未真正完成（脚本化驱动时常见，见两段式提交说明）。解决：清空 embedded-db 命名卷后重新走完向导，或人工在浏览器完整走一遍向导。

4. 8139（5222）端口连不通 向导未完成前 XMPP 端口不监听，属正常现象；完成向导后即恢复。

九、参考

官方镜像：https://github.com/igniterealtime/openfire-docker-documentation （镜像 ghcr.io/igniterealtime/openfire）
Openfire 官方文档：https://docs.igniterealtime.org/openfire/
站内：《Openfire 5.1.2 介绍与选型指南》、《Ubuntu 24.04 安装 Openfire 5.1.2 指南》