视频加载失败

听雨茶室站点互联指南

听雨茶室站点互联指南
48 分钟听雨茶室 / Matrix / 站点互联

听雨茶室站点互联指南

“面向友站站长的 Matrix 接入指南,涵盖独立账号、共享转发、昵称和头像、消息同步,以及雪宝的站点和冷汐的杂货铺的接入方式。”

9575 字
48 分钟
听雨茶室站点互联指南

听雨茶室的互联效果,聊天区显示来自不同站点的发言、提及、表情和站点来源
听雨茶室的互联效果,聊天区显示来自不同站点的发言、提及、表情和站点来源

同一个公开 Matrix 大厅把各站的聊天室连在一起。任一互联站点在这个大厅发出的公开消息,会经 Matrix 同步到其他已接入的站点。

图中可以看到来自冷汐的杂货铺和雪宝的站点的消息,以及听雨显示的站点来源。

加入互联的要求#

  • 站点合规。 申请的站点须遵守适用的法规,站长应能处理违规内容和用户反馈。
  • 必须是播客站点。 申请时提供站点主页、公开聊天室链接,以及能联系到站长的方式。
  • 发言必须限流。 在服务端对每个发言身份限制发送频率,再给整个站点的互联出站队列设置限额,防止一个人连发或多个账号一起刷屏。文字、表情、图片和附件都要纳入限流。共享转发账号也要按原发言人分别计数。超限时给茶友明确的等待提示,避免暂存大量消息后一次全发到大厅。
  • 明确同步范围。 在发言入口提示消息会同步到 Matrix 和其他站点,只接入双方约定的互联房间。站长能暂停本方转发,以便处理误转发或刷屏。

第一次接入,从这里开始#

你现在的情况第一步听雨这边怎么配合
有 Matrix 账号,想进来聊天目前可用现有账号加入 #lobby:detached.online。切换为仅邀请后,先提供完整 Matrix ID 以便接收邀请个人入房无需提交站点接入申请
没有自己的服务器,想让网页聊天室接入参考雪宝的旧方案,在托管的聊天页中接入 Matrix 大厅。需要代发网页消息时,可以向我申请专用转发账号我可以免费提供一个指定用于本站互联的 Matrix 转发账号,并为它登记站点来源
有自己的网页聊天室,准备共用一个转发账号提供专用转发账号的完整 Matrix ID,约定每条消息怎样携带原昵称和头像为该账号登记站点来源,按双方确认的格式读取转发资料
有自己的 Matrix 服务器,茶友各有独立账号提供 Matrix 服务器名和一个示例账号。显示名用「昵称 · 站点名」,头像用 Matrix 成员资料核对大厅里实际收到的账号和头像,确认听雨显示的站点来源

复制这份接入申请#

把下面几项填好,发到 关于我页面公开的联系邮箱。邮件标题写「茶室互联接入 · 你的站点名」。

站点正式名称:
站点主页:
公开聊天室链接:
接入方式(共享转发/独立 Matrix 账号):
Matrix 服务器名和示例账号,或共享转发账号的完整 Matrix ID(可填「申请免费转发账号」):
首轮要验收的功能(例如文字、昵称与头像、回复):

收到后,我会和你确认大厅、站点来源标签和首轮联调范围。需要免费转发账号时,我会单独提供账号资料。这是由我为互联站点分配的专用账号,听雨的 Matrix 服务器仍关闭公开注册。转发程序可以跑在托管的 Worker 或其他服务端环境,令牌放在私有配置里。

友站互联从哪个入口开始#

听雨通过 Matrix 公共大厅交换新消息。目前连接的大厅别名是 #lobby:detached.online,可以从 大厅加入链接 打开。听雨使用的 homeserver 地址是 https://matrix.rainzt.cn。联调时重新解析别名并核对真实房间 ID,尤其是大厅重建以后。房间 ID 当作不透明字符串保存,遇到没有域名后缀的 ID 也原样使用。

各站的网页入口也可以直接打开,方便从熟悉的站点进来。悬停或轻触站名可以查看友站资料。

DetachedDetached独立开发 · 技术工具 · 生活记录独立开发者的技术、工具与生活博客 · 雪宝的站点AIOVTUE-雪博客主题 · 开源 · 教程雨滴会记录生命中的每一个瞬间 · 冷汐的杂货铺冷汐的杂货铺个人博客 · 独立开发 · 技术分享你好谢谢小笼包再见 · SomoeSomoe Home个人博客 · 技术分享 · 生活随笔在文字的深海里,拾贝而行

只想从 Matrix 进来聊天#

