Tigase 8.4.3 配置参数详解

Tigase 8.4.3 配置全解:Groovy DSL config.tdsl 结构 + 15 大类参数详解(dataSource/http/vhost/muc/pubsub/message-archive/sess-man/JVM)+ 生产模板 + 常见 FAQ,基于启动后 dump.properties 快照与 JVM 堆 256–512MB 约束。

TigaseTigaseJabberRESTXEPMUCPubSub即时通讯2026/10/27

Tigase 8.4.3 配置参数详解

目标:系统梳理 Tigase 8.4.3 的三类配置面——Groovy DSL 配置文件 etc/config.tdsl(核心配置)、JVM 启动参数 etc/tigase.conf(Java 进程层)、子模块配置文件(logback.xml、jmx.access/password、snmp.acl、tigase-http-context.xml),给出每类参数的含义、默认值、修改建议与生效方式。本文在 Ubuntu 22.04 / systemd / PostgreSQL / JVM 256–512MB 环境实测,配置来源同时覆盖发行包模板与启动后生成的 etc/config-dump.properties(平铺 Bean 属性全量快照)。

一、环境信息

项目值
配置文件(核心)etc/config.tdsl(Groovy DSL)
配置文件(JVM)etc/tigase.conf
启动后快照etc/config-dump.properties(每次启动自动 dump)
日志配置etc/logback.xml
JMX 配置etc/jmx.access / etc/jmx.password
HTTP 上下文etc/tigase-http-context.xml
证书目录certs/
Schema 脚本database/<db>-<component>-<version>.sql
运行用户tigase
生效方式修改 config.tdsl 后 systemctl restart tigase-server;tigase.conf 同上;部分模块支持运行时热加载

二、前置条件

  1. Tigase 8.4.3 已安装并跑通(参考 B1 / B2 文档)。
  2. 具备对配置文件的读写权限(运行用户 tigase)。
  3. 了解 Groovy DSL 基本语法(config.tdsl 里大括号块 = Bean 类)。
  4. 明确修改后果:所有配置修改需要重启服务,Tigase 没有全量热重载机制(Groovy admin 脚本可运行时改部分)。

三、参数查看与修改方式

3.1 三层配置模型

层文件内容粒度
顶层 JVMetc/tigase.confJVM 堆/GC/编码/Debug/远程调试进程级,全部生效前重启
中间 Tigase Coreetc/config.tdslBean 定义(VHost 管理、dataSource、HTTP 组件、MUC、PubSub 等)组件级,重启生效
子模块独立文件etc/logback.xml、etc/jmx.*、etc/snmp.acl、etc/tigase-http-context.xml日志、监控、HTTP 上下文子系统级,各自热加载或重启

3.2 启动后 dump 快照(强烈推荐先看)

每次启动 Tigase 会在 etc/config-dump.properties 自动生成平铺 Bean 属性的全量快照(按 Bean class + default 块组织)。修改 config.tdsl 前先 grep dump 里的目标 Bean 名,能看到 Bean 的全部可配属性 + 当前生效值:

# 查 dataSource 配置
grep -A 20 'dataSource' /home/tigase/tigase-server/etc/config-dump.properties | head -30
# dataSource (class: tigase.db.DataSource,
#     default (class: tigase.db.DataSource) {
#         uri = 'jdbc:derby:tigasedb;create=true'
#         # ...
#     }
# )

# 查 admins / scripts-dir
grep -E 'admins|scripts-dir' /home/tigase/tigase-server/etc/config-dump.properties | head -10
# admins = [ 'admin@xmpp.example.com' ]
# 'scripts-dir' = 'scripts/admin'

3.3 常见操作命令

# 编辑
vim etc/config.tdsl
# 验证 DSL 语法(配置管理器)
bash scripts/tigase.sh check etc/tigase.conf
# 重启生效
systemctl restart tigase-server
# 查看状态
systemctl status tigase-server
# 查看完整 dump(方便 grep)
cat etc/config-dump.properties | less

3.4 config.tdsl Groovy DSL 语法速查

