Ejabberd中Matrix网关模块的JSON编码问题分析与解决方案

背景介绍

Ejabberd作为一款成熟的XMPP服务器，在其24.x版本中引入了Matrix协议网关功能（mod_matrix_gw模块），用于实现XMPP与Matrix协议之间的互通。这项功能在部署过程中可能会遇到JSON编码相关的技术问题，特别是在Erlang/OTP版本升级后。

问题现象

在Ejabberd 24.06及24.12版本中，当使用Matrix网关功能时，系统日志会出现以下关键错误：

exception error: {unsupported_type,{[{<<"old_verify_keys">>,{[]}},...]}

错误发生在json:do_encode/2函数调用时，表明系统无法正确处理特定的JSON数据结构。

技术分析

问题根源

1. 数据结构特性：Matrix网关需要生成包含特定字段顺序的JSON对象（用于签名验证），这些数据以有序的键值对列表形式表示
2. 编码器差异：
   • Erlang 26及之前版本使用外部JSON库处理
   • Erlang 27引入了内置json模块，对输入数据结构有更严格的要求
3. 类型转换问题：有序的键值对列表（proplists）与新的json模块期望的数据格式不兼容

影响范围

• 使用Erlang/OTP 27运行Ejabberd 24.x版本
• 启用了mod_matrix_gw模块的部署环境
• 进行Matrix服务器信息查询时触发（/_matrix/key/v2/server请求）

解决方案

临时解决方案

对于无法立即升级的用户：

1. 降级到Erlang/OTP 26版本
2. 暂时禁用Matrix网关功能

永久修复方案

Ejabberd开发团队已提交修复代码（a4fd756），主要改进包括：

1. 新增misc:json_encode_with_kv_lists/1函数
2. 实现对有序键值对列表的特殊处理
3. 确保JSON字段顺序符合Matrix签名要求

验证方法

修复后可通过以下方式验证：

1. 访问Matrix Federation Tester工具
2. 检查服务器返回的签名信息
3. 确认日志中不再出现unsupported_type错误

最佳实践建议

1. 版本兼容性：

   • Ejabberd 24.12+建议搭配Erlang/OTP 27+
   • 升级时注意检查所有依赖模块的兼容性

2. 配置注意事项：

mod_matrix_gw:
  matrix_domain: "your.matrix.domain"
  key_name: "ed25519:key1" 
  key: "your_public_key_here"

3. 监控建议：
   • 定期检查ejabberd日志中的JSON相关错误
   • 监控Matrix网关的可用性状态

技术延伸

Matrix网关工作原理

1. 协议转换层：在XMPP和Matrix协议间转换消息格式
2. 身份验证：使用Ed25519签名验证服务器身份
3. 数据持久化：维护跨协议的用户映射关系

Erlang JSON处理演进

1. 历史方案：第三方库如jiffy、jsx
2. OTP 27改进：原生json模块提供更高性能
3. 数据类型映射：需要特别注意复杂嵌套结构的处理

总结

Ejabberd的Matrix网关功能为多协议互通提供了便利，但在Erlang版本升级过程中可能遇到JSON编码兼容性问题。通过理解底层机制和采用正确的解决方案，可以确保服务的稳定运行。建议用户保持关注官方更新，及时应用相关补丁。