使用已有 Matrix 账号,通过支持 Matrix 的客户端加入这个公开大厅。用自己的账号发送消息,来源取自实际 Matrix 用户 ID 及听雨端的映射。这样可以先验证「Matrix → 听雨」和「听雨 → Matrix」两条方向。站点网页是否接入,需要这家站点自己的适配器。

想把自己的网页聊天室接进来#

有独立 homeserver 的站点,可以用本方账号加入同一房间,利用 Matrix 原生联邦。使用 EdgeChat 或自建网页聊天室的站点,则要让服务端或 Worker 连接 Matrix Client-Server API,把本地原创消息送进大厅,再把大厅的新事件写入本站。原版 EdgeChat 的站间互联需要额外实现这段 Matrix 适配。

  1. 发出上面的接入申请,确认适配器只绑定双方约定的互联房间,并按下文准备新身份的邀请流程。
  2. 选定服务端发言身份。能为每个网页茶友维护独立 Matrix 身份的一方,用自己的 homeserver 和 Application Service 管理虚拟账号。采用共享账号的一方,为站点单独准备转发账号,并请听雨配置该完整账号的来源和可信元数据。
  3. 在 Worker Secret 或服务端私有配置中保存访问令牌。使用自己的最小权限账号和设备,保持令牌、邮箱、登录资料和管理字段留在各站内部。
  4. 网页入口明确提示「这里的公开消息可能同步到 Matrix 及互联站点」。仅转发联调启用后的新公开消息,旧历史继续留在原站。
  5. 先验证纯文字、署名、回复和重试,确认双向都正确后,再逐项打开贴纸、图片、语音和文件。跨站发布前按文末清单联调一次。

未来仅邀请入房的流程#

  1. 注册 Matrix 身份。 在你的 homeserver 创建独立发言身份,保存完整 Matrix 用户 ID。使用 Application Service 时,由服务端为其命名空间内的新身份注册。使用听雨分配的共享转发账号时,这一步由站长提供已有身份。 Matrix 注册接口 · Matrix Application Service API
  2. 用你的账号发邀请。 使用你已经在大厅里、且有邀请权限的 Matrix 账号,调用 POST /_matrix/client/v3/rooms/{roomId}/invite,请求体为 {"user_id":"@新身份:example.org"}。若你的账号还没有邀请权限,先联系房管。 Matrix 邀请接口
  3. 后台替新身份接受邀请并入房。 适配器以被邀请的新身份调用 POST /_matrix/client/v3/join/{roomIdOrAlias}。使用新身份自己的会话,或由 Application Service 在其命名空间内代表该身份调用。确认该身份的房间成员状态是 join 后,再开始转发。 Matrix 加入房间接口

切换为仅邀请前先检查什么#

  • 入房与历史。 房管用 m.room.join_rules 的 join_rule: "invite" 控制谁能进房。另用 m.room.history_visibility 控制谁能看历史。希望新成员从加入以后开始看,可以选 joined。切换前确认各站网页还会展示哪些旧消息或缓存副本,并核对房间目录是否仍需公开展示。 Matrix 加入规则 · Matrix 历史可见性
  • 房间权限。 查 m.room.power_levels。邀请账号需要达到 invite 门槛,发言身份需要能发送 m.room.message、m.sticker 等接入所需的事件。撤回他人消息和发起 @room 分别按 redact 和 notifications.room 核对权限。给各账号配置实际需要的权限。 Matrix 房间权限规范
  • 先验证桥接再切换。 目前听雨桥接仍要求公开加入和公开历史。正式切换前需要先完成桥接适配,在仅邀请的房间里验证邀请、入房、收发和重连。

Matrix 里的名字怎么写#

对外展示统一约定为 昵称 · 站点名。中间是一个间隔点,两边各有一个半角空格,站点名放在最后。站点名使用双方约定的正式名称,网页侧的「来自」标签可以用配置里的域名简称。

原始昵称和来源Matrix 中应看到的署名
朝朝听雨在听雨茶室发言朝朝听雨 · 听雨茶室
遇见在冷汐的杂货铺发言遇见 · 冷汐的杂货铺
雪中来客在雪宝的站点发言雪中来客 · 雪宝的站点

有独立发言身份时,在 Matrix 房间成员的显示名上设置这串署名,消息正文保持原文。听雨目前采用此方式,给本地茶友分配并持久保存 @zzty001:matrix.rainzt.cn 这一类账号。虚拟账号跨重启复用,更新昵称或头像时维持同一个身份。

使用共享转发账号时,Matrix 客户端的发送者栏会显示转发账号自己的房间资料。每条转发消息还要带上原发言人的昵称和头像,让接收站能按这条消息恢复发言人。共享账号自己的房间资料保持稳定。下文分别给出听雨当前能解析的昵称、头像格式,以及独立账号的接法。

