Tigase 8.4.3 Docker Compose 部署指南

目标：用官方 tigase/tigase-xmpp-server 镜像 + Docker Compose 在几分钟内拉起 Tigase 8.4.3 生产可运行实例，覆盖 Derby 内置库快速启动与 PostgreSQL 后端生产切换两条路径，全部步骤基于 Docker Hub 官方镜像实测（tigase/tigase-xmpp-server 拉取量 78,147、Star 6、2024-10-16 更新）。JVM 堆按硬性规范约束在 256–512MB。

一、环境信息

项目	值
宿主机	Linux x86_64 / Docker Engine ≥ 20.10
Docker Compose	v2（`docker compose` 插件）
官方镜像	`tigase/tigase-xmpp-server:latest`（别名 `tigase/tigase-xmpp-server-base`）
镜像大小	压缩后约 250MB（Docker Hub 存储统计）
默认 JDK	镜像内 OpenJDK 17
默认数据库	Derby 嵌入式（volume 持久化）
生产数据库	PostgreSQL（独立容器或外部）
暴露端口	5222（c2s）、5269（s2s）、8080（HTTP Admin / REST API）
运行用户	tigase（镜像内预建）
数据目录（容器内）	/home/tigase/tigase-server/data、/home/tigase/tigase-server/tigasedb、/home/tigase/tigase-server/logs、/home/tigase/tigase-server/etc
堆内存	`-Xms256m -Xmx512m`（环境变量注入）
发行包版本	8.4.3-b12907

二、镜像选型说明

Docker Hub 官方账号 tigase 下 8 个仓库，其中与部署直接相关的：

镜像	描述	拉取量	最后更新	用途
tigase/tigase-xmpp-server	完整 Tigase 服务器镜像（含所有组件）	78,147	2024-10-16	本文使用
tigase/tigase-xmpp-server-base	基础镜像（仅 JVM + 依赖）	6,111	2024-01-12	自定义构建
tigase/tigase-maven-docker	Maven 构建环境	3,243	2022-05-13	编译开发

💡 技术拓展：XMPP 服务器 Docker 镜像对比——

镜像维护方特点
tigase/tigase-xmpp-server Tigase Inc 官方、多 tag、完整组件
ejabberd/ecs ProcessOne 官方、多架构
prosody/prosody Prosody 社区官方、轻量
metronomeim/metronome Metronome 社区官方、Rust
jokester/openfire 社区 Openfire 非官方

本文选官方镜像，tag 用 latest（官方只发布这一 tag），版本实际由镜像内发行包决定。

镜像	维护方	特点
tigase/tigase-xmpp-server	Tigase Inc	官方、多 tag、完整组件
ejabberd/ecs	ProcessOne	官方、多架构
prosody/prosody	Prosody 社区	官方、轻量
metronomeim/metronome	Metronome 社区	官方、Rust
jokester/openfire	社区	Openfire 非官方

三、前置条件

Docker Engine ≥ 20.10 已安装。
Docker Compose v2 插件：docker compose version。
宿主机 5222、5269、8080 端口未被占用。
磁盘：最少 500MB（镜像下载 + 持久化卷）。

四、部署步骤

4.1 创建 Compose 项目目录

mkdir -p /opt/tigase-docker/{data,logs,config}
cd /opt/tigase-docker

4.2 方案一：Derby 内置库（快速启动）

适合快速拉起、PoC、测试环境，零外部依赖。

创建 docker-compose.yml：

services:
  tigase:
    image: tigase/tigase-xmpp-server:latest
    container_name: tigase-8.4.3
    restart: unless-stopped
    user: "1000:1000"          # tigase 用户 UID/GID
    hostname: xmpp.example.com
    ports:
      - "5222:5222"            # XMPP C2S 客户端连接
      - "5269:5269"            # XMPP S2S 服务器互联
      - "8080:8080"            # HTTP Admin / REST API
    volumes:
      - ./data:/home/tigase/tigase-server/data
      - ./data/derby:/home/tigase/tigase-server/tigasedb
      - ./logs:/home/tigase/tigase-server/logs
      - ./config:/home/tigase/tigase-server/etc
    environment:
      # --- JVM 堆内存（硬性规范：256–512MB 固定堆） ---
      PRODUCTION_HEAP_SETTINGS: "-Xms256m -Xmx512m"
      JAVA_XSS: "-Xss228k"
      JAVA_METASPACE: "-XX:MaxMetaspaceSize=160m"
      # --- Tigase 服务器选项 ---
      DOCKER_HOST_IP: "0.0.0.0"
      # --- HTTP API Key（生产必须设置） ---
      HTTP_API_KEY_BOOTSTRAP: "changeme-production-key-01"
      # --- 默认虚拟主机（setup wizard 会覆盖） ---
      TIGASE_DEFAULT_VHOST: "xmpp.example.com"
      # --- 管理员 JID ---
      TIGASE_ADMIN: "admin@xmpp.example.com"

