Openfire 5.1.2 配置参数详解

目标：梳理 Openfire 5.1.2 的两层配置体系（openfire.xml 引导层与数据库 System Properties 运行层），基于 Ubuntu 24.04 实测环境逐组盘点关键配置参数的真实键值、修改方式与生效机制。

一、环境信息

本文所有配置项与回显在以下环境实测采集：

项目	内容
操作系统	Ubuntu 24.04.5 LTS
Openfire 版本	5.1.2（deb 包安装，systemd 管理）
数据源	内嵌数据库（EmbeddedConnectionProvider）
演示域名 / 账号	im.example.com；admin / q1w2e3r4
属性采集口径	管理台 System Properties 页全量导出，共 267 项

配置体系背景见《Openfire 5.1.2 介绍与选型指南》，安装过程见《Ubuntu 24.04 安装 Openfire 5.1.2 指南》、《Openfire 5.1.2 Docker Compose 部署指南》。

二、配置体系总览

Openfire 5.1.2 的配置分两层，官方在 openfire.xml 的文件头注释中明确了这一设计：

This file stores bootstrap properties needed by Openfire.
...
Most properties are stored in the Openfire database. A
property viewer and editor is included in the admin console.

层	载体	管理方式	典型内容
引导层	/etc/openfire/openfire.xml（deb 安装）	文本编辑，重启读取	管理台端口、数据源连接、setup 标记、域名
运行层	数据库 ofProperty 表	管理台 System Properties 页在线维护	267 项系统属性（auth、session、httpbind、provider 等）
JVM 层	/etc/default/openfire（deb 安装）	文本编辑，重启生效	DAEMON_OPTS（堆大小等）

deb 安装的关键路径：/etc/openfire/openfire.xml、/etc/default/openfire、/etc/openfire/log4j2.xml；程序目录 /usr/share/openfire；日志 /var/log/openfire/openfire.log。

三、引导层：openfire.xml 逐项详解

初始化向导完成后，deb 环境的 /etc/openfire/openfire.xml 实测原文（节选保留全部有效节点）：

<jive>
  <adminConsole>
    <!-- Disable either port by setting the value to -1 -->
    <port>9090</port>
    <securePort>9091</securePort>
  </adminConsole>
  <locale>en</locale>
  <clustering>
    <nodeid>5048e1f5-cc46-478b-b073-3e1b0e66c1c5</nodeid>
  </clustering>
  <connectionProvider>
    <className>org.jivesoftware.database.EmbeddedConnectionProvider</className>
  </connectionProvider>
  <setup>true</setup>
  <fqdn>im.example.com</fqdn>
</jive>

逐项说明：

节点	实测值	说明
adminConsole/port	9090	管理台 HTTP 端口，设 -1 禁用
adminConsole/securePort	9091	管理台 HTTPS 端口，设 -1 禁用
locale	en	界面语言（向导第一步写入，zh_CN 为中文）
clustering/nodeid	5048e1f5-…	集群节点随机 ID，单机也生成
connectionProvider/className	…EmbeddedConnectionProvider	数据源实现；切换外部库后此节点变为 DefaultConnectionProvider 加 JDBC 参数
setup	true	向导完成标记；改为 false 会重新触发初始化向导
fqdn	im.example.com	服务器对外完整域名

network（绑定网卡）与 oneTimeAccessToken（管理台一次性访问令牌）默认注释，需要时按注释模板手工添加并重启。

四、JVM 层：/etc/default/openfire

deb 安装的服务单元通过该文件注入 JVM 参数，实测内容：

cat /etc/default/openfire

# If you wish to override the auto-detected JAVA_HOME variable, uncomment
# and change the following line.
#JAVA_HOME=/usr/java/default

# Additional options that are passed to the Daemon.
DAEMON_OPTS="-Xms256m -Xmx512m"

修改后重启并验证生效（实测链路）：

systemctl restart openfire
sudo -u openfire jps -lvm | head -1

4407 /usr/share/openfire/lib/startup.jar -Xms256m -Xmx512m -Dlog4j.configurationFile=/usr/share/openfire/lib/log4j2.xml …

生产建议堆上限 512MB–2GB；本文环境按 256–512MB 限额实测。日志级别调整编辑 /etc/openfire/log4j2.xml（log4j2 语法），改后 systemctl restart openfire 生效。

五、运行层：System Properties 参数详解

管理台路径：Server → Server Manager → System Properties，在线查看与修改，数据持久化于数据库（重启不丢失）。以下键值全部来自 5.1.2 实测导出（共 267 项，本文按组收录关键项）。

5.1 管理台安全（adminConsole.*）