共享转发账号怎样收发昵称和头像#

共享转发账号使用 m.room.message,普通文字的 msgtype 为 m.text。站长先设置转发账号自己的昵称和头像。网页茶友在来源站填写的昵称和头像,由转发程序随每条消息传给接收端。接收站要按完整 Matrix 发送者 ID 识别可信转发账号,再解析原发言人的昵称、头像和正文。两个茶友连续发言时,应分别显示各自的头像和昵称。

目前听雨通过正文协议头同时接收共享转发账号传来的昵称和头像。下面以雪宝的站点早期转发方案为例。首行放资料,换行后放原文。

[ID:雪中来客];[URL:https://daily.yybb.us/avatars/guest.webp]
下午好,我从雪宝的站点过来。

发送端在 ID 填原昵称,在 URL 填可直接读取的 HTTPS 头像地址。听雨也兼容现有的 Markdown 链接或图片写法。头像地址使用 HTTPS,无用户名、密码或自定义端口。接收端导入后隐藏协议头,显示原文、原昵称、对应头像和可信配置里的站点来源。头像读取失败时允许正常显示消息,并使用可用的默认头像。普通 Matrix 成员的消息按其房间成员资料处理。

正文协议以昵称作为身份键,同名会撞在一起,改名也会产生新身份。结构化 v1 可以传稳定用户 ID。以下示例中的 user-815 是网站数据库里的本地用户标识。

{
"msgtype": "m.text",
"body": "雪中来客 · 雪宝的站点\n下午好,我从雪宝的站点过来。",
"org.tea-room.bridge": {
"version": 1,
"site": "https://daily.yybb.us",
"actor": {
"id": "user-815",
"nick": "雪中来客"
},
"text": "下午好,我从雪宝的站点过来。"
}
}

body 给 Matrix 客户端阅读,text 是写入茶室的原文,actor.id 在改名、更换头像和重启后保持稳定。听雨用「完整 Matrix 发送账号 + 本地用户 ID」区分转发用户,两个重名茶友可各有自己的资料。信任权限按完整账号授予。来源以听雨配置为准,site 是便于其他客户端识别的公开信息。接口见 Matrix Client-Server API。

如需同时保留稳定 ID 和原发言人的头像,双方接收端要一起扩展并约定头像字段。听雨当前会优先读有效的 v1 数据,v1 当前读取 ID、昵称和正文。选用现有头像协议头时,发送方使用上面的正文格式即可。

适配器从自己所用账号的 homeserver 发起请求,使用 Authorization: Bearer <访问令牌> 请求头。常用接口如下,路径里的房间、事件和事务 ID 用实际值替换。

操作Matrix API
确认当前登录账号GET /_matrix/client/v3/account/whoami
将房间别名解析成 IDGET /_matrix/client/v3/directory/room/{roomAlias}
邀请新身份有邀请权限的账号调用 POST /_matrix/client/v3/rooms/{roomId}/invite
接受邀请并加入房间新身份调用 POST /_matrix/client/v3/join/{roomIdOrAlias}
拉取新事件GET /_matrix/client/v3/sync,后续请求的 since 使用上次成功处理的 next_batch
发送文字PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId},将上面的 JSON 作为请求体,保存响应里的 event_id
撤回事件PUT /_matrix/client/v3/rooms/{roomId}/redact/{eventId}/{txnId}

雪宝的站点从 EdgeChat 到 Matrix 网页客户端#

以前的方案#

雪宝早期在博客里嵌入了部署于 Cloudflare 的 EdgeChat。当地的 EdgeChat 聊天按自己的账号和房间运行,互联大厅则出现在 EdgeChat 界面顶部,单独读取和展示 Matrix 房间的消息。访客当时需要先注册再登录。 雪宝当时的聊天室介绍

听雨这一侧也为雪宝的站点做过共享账号适配。最早雪宝本人的 @aiovtue:matrix.rainzt.cn 兼作转发入口,后来改由专用账号 @aiprate:matrix.rainzt.cn 转发,本人账号用于雪宝自己发言。共享账号发来的网页访客消息,听雨可按上面的协议读取原昵称、头像和正文,再显示「雪宝的站点」来源。

Matrix 客户端中显示共享转发消息的原始正文,第一行包含 ID 和 URL 字段
Matrix 客户端中显示共享转发消息的原始正文,第一行包含 ID 和 URL 字段

共享转发格式实拍。Matrix 客户端里可以看到原始的 [ID:…];[URL:…] 协议头。听雨识别到可信转发账号后,会从中提取原发言人的昵称和头像,聊天区显示协议头后面的正文。