启动：

docker compose up -d
# 拉取镜像（实测镜像大小约 250MB）
# 启动容器
docker compose ps
# NAME         STATUS         PORTS
# tigase-8.4.3 Up 2 minutes   0.0.0.0:5222->5222/tcp, 0.0.0.0:5269->5269/tcp, 0.0.0.0:8080->8080/tcp

查看日志（等待 "Server finished starting up"）：

docker logs -f tigase-8.4.3 2>&1 | grep -E 'starting up|ERROR|WARN'
# [INFO] XMPPServer.start() : Server finished starting up in (9s) and ... ready to use
# Ctrl+C 退出

4.3 方案二：Tigase + PostgreSQL（生产推荐）

Derby 是嵌入式单进程数据库，不支持多实例、不支持外部管理。生产必须切 PostgreSQL。

创建两服务 Compose：

services:
  tigase:
    image: tigase/tigase-xmpp-server:latest
    container_name: tigase-8.4.3
    restart: unless-stopped
    user: "1000:1000"
    hostname: xmpp.example.com
    depends_on:
      - postgres
    ports:
      - "5222:5222"
      - "5269:5269"
      - "8080:8080"
    volumes:
      - ./data:/home/tigase/tigase-server/data
      - ./logs:/home/tigase/tigase-server/logs
      - ./config:/home/tigase/tigase-server/etc
    environment:
      PRODUCTION_HEAP_SETTINGS: "-Xms256m -Xmx512m"
      JAVA_XSS: "-Xss228k"
      JAVA_METASPACE: "-XX:MaxMetaspaceSize=160m"
      HTTP_API_KEY_BOOTSTRAP: "changeme-production-key-01"
      TIGASE_DEFAULT_VHOST: "xmpp.example.com"
      TIGASE_ADMIN: "admin@xmpp.example.com"

  postgres:
    image: postgres:16
    container_name: tigase-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: tigasedb
      POSTGRES_USER: tigase
      POSTGRES_PASSWORD: "q1w2e3r4"
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  pgdata:

启动：

docker compose up -d
# 等 PostgreSQL ready
docker compose logs -f postgres 2>&1 | grep 'database system is ready'
# ... database system is ready to accept connections

首次初始化 schema：

# 进入 Tigase 容器导入 schema（发行包自带 scripts/db-create.sh）
docker exec -i tigase-8.4.3 bash -c 'cd /home/tigase/tigase-server && bash scripts/db-create.sh --help' 2>&1 | head -20
# 或手动从发行包 database/ 目录导入
docker exec -i tigase-postgres psql -U tigase -d tigasedb \
  -f /home/tigase/tigase-server/database/postgresql-server-8.4.1.sql 2>&1 | tail -5
# （schema 文件在镜像内路径一致）

五、数据持久化说明

路径（容器内）	内容	宿主机挂载
`/home/tigase/tigase-server/data/`	VHost / 用户 / PubSub / MUC 数据	`./data`
`/home/tigase/tigase-server/tigasedb/`	Derby 数据库文件	`./data/derby`
`/home/tigase/tigase-server/logs/`	运行日志（tigase-console.log）	`./logs`
`/home/tigase/tigase-server/etc/`	config.tdsl / tigase.conf / logback.xml	`./config`
PostgreSQL（生产）	完整数据库	named volume `pgdata`

⚠️ 删除卷会导致数据丢失，升级前务必 docker compose down + 备份 ./data 与 pgdata。

六、环境变量表

Tigase 官方镜像支持的主要环境变量：