// 标量
'config-type' = 'default'
PRODUCTION_HEAP_SETTINGS = ' -Xms256m -Xmx512m '

// 列表
admins = [ 'admin@xmpp.example.com', 'ops@xmpp.example.com' ]

// 块 = Bean(类定义在 Tigase jar 内部)
dataSource () {
    default () {
        uri = 'jdbc:postgresql://127.0.0.1:5432/tigasedb'
        user = 'tigase'
        password = 'q1w2e3r4'
    }
}

// 嵌套
http () {
    rest () {
        open_access = true
    }
    'admin-console' () {
        'admin-user' = 'admin'
        'admin-password' = 'q1w2e3r4'
    }
}

// 注释
// 单行注释
/* 块注释 */

四、参数总览

按 Bean / 功能域分类,覆盖常见配置项:

类别Bean 名核心配置点生效影响
通用基础—admins、default-virtual-host、config-type启动时加载
dataSourcedataSourceuri / user / password存储后端
httphttprest/open_access、admin-consoleAdmin Console / REST API
vhostsvhost默认 VHost、max-users-per-vhost多租户
sess-manSessionManager会话超时、离线消息上限C2S 入口行为
s2sS2SConnectionManager联邦白黑名单、连接超时S2S 互联
mucMUCComponent默认房间配置、持久化路径MUC 聊天室
pubsubPubSubComponent默认节点配置、存储后端PubSub
message-archiveMessageArchiveComponentMAM 存储、TTS消息归档
monitorMonitorComponent健康检查端口、指标导出监控
eventbusEventBusComponent事件订阅内部事件
JVMetc/tigase.confPRODUCTION_HEAP_SETTINGS / JAVA_XSS / GC进程层
TLScerts/ + tigase.conf 加 TLS_DEBUG证书加载加密
logbacklogback.xmlappender、level、file日志
JMX / SNMPjmx.* / snmp.acl远程监控访问监控

五、核心参数分类详解

5.1 通用基础参数(config.tdsl 顶层)

参数默认含义生产建议
adminssetup wizard 生成管理员 JID 列表数组,如 ['admin@xmpp.example.com']
'config-type''default'配置类型,setup wizard 会写入 'default' 或 'setup'保持 default
'default-virtual-host'空默认 VHost必须设,所有不显式指定域名的请求走这里
'scripts-dir'scripts/adminGroovy Ad-Hoc 脚本目录保持默认
'max-connections'未显式全局连接数上限大机器可调高
'allow-registration'未显式是否允许 JIQ Register 注册生产关,开发可开

示例修改——显式设默认 VHost + 多管理员:

admins = [ 'admin@xmpp.example.com', 'ops@xmpp.example.com' ]
'config-type' = 'default'
'default-virtual-host' = 'xmpp.example.com'
'allow-registration' = false

5.2 dataSource 数据源

决定用户、VHost、PubSub、MUC、消息归档的数据后端。多后端并存时按组件分别定义(如 muc () { ... } 下再嵌套 dataSource)。

dataSource () {
    default () {
        // Derby(默认嵌入式)
        // uri = 'jdbc:derby:tigasedb;create=true'

        // PostgreSQL(生产首选)
        uri = 'jdbc:postgresql://127.0.0.1:5432/tigasedb'
        user = 'tigase'
        password = 'q1w2e3r4'

        // MySQL 格式类似
        // uri = 'jdbc:mysql://127.0.0.1:3306/tigasedb?useSSL=false'
        // user = 'tigase'
        // password = 'q1w2e3r4'

        // SQL Server
        // uri = 'jdbc:sqlserver://127.0.0.1:1433;databaseName=tigasedb'

        // 连接池参数(可选,Tigase 自动用 HikariCP)
        // pool-size = 10
        // min-idle = 2
        // max-idle = 8
    }
}

修改生效:systemctl restart tigase-server。首次切换需先导入新后端的 schema 脚本(database/postgresql-*.sql)。

5.3 http(Admin Console + REST API + HTTP 组件)