现在的方案#

雪宝在 2026 年 11 月 19 日介绍了重构后的聊天室。现在聊天页作为静态页面随博客部署,浏览器内的 matrix-js-sdk 负责与 Matrix homeserver 通信,页面打开同一个公共大厅 #lobby:detached.online。新页面自身无需额外的 EdgeChat Worker 运行。 雪宝的重构说明 · 雪宝的站点聊天页面

  • 访客登录。 打开雪宝的站点的「聊天」,选择「访客登录」,填写昵称和邮箱。雪宝的文章说明访客资料与博客评论入口互通。登录后可点击侧栏头像设置自定义头像或退出。
  • 账号登录与注册。 已有 Matrix 账号的茶友,切到「账号登录」,选择账号实际所属的服务器。登录后页面会自动加入大厅。雪宝页面目前默认填入的 https://matrix.rainzt.cn 是配置失误。听雨的 Matrix 服务器未开放公开注册。需要注册新账号时,请使用雪宝自己的服务器 https://matrix.yybb.us。
  • 接收和显示。 使用自己的 Matrix 账号发言时,接收端按实际发送者的完整 Matrix ID 和房间成员昵称、头像显示。收到可信共享转发账号的消息时,仍按相应协议恢复原发言人。雪宝的站点当前的访客模式分配什么 Matrix 身份,应以该模式实际发出的事件为准。

冷汐的杂货铺#

冷汐使用自己的 Matrix 服务器 matrix.lengxiqwq.com,本人的账号是 @lengxiqwq:matrix.lengxiqwq.com。网页茶友也有各自的独立账号,例如 @u_7bfe75ddf8:matrix.lengxiqwq.com。其中 7bfe75ddf8 是冷汐站点生成的哈希值。接收端用完整 Matrix 用户 ID 区分身份,从房间成员资料读取显示名和头像。

遇见从冷汐站点发言时,由自己的独立账号发送,Matrix 的显示名写 遇见 · 冷汐的杂货铺,成员头像使用遇见的头像,消息正文直接保留原文。接收站可将 matrix.lengxiqwq.com 映射为来源标签 lengxiqwq.com。验收时分别检查冷汐本人发言与两位网页茶友发言,确认实际发送者、署名和头像分别对应到正确账号。

同一条消息在三端的显示#

在冷汐的杂货铺发出「互联测试01」后,两边都能看到遇见的头像和带站点后缀的署名。听雨还会在昵称旁显示来源标签。

冷汐的杂货铺 · 遇见发出「互联测试01」
冷汐的杂货铺 · 遇见发出「互联测试01」
听雨茶室 · 同一条消息带有来源标签
听雨茶室 · 同一条消息带有来源标签

在 Matrix 客户端打开这条消息的「查看源代码」。正文仍是「互联测试01」,事件的 sender 是遇见的独立账号 @u_7bfe75ddf8:matrix.lengxiqwq.com。

Matrix 原始事件中的正文和独立发送账号,右侧成员列表显示遇见的署名
Matrix 原始事件中的正文和独立发送账号,右侧成员列表显示遇见的署名

回复、@、撤回和媒体怎样对接#

能力适配规则
回复发送 m.relates_to.m.in_reply_to.event_id,值是回复目标在同一个 Matrix 房间中的事件 ID。本地表保留双向映射。目标未同步时可保留可读的引用说明
编辑原消息已映射时使用 Matrix 替换事件,关系为 m.replace,正文放进 m.new_content。接收时核对同房间、原事件和发送者,只修改对应正文
个人 @关系字段使用 m.mentions.user_ids 传实际 Matrix ID。HTML 表现可用 matrix.to 账号链接,正文保留能阅读的昵称。相同接收者只通知一次
全员 @使用 m.mentions.room,发送者须具备 Matrix 房间的群提醒权限。听雨将获授权的原生 Matrix 全员提醒呈现为「@全员」,共享转发账号的正文不能自行提升群提醒权限
已读回执独立 Matrix 身份可对已映射的消息发送公开 m.read 回执。接收时从 /sync 的临时事件读取 m.receipt,按已知的阅读者、房间和消息映射更新。用共享账号发回执时只能表达该账号的阅读状态
图片和贴纸普通图片走 m.image,独立贴纸可用 m.sticker,行内表情可用下文的 m.text 富文本格式。媒体用 Matrix 内容仓库的 mxc:// 引用,并填写消息类型所需的 MIME、尺寸和大小
文件、短语音和视频文件走 m.file,语音走 m.audio,Matrix 视频可作为附件接收。听雨本地选文件上限 20 MB;Matrix 导入受类型、媒体可访问性和桥接大小限制,短语音能否直接播放取决于可下载与可处理情况
撤回保存对应事件 ID,走 Matrix redaction。原事件未发送时取消待发任务。收到远端红删后更新已映射记录,先收到红删也要记住它,避免重连后把原文补回来

