Skip to main content
[ PIER ]

Matrix Synapse with PostgreSQL

Matrix 参考 homeserver —— 开箱即用接入 PostgreSQL。

Service#chat#messaging#matrix#federation#postgresql

Matrix Synapse 是 Matrix 协议的参考 homeserver 实现 —— 一个开放的、去中心化的联邦标准,用于实时聊天、语音、视频和端到端加密消息。本模板提供 Synapse 加 PostgreSQL 后端(Synapse 唯一支持生产的数据库),预连线以便联邦和大房间从第一天起就能正确运行。

使用 Pier 部署

  1. 1打开 Pier 控制台,点击 Add service。
  2. 2从模板列表中选择 Matrix Synapse with PostgreSQL。
  3. 3选择版本、设置服务名称,Pier 会自动配置容器、存储和端口。
  4. 4如需 HTTPS,请绑定域名。Traefik 会自动签发 Let's Encrypt 证书。

什么是 Matrix Synapse?

Matrix 是去中心化、联邦实时通信的开放标准 —— 聊天、语音、视频、文件、 端到端加密。Synapse 是参考 homeserver:原始实现,由 Matrix.org 基金会 用 Python 维护,每个规范功能首先在这里发布。

运行 Synapse homeserver,你的用户(alice:example.com、bob:example.com)可与 任何其他 Matrix 服务器上的用户聊天 —— 像电子邮件但用于聊天。桥将 Matrix 房间链接到 Telegram、Discord、Slack、WhatsApp、Signal、IRC 等,因此单个 Element 客户端可显示每次对话。

Pier 如何部署它

本模板在一个 Compose 栈中运行 Synapse 加专用 PostgreSQL 后端。Postgres 是 Synapse 唯一支持生产的数据库 —— SQLite 跟不上繁忙房间的联邦加入。

默认端口:8008(HTTP,在 Traefik 后)。你在 Pier 附加自定义域名,Traefik 处理 TLS。Synapse 需要 Matrix 服务器名与顶级域名上的 .well-known/matrix/server 文件匹配;在 Pier env 变量中配置或从单独的 Pier 服务提供。

首次启动后,通过 docker exec 使用 register_new_matrix_user 创建管理员 用户。然后将任何 Element 客户端指向你的 homeserver URL 以登录。

何时不要使用 Matrix Synapse

如果你只需要单组织封闭聊天(无联邦、无桥),更轻的替代品如 Mattermost 更易操作。如果你想要尖端规范功能但更小的服务器,对于个人/测试用途尝试 matrix-synapse-sqlite(本目录),或 Dendrite / Conduit 作为实验性轻量 homeserver。Synapse 仍是任何联邦繁重或桥繁重部署的正确答案。

核心功能

联邦设计

你的 homeserver 与开放网络上每个其他 Matrix 服务器通信。你域名上的用户可加入任何地方托管的房间,反之亦然 —— 像电子邮件,但用于聊天。

端到端加密

通过 Olm/Megolm Double Ratchet 的原生 E2EE。私信和私人房间使用每设备密钥加密;服务器从不看到明文。

桥接到一切

Matrix 桥将房间连接到 Telegram、Discord、Slack、WhatsApp、Signal、IRC、XMPP、Mattermost —— 在不强迫每个联系人迁移的情况下,在 Matrix 上运行你的团队聊天。

语音、视频和会议

通过 WebRTC 的 1 对 1 通话;通过 Element Call 或 Jitsi 桥的群组通话。使用 SFU 扩展到数十名参与者的会议。

PostgreSQL 后端

Synapse 唯一支持生产的数据库 —— SQLite 跟不上联邦流量。本模板将 Synapse 连线到专用 Postgres,让你跳过最常见的扩展陷阱。

开放治理

由 Matrix.org 基金会(非营利)维护规范。任何人都可运行 homeserver,任何人都可实现客户端。没有供应商控制协议。

应用场景

自托管团队聊天

用你的组织拥有的 homeserver 替换 Slack / Discord / Teams。Element web/移动/桌面客户端提供精致的 UX,不会失去数据主权。

社区 / 项目聊天

为开源项目、大学或 DAO 运行社区 Matrix 服务器。联邦意味着用户如果已有 Matrix 身份,可保留它。

高信任环境的安全消息