http () {
    'admin-console' () {
        'admin-user' = 'admin'
        'admin-password' = 'q1w2e3r4'
        // 监听端口
        'admin-port' = 8080
    }
    rest () {
        // 打开 REST API 匿名访问(生产不要,改用 Api-Key)
        open_access = true
        // Api-Key 白名单逗号分隔
        // api_keys = 'key1,key2'
    }
    'file-upload' () {
        // 上传目录
        'upload-dir' = 'data/upload'
        'max-file-size' = 67108864  // 64MB
    }
}
参数默认含义生产建议
http.rest.open_accessfalseREST API 是否允许无认证访问生产必须 false,用 Api-Key
http.admin-console.admin-usersetup wizard 写入Admin Console 用户名(Basic Auth user)与 admins JID 对应
http.admin-console.admin-passwordsetup wizard 写入Admin Console 密码生产改掉默认 tigase
http.admin-console.admin-port8080Admin / REST 监听端口防火墙放行

5.4 s2s(服务器互联联邦)

默认允许与所有服务器互联。生产建议加白名单降低 spam 风险:

s2s () {
    // 允许互联的 VHost 列表,不设即全部允许
    // 'allow-list' = [ 'gmail.com', 'jabber.org' ]
    // 'deny-list' = [ 'spam.example.com' ]
    // 连接超时(秒)
    'connect-timeout' = 30
    // DNS 超时(秒)
    'dns-timeout' = 10
}

5.5 muc(多用户会议)

muc () {
    'default-room-config' () {
        // 是否允许匿名进入房间
        'allow-anonymous' = false
        // 是否允许非管理员创建持久房间
        'allow-persistent' = false
        // 房间最大人数
        'max-users' = 500
        // 默认主题
        subject = 'Welcome to MUC Room'
    }
    // 存储(默认走 dataSource.default)
    // 如果要独立数据库:
    // dataSource () { default () { uri = '...' } }
}

5.6 pubsub(发布订阅)

pubsub () {
    'default-node-config' () {
        // 默认节点类型:leaf(终端)/ collection(集合)
        'node-type' = 'leaf'
        // 最大持久化项数
        'max-publish-items' = 1000
        // 是否允许订阅者拉取历史
        'persist-items' = true
    }
}

5.7 message-archive(消息归档 XEP-0313 MAM)

'message-archive' () {
    // 归档保留时间(天)
    'retention-days' = 90
    // 最大归档条数(单用户单对话)
    'max-entries' = 100000
    // 存储后端(默认走 dataSource.default)
    // 需要独立表:database/message-archiving-*.sql 单独导入
}

5.8 sess-man(会话管理器 C2S 入口)

'sess-man' () {
    // 空闲超时(秒)
    'idle-timeout' = 1800
    // 离线消息上限(条)
    'offline-queue-limit' = 100
    // 单个用户最大连接数
    'max-user-connections' = 10
}

5.9 monitor(监控组件)

monitor () {
    // 监控端口(HTTP 状态接口)
    port = 9050
    // 输出格式:json / text
    format = 'json'
}

5.10 vhost(虚拟主机)

默认 VHost 在顶层 'default-virtual-host'。运行时增删 VHost 走 Groovy Ad-Hoc 命令 CreateNode / DeleteNode / VHostAdmin REST。

vhosts () {
    'xmpp.example.com' () {
        // 单 VHost 用户数上限
        'max-users' = 10000
        // 是否允许该 VHost 注册
        'allow-registration' = false
        // 独立管理员
        admins = [ 'admin@xmpp.example.com' ]
    }
    'chat.example.com' () {
        'max-users' = 5000
    }
}

5.11 JVM 层参数(etc/tigase.conf)

本节来自 writing-rules.md §4 硬性规范——所有 Java 组件必须单独说明堆限与修改位置。

# ===== 编码 =====
ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"

# ===== GC(默认注释掉,表示用 JVM 默认) =====
# GC="-XX:+UseBiasedLocking -XX:+UseConcMarkSweepGC ..."

