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 约束。
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 同上;部分模块支持运行时热加载 |
二、前置条件
- Tigase 8.4.3 已安装并跑通(参考 B1 / B2 文档)。
- 具备对配置文件的读写权限(运行用户 tigase)。
- 了解 Groovy DSL 基本语法(config.tdsl 里大括号块 = Bean 类)。
- 明确修改后果:所有配置修改需要重启服务,Tigase 没有全量热重载机制(Groovy admin 脚本可运行时改部分)。
三、参数查看与修改方式
3.1 三层配置模型
| 层 | 文件 | 内容 | 粒度 |
|---|---|---|---|
| 顶层 JVM | etc/tigase.conf | JVM 堆/GC/编码/Debug/远程调试 | 进程级,全部生效前重启 |
| 中间 Tigase Core | etc/config.tdsl | Bean 定义(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 | 启动时加载 |
| dataSource | dataSource | uri / user / password | 存储后端 |
| http | http | rest/open_access、admin-console | Admin Console / REST API |
| vhosts | vhost | 默认 VHost、max-users-per-vhost | 多租户 |
| sess-man | SessionManager | 会话超时、离线消息上限 | C2S 入口行为 |
| s2s | S2SConnectionManager | 联邦白黑名单、连接超时 | S2S 互联 |
| muc | MUCComponent | 默认房间配置、持久化路径 | MUC 聊天室 |
| pubsub | PubSubComponent | 默认节点配置、存储后端 | PubSub |
| message-archive | MessageArchiveComponent | MAM 存储、TTS | 消息归档 |
| monitor | MonitorComponent | 健康检查端口、指标导出 | 监控 |
| eventbus | EventBusComponent | 事件订阅 | 内部事件 |
| JVM | etc/tigase.conf | PRODUCTION_HEAP_SETTINGS / JAVA_XSS / GC | 进程层 |
| TLS | certs/ + tigase.conf 加 TLS_DEBUG | 证书加载 | 加密 |
| logback | logback.xml | appender、level、file | 日志 |
| JMX / SNMP | jmx.* / snmp.acl | 远程监控访问 | 监控 |
五、核心参数分类详解
5.1 通用基础参数(config.tdsl 顶层)
| 参数 | 默认 | 含义 | 生产建议 |
|---|---|---|---|
admins | setup wizard 生成 | 管理员 JID 列表 | 数组,如 ['admin@xmpp.example.com'] |
'config-type' | 'default' | 配置类型,setup wizard 会写入 'default' 或 'setup' | 保持 default |
'default-virtual-host' | 空 | 默认 VHost | 必须设,所有不显式指定域名的请求走这里 |
'scripts-dir' | scripts/admin | Groovy 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_access | false | REST API 是否允许无认证访问 | 生产必须 false,用 Api-Key |
http.admin-console.admin-user | setup wizard 写入 | Admin Console 用户名(Basic Auth user) | 与 admins JID 对应 |
http.admin-console.admin-password | setup wizard 写入 | Admin Console 密码 | 生产改掉默认 tigase |
http.admin-console.admin-port | 8080 | Admin / 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-keystore | Java KeyStore 格式 | 服务端证书 |
| certs/truststore | Java TrustStore | 信任链 |
| certs/keystore-letsencrypt | Let'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 后启动报数据库错
检查:
- 新后端的 schema 脚本是否全部导入(server + common + 组件脚本)
- 连接串 URI 格式(PostgreSQL 用
//host:port/dbname,Derby 用冒号分隔) - 用户名密码、TCP 端口、防火墙
- 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)。
八、参考链接
- Tigase Admin Guide Configuration:https://docs.tigase.org/tigase-server/8.4.0/Administration_Guide/Configuration/
- Tigase Bean 配置参考:发行包 docs/javadoc/tigase/ 下对应 Bean 类
- PostgreSQL JDBC 驱动文档:https://jdbc.postgresql.org/documentation/
- Logback 手册:https://logback.qos.ch/manual/index.html
- Groovy DSL 介绍:发行包
scripts/admin/example_TigaseScriptingGuide.groovy