媒体下载与鉴权#

收到头像、图片、贴纸或语音的 mxc://服务器名/媒体ID 后,通过所用账号的 homeserver 请求带认证的下载接口 GET /_matrix/client/v1/media/download/{serverName}/{mediaId}。需要缩略图时用对应的 thumbnail 接口。服务端桥接把自己的访问令牌放在 Authorization: Bearer … 请求头里,再按本站的访问权限向网页提供媒体。 Matrix 媒体下载接口 · Matrix 缩略图接口

验收时从另一台 homeserver 刚上传一张贴纸,再测新头像及普通图片或语音,分别检查完整媒体和缩略图。旧附件能打开时,也要单独验证新媒体的认证路径。

Markdown 正文怎么互通#

互联时可以把 Markdown 源文放进 m.text 的 body。听雨收到后会解析常用 Markdown,包括粗体、斜体、删除线、链接、引用、列表、表格、行内代码、代码块和 HTTPS 图片。接入方如果也能生成 Matrix 富文本,可以同时提供转换后的 HTML,方便支持富文本的客户端显示。

想发送的内容Markdown 写法富文本中的对应元素
强调或订正**加粗**、*斜体*、~~旧内容~~strong、em、del
带标题的链接[听雨茶室](https://rainzt.cn/chat/)a,保留链接标题
引用和列表行首用 > 引用,另起一行用 - 列条目blockquote、ul、li
配置字段和代码用反引号围住行内字段,多行代码使用围栏代码块code,多行代码用 pre 包住
图文混排![图片说明](https://example.org/chat.webp)上传图片后在 img 里使用 mxc://,并保留替代文字

接收端优先显示经过安全过滤的 formatted_body,不可用时才显示 body。支持 Markdown 的网页可以解析回退正文,纯文本客户端则可能原样呈现符号。引用块只是正文排版,点击跳回原消息还需要标准的 Matrix 回复关系。代码块中的 @ 和图片语法按代码显示。

站点表情包怎么发到 Matrix#

目前互联站点已经能接收或转发贴纸,其中有的路径会把贴纸转成普通图片。这样能显示画面,但转发成 m.image 后,接收端看到的就是一条普通图片消息。后续加入互联的站点请按 Matrix 规范保留贴纸类型和行内表情语义。网页为了展示而解码或转换图片时,仍应保留原来的消息类型。

本站专用的表情短码在外站通常没有对应资源。转发前先解析出实际图片。动态表情可用 GIF 或目标客户端支持的动画 WebP,静态表情可用 PNG 或 WebP。上传到 Matrix 媒体仓库后,使用返回的 mxc:// 地址。 Matrix 媒体仓库

发送内容互联事件写法官方规范
单独发送的贴纸事件类型用 m.sticker,在 content 中提供描述用的 body、媒体 url 和图片 infoMatrix 原生贴纸
富文本里的自定义表情事件用 m.room.message,msgtype 用 m.text,在 formatted_body 里用带 data-mx-emoticon 的 img 标识自定义表情。图片 src 使用 mxc://,alt 提供可读名称Matrix 自定义行内表情
普通图片事件用 m.room.message,msgtype 用 m.image,填写图片 url 和适用的 info 字段Matrix 图片消息

下面以冷汐的「鬼脸」为例,只列出发送请求需要的 content。把 Markdown 图片写入 body,同时提供转换后的安全 HTML,让支持 Matrix 富文本的客户端能直接显示表情。

{
"msgtype": "m.text",
"body": "![鬼脸](https://lengxiqwq.com/assets/stickers/miku/miku_%E9%AC%BC%E8%84%B8.webp)",
"format": "org.matrix.custom.html",
"formatted_body": "<img data-mx-emoticon src=\"mxc://matrix.lengxiqwq.com/ZOafz4CVUysiOC24cFlVp8fLI6DMRFIl\" alt=\"鬼脸\" title=\"鬼脸\" height=\"32\">"
}
  • 发送端提供两种表示。 body 和 msgtype 必填。发送富文本时,format: "org.matrix.custom.html" 与 formatted_body 成对提供。对 img 使用 mxc:// 和可读的 alt,尺寸用 width 或 height。客户端可能过滤内联样式,排版由客户端处理。 Matrix 消息类型规范
  • 听雨的 Markdown 路径。 听雨从 Matrix 导入这类文字消息时,用 body 里的 Markdown 渲染 HTTPS 图片。因此只发 msgtype 和带 Markdown 的 body,本站也能显示表情,前提是图片地址可访问并通过本站的图片链接校验。普通文字也能只用 body。其他客户端可能会把 Markdown 原样显示。听雨会从富文本中识别部分 Matrix 提及,消息里的图片仍走本站的 Markdown 渲染。
  • 事件外层和自定义字段。 示例原事件中的 event_id、sender、origin_server_ts 和 unsigned 由 Matrix 事件或同步响应提供,发送时提交的是 content。com.lengxiqwq.msg_uid 是冷汐站点的自定义字段。没有提及对象时可以省略 m.mentions。

富文本表情从冷汐发到听雨#

冷汐站点的「真的吗」表情以 m.text 发出。Matrix 事件详情里,body 是指向站点 WebP 的 Markdown 图片,formatted_body 则引用上传后的 mxc:// 媒体。

冷汐站点的「真的吗」表情在 Matrix 事件详情中同时携带 Markdown body 和 HTML formatted_body
冷汐站点的「真的吗」表情在 Matrix 事件详情中同时携带 Markdown body 和 HTML formatted_body

听雨收到这条消息后,按 body 的 Markdown 渲染图片,消息组上方仍显示遇见的头像、署名和站点来源。

听雨渲染来自冷汐站点的「真的吗」表情,消息组顶部保留遇见的头像与来源标签
听雨渲染来自冷汐站点的「真的吗」表情,消息组顶部保留遇见的头像与来源标签

听雨也能发富文本行内表情#

把文字和听雨内置表情「戳一戳」一起发送时,这条消息以 m.room.message 发到 Matrix,msgtype 是 m.text。和冷汐的发法一样,body 保留文字和指向站点 WebP 的 Markdown 图片,formatted_body 则把同一段文字和引用 mxc:// 的 HTML 图片放在一起。支持富文本的客户端可以把表情显示在文字旁边,支持 Markdown 的友站也能从 body 渲染图片。

听雨内置「戳一戳」和文字一起发送时的 Matrix 事件,含 m.text、body 和 formatted_body
听雨内置「戳一戳」和文字一起发送时的 Matrix 事件,含 m.text、body 和 formatted_body

两站使用的是 Matrix 规范定义的 m.text 富文本结构,format: "org.matrix.custom.html" 与 formatted_body 成对提供。把 HTTPS Markdown 图片放进 body 是两站采用的兼容写法。Matrix 规范要求 body 是字符串,具体是否解析其中的 Markdown 由客户端决定。听雨的本地表情短码另保存在桥接元数据中。 Matrix 消息类型规范

独立贴纸从听雨发到 Matrix#

在听雨单独发送「开心」贴纸时,Matrix 事件类型是 m.sticker。事件里的 content.url 指向 Matrix 媒体仓库,info 记录这张 WebP 的尺寸和大小。

听雨发送「开心」时的 Matrix 事件详情,事件类型为 m.sticker,媒体格式为 image/webp
听雨发送「开心」时的 Matrix 事件详情,事件类型为 m.sticker,媒体格式为 image/webp

Matrix 客户端把这条消息显示为一张独立贴纸,发送者是「朝朝听雨 · 听雨茶室」。

Matrix 大厅中显示朝朝听雨通过独立账号发送的「开心」贴纸
Matrix 大厅中显示朝朝听雨通过独立账号发送的「开心」贴纸

联调时先发一条同时带两个字段的消息,确认支持富文本的接收端只显示一次。再发一条只带 msgtype 和 Markdown body 的消息,在听雨检查 HTTPS 图片能否渲染。上面「真的吗」的截图对应的是同时提供 Markdown 和富文本的事件。

在线状态怎样适配#

Matrix 用 m.presence 更新用户状态。接收端从 GET /_matrix/client/v3/sync 响应顶层的 presence.events 读取事件,按 sender 的完整 Matrix 用户 ID 更新成员状态。需要补取某位成员的当前状态时,可以请求 GET /_matrix/client/v3/presence/{userId}/status。房间成员名册用 m.room.member 建立,在线状态单独更新。 Matrix Presence 规范

{
"type": "m.presence",
"sender": "@visitor:example.org",
"content": {
"presence": "online"
}
}
收到的状态听雨如何显示
online在线
unavailable离开
offline离线
缺少有效状态、查询失败或缓存过期未知,这是听雨的展示状态
  • 按房间和账号匹配。 只展示仍加入当前互联房间的成员。对方退出后从名册移除。已加入房间或刚发过消息,都不足以推断在线。
  • 共享转发账号单独处理。 听雨将可信共享账号标为「转发账号」。即使它在线,也无法由此判断网页访客是否在线,转发账号也不计入在线人数。
  • 状态会过期。 听雨优先使用同步到的事件,也会按需查询成员状态。缓存超过 120 秒后显示「未知」,同步中断时也会清除已缓存的状态。听雨生成的 Matrix 发言账号从远端名册排除,本站用户的在线状态由本地连接提供。

联调时先用一个独立 Matrix 账号验证「在线」「离开」「离线」的显示,再观察成员退出、同步中断,以及共享转发账号在线时的名册变化。

断线以后怎么接着走#

适配器应在数据库里持久化待发队列、发件事务 ID、已处理 Matrix 事件 ID、local message ID 与 Matrix event ID 的映射,以及每个账号和房间的 /sync 游标。

  • 本地原创消息与待发记录一起落库。发送超时或网络中断后,用同一个发送身份沿用原来的 txnId 重试。遇到 429 / M_LIMIT_EXCEEDED 时按 Retry-After 等待,兼容旧服务端的 retry_after_ms,没有等待提示时逐步延长重试间隔。重新连上后,按本站限速逐步消化待发队列。 Matrix 限流规范 · Matrix 事务 ID 规范
  • 遇到 403 / M_FORBIDDEN 时暂停对应操作,先核对当前身份是否已入房,以及该账号是否有发送、邀请或撤回权限。等权限问题修复后再恢复。 Matrix 房间权限规范
  • 第一次连接只建立同步基准。从游标拉取后续事件,事件成功入库或被明确识别为跳过之后再推进游标。遇到有限时间线时从原有锚点补页,找不到锚点就标记断档,留给站长检查。
  • 收到的跨站副本记录来源和事件 ID,只用于本站显示。服务端应识别自己的发送回声,并用唯一键拦住重复导入。
  • 发送和接收前都确认账号仍在约定的未加密房间,并符合当前桥接所支持的入房和历史可见性规则。房间迁移、访问条件变化或开启加密时,先暂停并核对。换房间后单独建立游标和队列。
  • 各站私有账号、个人设置和浏览器会话各自保存。

两个方向各能显示什么#

下表以 Matrix 大厅为分界,说明听雨桥接代码目前处理的行为。友站网页能否显示同样的内容,取决于该站接收端。给每个友站验收时,可以在表旁记下「通过」「降级可读」或「待实测」。

测试项友站经 Matrix 发到听雨听雨发到 Matrix 和友站
纯文字导入 body,有可信转发资料时读取原文和原发言人Matrix 收到文字,独立账号的显示名带「· 听雨茶室」
Markdown 正文听雨按 body 解析链接、引用、列表和代码等常用格式友站按收到的富文本或回退正文显示。联调时核对排版、换行和链接
行内表情,body 和 formatted_body 都有听雨从 Markdown body 渲染 HTTPS 图片本站内置行内表情可生成带 mxc:// 图片的富文本。友站网页需测试自己的富文本渲染
行内表情,仅 Markdown bodyHTTPS 图片能加载时,听雨按 Markdown 渲染只按纯文本显示的客户端可能会显示原始 Markdown。接收端也可选择解析 Markdown
独立贴纸 m.sticker拉取媒体后作为贴纸图片显示。动画能否保留取决于媒体是否可处理本站支持的独立贴纸可发出原生 Matrix 贴纸事件。友站需处理该事件类型
回复与编辑原事件有映射时,可保留回复跳转或更新原消息发出标准回复与替换关系。友站需核对原事件的映射和发送者
撤回Matrix 红删会清除映射到听雨的内容有对应 Matrix 事件和撤回权限时发出红删。友站需处理已存在的副本
@ 与已读按实际 Matrix 用户 ID 匹配提及,按已映射阅读者和消息处理公开已读可发送已解析的 Matrix 提及和独立身份的公开已读。友站需验证通知对象与阅读者
在线状态听雨读取大厅成员的 m.presence,共享账号只标为「转发账号」听雨网页用户的在线状态来自本地连接,友站可按各自的 Matrix 状态来源显示
图片、文件与语音用标准媒体事件导入。超出限制或无法处理的附件会按情况降级,短语音能否直接播放要单测可发送标准图片、文件和短语音事件。友站分别检查预览、下载、播放与撤回

公开互联状态能确认听雨与大厅的桥接是否在线。每家网页端实际渲染过哪些消息,按下面的步骤记录。 听雨公开互联状态

三端联调怎么跑#

找一段双方约好的测试时间,同时打开友站网页、Matrix 客户端和听雨茶室。每条测试消息带上容易搜索的短标记,例如 [互联测试-01]。保存对应的 Matrix event_id,需要核对时可以确认三端看的是同一条事件。

  1. 先验收文字和站点署名。 从友站发一条,再从听雨回一条。三端都应该只出现一次。Matrix 上确认独立账号的显示名形如「遇见 · 冷汐的杂货铺」,到听雨点头像核对实际昵称、头像和站点来源。
  2. 让两个同名茶友轮流发言。 两人用不同头像,其中一人发完后改名再发。独立账号按完整 Matrix ID 区分,结构化转发按可信发送账号和稳定的 actor.id 区分。旧正文协议以昵称为键,若遇到同名合并或改名后出现新身份,记录为该协议的限制。使用雪宝的站点新版时,分别用「访客登录」和「账号登录」发一条,记下事件实际的 sender,并核对头像来自事件里的转发资料还是 Matrix 房间成员资料。
  3. 用同一张「鬼脸」测三条。 第一条按前面的双格式 JSON 发。第二条只带 msgtype 和 Markdown body。第三条把同一张图上传到媒体仓库,以 m.sticker 发出。逐端记下是行内图片、大贴纸、原始 Markdown、替代文字还是加载失败。可再补一张动态 GIF,查看动画是否保留。
  4. 沿着同一条消息测操作。 回复「鬼脸」,点击引用回原消息。另发一条文字,编辑后确认原位置更新。对一位茶友发出提及,核对只有目标身份进入提及名单。让另一个账号读到消息,检查公开已读回执。最后撤回「鬼脸」,核对三端相应副本。
  5. 断开适配器后再恢复。 在双方同意的测试环境暂停一端同步,从另一端发两条带编号的消息,再恢复。确认编号按顺序出现且各只有一条。有待发或重试时,核对原事务 ID 和 event_id 的映射。

可以把每条测试结果记在同一个表里,遇到加载失败时保留 Matrix 事件 ID 和出错端,方便复查。

用例方向Matrix 事件 ID友站网页Matrix 客户端听雨结果
鬼脸,仅 Markdown友站 → 听雨测试后填写测试后填写测试后填写测试后填写待实测

接入前检查清单#

验收项通过时应该看到的结果
双向文字从你的网页发一条,在 Matrix 和听雨都只出现一次。再从听雨发一条,你的网页也只出现一次
署名在 Matrix 看到「遇见 · 冷汐的杂货铺」这类站点后缀。听雨里点头像,昵称和来源对应到正确茶友
身份和头像在雪宝的站点分别测试访客登录和账号登录。共享转发方案要验证同一账号发来的两条消息各有自己的昵称和头像。冷汐本人与网页茶友分别使用独立账号。使用稳定 ID 或独立账号的茶友改名后仍保留原身份
回复、编辑、@、已读各端都操作一次。能映射的引用点回原消息,文字编辑后更新原条目,被提及的人收到一次符合个人设置的提醒,已读显示对应的实际阅读者
媒体与撤回分别发送普通图片、独立贴纸、行内表情、文件和短语音。检查事件类型和行内表情标记是否正确,再分别撤回已转发和待发消息
仅邀请入房新身份注册后,由有权限的成员发邀请。后台以新身份接受邀请,确认状态为 join 再试发消息
历史和权限用刚加入的成员确认能看到的历史范围,分别测试普通发言和有权限账号发邀请
媒体鉴权用其他 homeserver 刚上传的媒体测试下载和缩略图,确认页面没有暴露桥接令牌
发言限流在测试环境连续发送文字和附件,确认限额生效、页面提示等待、恢复后队列按限速发送
断线恢复断开适配器期间产生的新消息可以补齐,超时重试只产生一条消息,重启仍使用上次游标
公共同步范围互联提示对访客可见,私人内容留在原处,公开事件中没有凭证及私有账号资料

听雨一侧可以查看 公开互联状态。connected 表示听雨桥接已经连上大厅,pending 是等待处理的待发数。实际接入结果以网页两端和 Matrix 都核对过同一批新事件为准。

来聊天的朋友随时可以 进听雨茶室。想接上自家茶室的站长,带上站点名、链接、Matrix 账号和准备支持的消息类型来找我,我们从一条能看到出处的问候开始。

后续我们也会继续向 Matrix 官方规范看齐。具体的事件格式和接口可以参考 Matrix Client-Server API 官方规范。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或打赏支持!

打赏
听雨茶室站点互联指南
https://rainzt.cn/posts/tingyu-tea-room-guide/
作者
Rain
发布于
2026-11-20
许可协议
CC BY-NC-SA 4.0

评论区

跳到正文
朝朝听雨
外观

站点主题

字体样式

‹ 返回
本文使用 AI 辅助创作,请注意甄别。
本文目录

文章目录