# ===== 堆内存(硬性规范必须改到 256–512MB) =====
# 发行包默认注释后为动态 MaxRAMPercentage=80,生产吞噬宿主
PRODUCTION_HEAP_SETTINGS=" -Xms256m -Xmx512m "

# ===== 线程栈 =====
JAVA_XSS=" -Xss228k "

# ===== Metaspace =====
JAVA_METASPACE=" -XX:MaxMetaspaceSize=160m "

# ===== 远程调试(生产关) =====
# REMOTE_DEBUG=" -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n "

# ===== GC Debug =====
# GC_DEBUG=" -XX:+PrintGCDetails ... -Xloggc:logs/jvm.log "

# ===== 生产 OOM 行为 =====
# JVM_DEBUG=" -XX:+HeapDumpOnOutOfMemoryError -XX:CrashOnOutOfMemoryError "

# ===== TLS Debug =====
# TLS_DEBUG=" -Djavax.net.debug=ssl:handshake "

# ===== NMT(NativeMemoryTracking)=====
# JVM_MEMORY=" -XX:+UnlockDiagnosticVMOptions -XX:NativeMemoryTracking=summary "

# ===== API Key(环境变量注入,Config Holder 读取)=====
HTTP_API_KEY_BOOTSTRAP="tigase-api-key-demo"

# ===== 组合注入(不要改这行,前面变量覆盖它)=====
JAVA_OPTIONS="${GC} ${GC_DEBUG} ${REMOTE_DEBUG} ${TLS_DEBUG} ${JVM_MEMORY} ... -server ${PRODUCTION_HEAP_SETTINGS} ${JAVA_XSS} ${JAVA_METASPACE} ${ENC}"

常见修改:

变量改法验证
堆大小PRODUCTION_HEAP_SETTINGS=" -Xms256m -Xmx512m "ps -ef | grep java 里看到 -Xms256m -Xmx512m
线程栈JAVA_XSS=" -Xss228k "同上
开启 GC 日志取消 GC_DEBUG 注释ls logs/jvm.log
开启远程调试取消 REMOTE_DEBUG 注释生产必须关掉
生产 API 密钥HTTP_API_KEY_BOOTSTRAP="strong-key"Rest 端点返回 403/401 说明 API-Key 链路生效

5.12 TLS 证书(certs/ 目录)

发行包预带三套证书:

目录内容用途
certs/rsa-keystoreJava KeyStore 格式服务端证书
certs/truststoreJava TrustStore信任链
certs/keystore-letsencryptLet's Encrypt 格式生产建议替换

生产建议把 Let's Encrypt 签好的 fullchain + privkey 用 keytool 转成 Java KeyStore 放到 certs/,然后取消 TLS_DEBUG 注释验证握手。

5.13 logback.xml(日志)

配置标准 SLF4J / Logback,示例改 INFO → DEBUG 排 REST API 问题:

<!-- etc/logback.xml -->
<logger name="tigase.http" level="DEBUG"/>
<logger name="tigase.rest" level="DEBUG"/>

默认 appender 输出到 logs/tigase-console.log,滚动策略是按时间轮转。

5.14 JMX 远程监控

etc/jmx.access 配置允许访问的角色,etc/jmx.password 存密码(明文!生产必须 600 权限):

chmod 600 /home/tigase/tigase-server/etc/jmx.password
# 启用远程 JVM 参数(etc/tigase.conf 取消注释)
JMX_REMOTE_IP="-Djava.rmi.server.hostname=0.0.0.0"
REMOTE_DEBUG=" -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n "
# 8000 端口防火墙放行(仅内网)

5.15 HTTP Context(tigase-http-context.xml)

内嵌 Jetty 的上下文配置,默认只是一个空的 ServletContextHandler:

<Configure class="org.eclipse.jetty.servlet.ServletContextHandler"/>

一般不需要改,REST handler 和 Admin Console 都由 Groovy 动态注册。

六、生产配置模板(4C/8G / PostgreSQL / 单机)

# etc/config.tdsl —— 生产版

admins = [ 'admin@xmpp.example.com' ]
'config-type' = 'default'
'default-virtual-host' = 'xmpp.example.com'
'allow-registration' = false