键	实测默认值	说明
adminConsole.access.ip-allowlist / ip-blocklist	none	管理台来源 IP 白/黑名单
adminConsole.maxAttemptsPerIP	40	每 IP 登录失败上限（防爆破）
adminConsole.maxAttemptsPerUsername	10	每用户名登录失败上限
adminConsole.perIPAttemptResetInterval	900000 (15 minutes)	计数重置周期
adminConsole.sessionTimeout	1800 (30 minutes)	管理台会话超时
adminConsole.CSP.enabled / responsevalue	true / default-src 'self'; …	内容安全策略
adminConsole.forwarded.enabled	false	反向代理信任（Forwarded 头解析）；置于代理后时开启，并配 trusted.proxies
adminConsole.stop-timeout	5000 (5 seconds)	停机等待

5.2 协议与会话（xmpp.*）

键	实测默认值	说明
xmpp.auth.anonymous	false	匿名登录开关
xmpp.auth.ignorecase	true	用户名大小写不敏感
xmpp.client.idle	360000 (6 minutes)	客户端空闲断开阈值
xmpp.client.idle.ping	true	空闲前主动 ping 保活
xmpp.client.preauth.timeout	300000 (5 minutes)	认证前超时
xmpp.client.csi.enabled / delay.max-duration	true / 600000 (10 minutes)	客户端状态指示（CSI）延迟投递
xmpp.command.limit / timeout	100 / 600000 (10 minutes)	Ad-hoc 命令限制
xmpp.ssl.* 相关组（未展开处以管理台实况为准）	—	TLS 上下文与信任策略

5.3 HTTP Binding（httpbind.*）

键	实测默认值	说明
httpbind.enabled	true	BOSH/WebSocket 服务开关
httpbind.port.plain / secure	7070 / 7443	监听端口
httpbind.client.processing.threads	200	处理线程数
httpbind.CORS.enabled / domains	true / *	跨域配置（生产应收紧 domains）
httpbind.forwarded.enabled	false	代理后真实 IP 解析

5.4 Provider 体系（provider.*）

实测默认全部为内置实现：

provider.admin.className   = org.jivesoftware.openfire.admin.DefaultAdminProvider
provider.auth.className    = org.jivesoftware.openfire.auth.DefaultAuthProvider
provider.group.className   = org.jivesoftware.openfire.group.DefaultGroupProvider
provider.lockout.className = org.jivesoftware.openfire.lockout.DefaultLockOutProvider
provider.user.className    = org.jivesoftware.openfire.user.DefaultUserProvider
provider.vcard.className   = org.jivesoftware.openfire.vcard.DefaultVCardProvider

对接 LDAP/外部库时替换对应 className（如 LdapUserProvider、LdapAuthProvider），由管理台向导辅助完成。

5.5 密码与其他

键	实测值	说明
passwordKey	hidden	属性值在页面隐藏显示（加密类属性标记）
update.service-enabled / frequency	true / 48 (2 days)	版本更新检查
update.notify-admins	true	更新时通知管理员

六、配置修改的生效与持久化

实测结论：

管理台修改（运行层）：System Properties 页保存后写入数据库并即时生效（个别监听类属性需重启，页面有提示）；持久化于内嵌库 ofProperty 表。实测验证：向导写入的域名 im.example.com 在本文环境经历多次 systemctl restart openfire 后保持不变。
文件层修改（openfire.xml / /etc/default/openfire）：编辑后必须 systemctl restart openfire；上述 DAEMON_OPTS 修改 + 重启 + jps 核对即为实测链路。
优先级：引导层只负责启动引导与数据源，运行属性以数据库为准；两者同名键时数据库值覆盖运行期行为。

七、常见问题

1. 修改 openfire.xml 后不生效 引导层仅启动时读取，需重启；另外确认编辑的是生效路径（deb 为 /etc/openfire/openfire.xml，压缩包安装为 $OPENFIRE_HOME/conf/openfire.xml）。

2. 管理台改了属性但行为没变 部分监听类属性（端口、线程池）需要重启进程；System Properties 页对需重启项有标注。

3. 把 setup 改回 false 后管理台变成向导 <setup> 为向导完成标记，误改回 false 会让管理台重新进入初始化向导；向导会保留既有数据库数据，走完即可恢复。

4. 反向代理后取不到真实客户端 IP 开启 adminConsole.forwarded.enabled 与 httpbind.forwarded.enabled，并把代理地址写入对应 trusted.proxies。

八、参考

Openfire 官方文档：https://docs.igniterealtime.org/openfire/
站内：《Openfire 5.1.2 介绍与选型指南》、《Ubuntu 24.04 安装 Openfire 5.1.2 指南》、《Openfire 5.1.2 Docker Compose 部署指南》