Openfire 5.1.2 API 使用详解

在 Openfire 5.1.2 上安装启用 REST API 插件 1.12.0 的实测指南，覆盖 Basic 认证配置、用户与会话端点实操、错误码归纳，以及管理台通配豁免导致 302 的排障实录。

OpenfireJabber/XMPP即时通讯2026/10/26

Openfire 5.1.2 API 使用详解

目标：在 Openfire 5.1.2 上安装并启用官方 REST API 插件，完成 Basic 认证配置，实测用户管理、会话与聊天室查询等核心端点，并给出一个 5.1.2 环境特有的管理台通配豁免排障实录。全部命令与回显均来自同一台 Ubuntu 24.04 实测服务器。

一、环境信息

项目内容
操作系统Ubuntu 24.04.5 LTS
Openfire 版本5.1.2（deb 包安装，已完成初始化向导）
REST API 插件restAPI 1.12.0（2025-07-04 发布，要求 Openfire 5.0.0+）
认证方式Basic HTTP Authentication（admin / q1w2e3r4）
API 基址http://im.example.com:9090/plugins/restapi/v1

安装与配置背景见《Ubuntu 24.04 安装 Openfire 5.1.2 指南》与《Openfire 5.1.2 配置参数详解》。

二、安装 REST API 插件

插件是 Openfire 的主要扩展机制（见《Openfire 5.1.2 介绍与选型指南》），REST API 插件提供基于 HTTP 的管理接口。两种安装方式等价：管理台 Plugins 页上传，或直接下载 jar 到插件目录后重启。本文采用后者：

cd /usr/share/openfire/plugins
curl -L -o restAPI.jar "https://www.igniterealtime.org/projects/openfire/plugins/1.12.0/restAPI.jar"
systemctl restart openfire

启动日志确认加载成功：

2026.10.26 10:58:11 INFO  [PluginMonitorExec-2]: org.jivesoftware.openfire.container.PluginManager - Successfully loaded plugin 'restapi-1.12.0'.

加载后插件目录展开为 restapi/（含 lib/ 依赖、web/ 管理页与预编译 JSP），管理台 Server → Server Settings 下出现 REST API 配置页。

三、启用与认证配置

配置页路径：http://<服务器>:9090/plugins/restapi/rest-api.jsp（注意 5.1.2 中插件配置页挂在 /plugins/<插件名>/ 前缀下）。表单字段与实测选择：

表单项可选值本文实测
enabledtrue / falsetrue
authtypebasic / secret / custombasic
secret文本（首次进入已自动生成随机值）保留默认
loggingEnabledtrue / falsetrue（排障期开启）

三种认证模式互斥，与插件 readme 的说明一致：

  • basic：请求头携带 Openfire 管理员账号的 HTTP Basic 凭据（Authorization: Basic <base64(user:password)>）；
  • secret：请求头直接携带共享密钥（Authorization: <secret>）；
  • custom：自定义过滤器类名（customAuthFilterClassName）。

保存后插件将配置持久化为系统属性（可在管理台 System Properties 看到）：plugin.restapi.enabled、plugin.restapi.httpAuth、plugin.restapi.secret、plugin.restapi.allowedIPs、plugin.restapi.serviceLoggingEnabled。

四、关键排障：一直被 302 重定向到登录页（5.1.2 实录）

启用后用 curl 测试却始终 302：

curl -s -D - -o /dev/null -u admin:q1w2e3r4 http://127.0.0.1:9090/plugins/restapi/v1/status

HTTP/1.1 302 Found
Location: /login.jsp?url=%2Fplugins%2Frestapi%2Fv1%2Fstatus