dataSource () {
    default () {
        uri = 'jdbc:postgresql://127.0.0.1:5432/tigasedb'
        user = 'tigase'
        password = 'q1w2e3r4'
        pool-size = 16
        min-idle = 4
    }
}

http () {
    'admin-console' () {
        'admin-user' = 'admin'
        'admin-password' = 'q1w2e3r4'
        'admin-port' = 8080
    }
    rest () {
        open_access = false
        api_keys = 'changeme-strong-key-01'
    }
    'file-upload' () {
        'upload-dir' = 'data/upload'
        'max-file-size' = 67108864
    }
}

s2s () {
    'connect-timeout' = 30
    'dns-timeout' = 10
    // 白名单模式:
    // 'allow-list' = [ 'gmail.com', 'jabber.org' ]
}

'sess-man' () {
    'idle-timeout' = 1800
    'offline-queue-limit' = 100
    'max-user-connections' = 10
}

muc () {
    'default-room-config' () {
        'allow-anonymous' = false
        'allow-persistent' = false
        'max-users' = 500
    }
}

pubsub () {
    'default-node-config' () {
        'max-publish-items' = 10000
        'persist-items' = true
    }
}

'message-archive' () {
    'retention-days' = 90
    'max-entries' = 100000
}

monitor () {
    port = 9050
    format = 'json'
}

配套 etc/tigase.conf(生产版关键几行):

PRODUCTION_HEAP_SETTINGS=" -Xms256m -Xmx512m "
JAVA_XSS=" -Xss228k "
JAVA_METASPACE=" -XX:MaxMetaspaceSize=160m "
HTTP_API_KEY_BOOTSTRAP="changeme-strong-key-01"
# REMOTE_DEBUG 注释掉
# GC_DEBUG 注释掉
# TLS_DEBUG 注释掉
# JVM_MEMORY 注释掉(NMT 有 5–10% 开销)

七、常见问题

7.1 修改 config.tdsl 后没生效

必须重启:systemctl restart tigase-server。Tigase 没有全量热 reload 机制,Groovy admin 脚本(UpdateConfig.groovy)能运行时改部分但仅限少数字段。

7.2 改完启动报错 DSLBeanConfigurator 解析失败

Groovy DSL 语法问题。常见坑:

  • 单引号 vs 双引号混用:Groovy 都可以,但属性名里带 - 必须单引号,如 'allow-registration'
  • 块缩进乱不影响(Groovy DSL 宽松)
  • 拼写错 Bean 名:如 'allow-registration' 写成 allow-registration(Bean 找不到)

7.3 修改 admins 后旧的 admin 登不进去

admins 是运行时加载的,重启后生效。旧 JID 如果 VHost 不一致也会失败(admins 里的 JID 必须含完整 VHost)。

7.4 修改 dataSource 后启动报数据库错

检查:

  1. 新后端的 schema 脚本是否全部导入(server + common + 组件脚本)
  2. 连接串 URI 格式(PostgreSQL 用 //host:port/dbname,Derby 用冒号分隔)
  3. 用户名密码、TCP 端口、防火墙
  4. Derby 锁文件(9.1)

7.5 堆内存没改过来

JVM 参数实际值由 etc/tigase.conf → JAVA_OPTIONS → tigase.sh → 最终 java 命令。排查链:

# 1. 看 config 里是否设了
grep PRODUCTION_HEAP_SETTINGS etc/tigase.conf
# 2. 看实际生效
ps -p $(cat logs/tigase.pid) -o args= | grep -o '\-Xms\S* -Xmx\S*'
# 3. 如果 2. 里是 -XX:MaxRAMPercentage=80,说明 PRODUCTION_HEAP_SETTINGS 被注释或没被 source

7.6 config-dump.properties 找不到某些参数

Bean 还没初始化或者该参数是隐含默认。看 dump 的完整值,而不是 grep 某一行。Bean 类名一般是完全限定 Java 类名(如 tigase.server.xmppsession.SessionManager)。

八、参考链接