政府(法国、德国、瑞典)、国防承包商和医疗保健组织为无法批准 Slack/Teams 的 E2EE 消息部署 Matrix。

桥接团队工作空间

一个 Element 客户端显示你的 Matrix 房间 + 桥接的 Telegram、WhatsApp 和 Discord 频道。停止在四个聊天应用之间切换标签。

机器人平台和 ChatOps

Matrix 的开放 API 和机器人框架(matrix-bot-sdk、maubot)使自动化比围墙花园的替代品更简单。

代码示例

首个用户注册(管理员)bash
docker exec -it pier-synapse-synapse \
  register_new_matrix_user \
    -u alice \
    -p strongpassword \
    -a \
    -c /data/homeserver.yaml \
    http://localhost:8008
联邦测试bash
curl https://federationtester.matrix.org/api/report?server_name=matrix.example.com | jq .
发现 .well-known 文件bash
# /.well-known/matrix/server (端口 443 的 matrix.example.com)
{"m.server": "matrix.example.com:443"}

# /.well-known/matrix/client
{
  "m.homeserver": { "base_url": "https://matrix.example.com" },
  "m.identity_server": { "base_url": "https://vector.im" }
}
注册管理 API 调用bash
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"deactivated": true}' \
  https://matrix.example.com/_synapse/admin/v1/deactivate/@spammer:matrix.example.com

对比

vs Element(客户端)+ Synapse(服务器)Element 是最流行的 Matrix 客户端;Synapse 是参考服务器。本模板提供服务器。Element 客户端(web、iOS、Android、桌面)从任何地方连接 —— 将它们指向你的 homeserver URL。
vs Dendrite、ConduitGo 和 Rust 的替代 Matrix homeserver。比 Synapse 轻量但功能不太完整。Synapse 仍是联邦繁重部署的生产默认。
vs Mattermost / Rocket.Chat封闭联邦(每个组织一个服务器)。更易于操作但无跨组织联邦、无 Matrix 桥、DM 中默认无 E2EE。需要开放联邦时选 Matrix;单组织封闭部署选 Mattermost/Rocket。
vs Slack / Discord / Teams仅 SaaS、无自托管、无 E2EE、围墙花园。Matrix 是开放替代 —— 联邦、自托管、DM 中默认 E2EE。

常见问题

为什么用 PostgreSQL 而不是 SQLite?
SQLite 对小型单用户 homeservers 还行,但跟不上繁忙房间(matrix.org HQ、大型公共社区)的联邦加入。生产 Synapse 需要 Postgres。本模板为你连线。
我需要什么域名配置?
Synapse 需要一个 Matrix 服务器名(例如 matrix.example.com),它与 example.com 上提供的 .well-known/matrix/server 文件匹配。服务器名是永久的 —— 你无法在不重新注册每个用户的情况下更改它。
如何禁用开放注册?
在 homeserver.yaml 中将 enable_registration 设置为 false(默认)。使用注册秘密通过管理脚本创建用户,或设置注册令牌系统。
语音和视频呢?
1 对 1 通话开箱即用(WebRTC)。对于群组通话和会议,运行 Element Call 或将 Synapse 与 Jitsi 实例配对。严格 NAT 后的用户需要 TURN 服务器(coturn)。
单个 Synapse 能多大?
在带 workers 的单节点上 Synapse 良好地纵向扩展到数千名活跃用户。超出此范围,巨大房间(10k+ 成员)上的联邦加入是瓶颈 —— 对于非常小或非常实验的部署考虑替代 homeserver(Dendrite/Conduit)。
桥接到其他平台?
matrix.org 维护 Telegram(mautrix-telegram)、Discord、WhatsApp、Signal、IRC、XMPP、Slack 等的桥。每个桥是通过 appservice API 与 Synapse 通信的单独服务。
备份?
备份 PostgreSQL 数据库(pg_dump)加 Synapse 媒体存储卷。将两者还原到具有相同域名的新服务器上以使工作 homeserver 重新上线。

相关服务

在你的 VPS 上部署

Matrix Synapse 是 Matrix 协议的参考 homeserver 实现 —— 一个开放的、去中心化的联邦标准,用于实时聊天、语音、视频和端到端加密消息。本模板提供 Synapse 加 PostgreSQL 后端(Synapse 唯一支持生产的数据库),预连线以便联邦和大房间从第一天起就能正确运行。

部署此服务 →