根因：管理台入口过滤器 AuthCheckFilter 会拦截一切无会话请求；REST API 插件初始化时调用 AuthCheckFilter.addExclude("restapi/*") 注册通配豁免，但 5.1.2 的通配匹配受系统属性 adminConsole.access.allow-wildcards-in-excludes 控制，默认关闭——豁免项 restapi/* 被当作字面字符串，无法匹配任何实际路径，于是请求全部落入登录重定向。

解决：在引导层 /etc/openfire/openfire.xml 的 <jive> 下加入该属性（与 adminConsole 端口配置并列）：

<jive>
  <adminConsole>
    <access>
      <allow-wildcards-in-excludes>true</allow-wildcards-in-excludes>
    </access>
    <port>9090</port>
    <securePort>9091</securePort>
  </adminConsole>
  ...
</jive>

重启后验证（无凭据 401、带凭据 200）：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9090/plugins/restapi/v1/users

401

curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://127.0.0.1:9090/plugins/restapi/v1/users

200

排障定位过程：带管理台会话访问 API 返回 401（说明插件认证过滤器已生效），无会话返回 302（说明被更外层的管理台过滤器拦截）；反汇编 xmppserver-5.1.2.jar 中 AuthCheckFilter 可见通配开关逻辑与上述属性名。此属性同样影响其他以通配方式注册豁免的插件。

五、API 实测

以下均以 basic 模式演示。端点清单以插件自带的 readme.html（restapi/ 目录内）为准，本文实测其中核心部分。

5.1 查询用户列表

curl -s -u admin:q1w2e3r4 http://127.0.0.1:9090/plugins/restapi/v1/users

实测回显（默认 XML）：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><users><user><username>admin</username><name>Administrator</name><email>admin@example.com</email><properties/></user></users>

Accept: application/json 请求 JSON 输出：

curl -s -u admin:q1w2e3r4 -H "Accept: application/json" \
  http://127.0.0.1:9090/plugins/restapi/v1/users

{"users":[{"username":"admin","name":"Administrator","email":"admin@example.com","properties":[]},{"username":"alice","name":"Alice Demo","properties":[]}]}

5.2 创建用户

curl -s -w "\nHTTP:%{http_code}\n" -u admin:q1w2e3r4 -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"a1b2c3d4","name":"Alice Demo"}' \
  http://127.0.0.1:9090/plugins/restapi/v1/users

实测回显：

HTTP:201

重复创建同名用户返回冲突：

HTTP:409

5.3 查询单个用户

curl -s -u admin:q1w2e3r4 http://127.0.0.1:9090/plugins/restapi/v1/users/alice

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><user><username>alice</username><name>Alice Demo</name><properties/></user>

5.4 会话与聊天室查询

curl -s -u admin:q1w2e3r4 http://127.0.0.1:9090/plugins/restapi/v1/sessions

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><sessions/>

curl -s -u admin:q1w2e3r4 http://127.0.0.1:9090/plugins/restapi/v1/chatrooms

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><chatRooms/>

空环境（无在线会话、无聊天室）时返回空集合，HTTP 200。

5.5 认证失败行为

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9090/plugins/restapi/v1/users

401

curl -s -o /dev/null -w "%{http_code}\n" -u admin:wrongpw http://127.0.0.1:9090/plugins/restapi/v1/users

401

六、错误码小结（实测归纳）

状态码触发条件（实测）
200查询成功（含空集合）
201创建成功（POST /users）
401缺少凭据、凭据错误、未启用插件时的无会话访问
404路径不存在（如 1.12.0 无 /status 路由）
409创建已存在的用户
302 → /login.jsp管理台通配豁免未生效（见排障一节）

七、安全建议

  • 生产环境优先 secret 或 custom 模式，避免管理员口令在网络中反复传输；启用后到 System Properties 检查 plugin.restapi.secret 的实际值；
  • 用 plugin.restapi.allowedIPs 限制调用来源 IP；
  • 9.0.0 起 REST API 支持 HTTPS 端口（9091）调用，管理台与 API 均建议置于 TLS 之后；
  • plugin.restapi.serviceLoggingEnabled=true 会记录 API 调用，排障期开启、常态关闭。

八、参考