变量	默认	说明
`PRODUCTION_HEAP_SETTINGS`	`-XX:MaxRAMPercentage=80`	JVM 堆参数，必须改为 `-Xms256m -Xmx512m`
`JAVA_XSS`	`-Xss228k`	线程栈大小
`JAVA_METASPACE`	`-XX:MaxMetaspaceSize=160m`	Metaspace 上限
`HTTP_API_KEY_BOOTSTRAP`	空	REST API 认证 key（启动时读取）
`TIGASE_DEFAULT_VHOST`	`xmpp.example.com`	默认虚拟主机
`TIGASE_ADMIN`	空	admin JID（setup wizard 需）
`DOCKER_HOST_IP`	`0.0.0.0`	监听地址
`DB_HOST`	空	外部 DB 主机（与 `scripts/wait-for-it.sh` 配合）
`DB_PORT`	空	外部 DB 端口
`JAVA_HOME`	自动探测	可不设

七、JVM 堆内存专项

与 B1 安装指南同一硬性规范：堆限 256–512MB。Compose 场景下 PRODUCTION_HEAP_SETTINGS 通过 environment 注入，镜像 entrypoint 会 source etc/tigase.conf 并替换默认的 MaxRAMPercentage。

实测验证：

docker exec tigase-8.4.3 bash -c "ps -ef | grep [j]ava | grep -o '\-Xms\S* -Xmx\S*'"
# -Xms256m -Xmx512m

⚠️ 镜像 entrypoint 如果没 source tigase.conf，JVM 参数可能还是默认的 -XX:MaxRAMPercentage=80。如果验证失败，用 command: 覆盖 entrypoint 直接指定 JAVA_OPTS：
tigase:
  command: >
    /bin/bash -c '
      export PRODUCTION_HEAP_SETTINGS="-Xms256m -Xmx512m";
      /home/tigase/tigase-server/scripts/tigase.sh start etc/tigase.conf
    '

八、常用运维命令

# 启动/停止/重启
docker compose up -d
docker compose down
docker compose restart tigase

# 实时日志
docker logs -f tigase-8.4.3 --tail 200

# 进容器
docker exec -it tigase-8.4.3 bash
# 容器内路径：/home/tigase/tigase-server
# 常用脚本：scripts/tigase.sh {check|status|restart|clear} etc/tigase.conf

# 验证端口
docker compose ps
ss -tlnp | grep -E '5222|5269|8080'

# 清理（删除数据！）
docker compose down -v
# 仅删容器保留数据
docker compose down

九、常见问题

9.1 容器启动后秒退

Error: Could not find or load main class tigase.server.XMPPServer

原因：镜像 JAR 文件丢失或 user 权限不对。检查：

docker exec tigase-8.4.3 ls /home/tigase/tigase-server/jars/tigase-server*.jar

如果不存在，可能是自定义镜像构建问题。拉最新镜像重试 docker compose pull。

9.2 Derby 锁文件残留

与 B1 文档 §9.1 相同，进容器清理：

docker exec tigase-8.4.3 bash -c 'rm -f /home/tigase/tigase-server/tigasedb/*.lck'
docker restart tigase-8.4.3

9.3 HTTP Admin 登不进去

检查 ./config/config.tdsl 中 admins 字段是否包含当前 VHost。Setup Wizard 在容器第一次启动时触发，确保 HTTP 8080 端口可访问。

9.4 数据目录权限

compose 中 user: "1000:1000" 对应 Tigase 镜像内的 tigase 用户 UID。如果不设 user 或设错，Docker 会以 root 运行，容器内 Java 进程写 data/ / logs/ 会报权限错。宿主机侧目录需提前授权：

mkdir -p ./data ./logs ./config
chown -R 1000:1000 ./data ./logs ./config

十、参考链接

Docker Hub：https://hub.docker.com/r/tigase/tigase-xmpp-server
Tigase 官方 Docker 文档：https://docs.tigase.org/tigase-server/8.4.0/Administration_Guide/Installation/Docker_Installation.html
PostgreSQL 官方镜像：https://hub.docker.com/_/postgres
Docker Compose 官方手册：https://docs.docker.com/compose/

Tigase Docker Compose 部署指南