matrixdotorg/matrix-bifrost

matrix-bifröst

![构建状态]([][#bifrost:half-shot.uk]([]

镜像概述和主要用途

matrix-bifröst 是一款通用傀儡桥接器，基于 libpurple 及其他后端实现，用于连接 Matrix 网络与其他类型的网络。该桥接器目前处于活跃开发阶段，主要用于实验和评估场景。

兼容性：已在 Node.JS v10 和 Synapse 0.34.0 环境中测试通过。

核心功能和特性

多后端支持

桥接器支持多种后端，可针对不同网络类型部署桥接服务：

xmpp.js 后端

• 直接桥接至 XMPP 网络，无需依赖 purple。
• 适用于需要高扩展性的 XMPP 桥接场景，基于 XMPP 组件实现。

node-purple 后端

• 通过 libpurple2 桥接至多种支持 libpurple 的网络。
• 适用于小规模用户的简单桥接，或桥接至协议支持较少的网络。
• 作为可选依赖默认安装，需手动安装构建依赖（详见 https://github.com/matrix-org/node-purple%EF%BC%89%E3%80%82

使用场景和适用范围

• 实验与评估：目前处于活跃开发阶段，适合技术验证和功能测试。
• XMPP 桥接：
  • 大规模场景：使用 xmpp.js 后端实现高扩展性。
  • 小规模场景：使用 node-purple 后端简化部署。
• 多协议支持：通过 node-purple 后端接入 libpurple 支持的其他网络（如 IRC、Jabber 等）。

详细使用方法和配置说明

Docker 部署

两种后端均支持 Docker 部署，可通过官方 Dockerfile 构建镜像或直接使用 Dockerhub 镜像。

镜像获取与构建

• Dockerhub 镜像：已发布至 https://hub.docker.com/r/matrixdotorg/matrix-bifrost%E3%80%82
• 手动构建：

  shell
  docker build -t bifrost:latest .
  

运行容器

shell
docker run -v /本地数据路径:/data -p 外部端口:5000 bifrost:latest

配置说明

1. 数据卷挂载：

   • 需将 config.yaml、registration.yaml 存放于 /data 目录（通过 -v /本地数据路径:/data 挂载）。
   • 配置文件中 userStoreFile 和 roomStoreFile 需指向 /data 内的文件（如 /data/user-store.json）。

2. 端口映射：

   • 容器内部端口为 5000，需通过 -p 外部端口:5000 映射至宿主机端口。

3. 网络配置：

   • 避免配置项使用 127.0.0.1 或 localhost（容器内无法解析）。
   • 例外：bridge.domain 必须设置为 homeserver 的 URL。

非 Docker 部署

依赖安装

1. 基础依赖：

   shell
   yarn install
   

2. node-purple 额外依赖：需安装构建依赖（详见 https://github.com/matrix-org/node-purple#node-purple%EF%BC%89%E3%80%82

配置步骤

1. 复制配置文件：

   shell
   cp config.sample.yaml config.yaml
   

2. 修改核心配置：
   • 设置 domain（homeserver 域名）、homeserver.url（homeserver 地址）。
   • 调整 userStoreFile 和 roomStoreFile 路径（如 ./data/user-store.json）。
   • 通过 sed 快速替换域名：

     shell
     sed -i "s/domain: \"localhost\"/domain: \"$YOUR_MATRIX_DOMAIN\"/g" config.yaml
     

3. 生成注册文件：

   shell
   yarn genreg -- -u http://桥接器地址:端口
   

   • 注册文件需被 homeserver 读取，例如在 Synapse 的 homeserver.yaml 中配置：

     yaml
     app_service_config_files:
       - "/路径/to/bifrost-registration.yaml"
     

   • 重启 Synapse 使配置生效：synctl restart。

后端配置

xmpp.js 后端专项配置

1. 修改 config.yaml：

   yaml
   purple:
     backend: "xmpp.js"
   

2. 调整注册文件中的别名和用户正则表达式（将 _purple_ 替换为 _xmpp_），并同步至 config.yaml。
3. 配置 XMPP 服务器组件参数（在 purple.backendOpts 中设置）。
4. 启用自动注册和门户功能（在 config.yaml 中配置 autoregistration 和 portals）。

启动服务

• 使用 node-purple 后端：

  shell
  ./start.sh  # 自动预加载 libpurple 库，需调整脚本中的端口（默认 9555）
  

• 非 node-purple 后端：

  shell
  yarn start -- -p 端口
  

账户绑定与管理

账户配置

1. 准备账户文件：

   • 通过 Pidgin 在本地创建账户，导出 ~/.purple/accounts.xml。
   • 将 accounts.xml 复制至桥接器服务器的 ~/.purple/ 目录（非 Docker 环境）或容器内对应路径。

2. 绑定账户至 Matrix 用户：

   • 与桥接器用户发起对话，执行以下命令：

     accounts add-existing 协议名 用户名  # 协议名和用户名需与 accounts.xml 一致
     accounts enable 协议名 用户名        # 启用账户
     

   • 账户将自动连接至目标网络。

常见问题

容器内无法解析 localhost

• 配置文件中避免使用 127.0.0.1 或 localhost（容器内指向自身），需使用宿主机 IP 或域名。
• 例外：bridge.domain 必须设置为 homeserver 的 URL（如 https://matrix.example.com）。

桥接器崩溃（段错误）

• node-purple 后端仍在优化中，建议报告复现步骤及相关插件信息（详见 贡献指南）。

测试

运行测试套件：

shell
yarn test

注意：使用前请仔细阅读 README 及后端专项文档，部分后端需额外安装依赖。提交 issue 或 PR 前请先阅读 CONTRIBUTING.md。