先分清:Matrix 不是又一个聊天软件,而是一套联邦协议
自建聊天这件事,前面已经写过 Rocket.Chat 篇:一台服务器、一个团队、装好就能用,数据全在自己手里。但 Rocket.Chat 有个天然边界——它是一座孤岛。你服务器上的用户,只能和同一台服务器上的人聊天,想联系另一台 Rocket.Chat 上的人,做不到。
Matrix 走的是完全不同的路线。它不是某个软件,而是一套开放的去中心化通信协议,思路和电子邮件一模一样:Gmail 的用户能给 Outlook 的用户发邮件,不需要他们在同一家服务商注册。Matrix 里也一样:
- 你的用户 ID 长这样:
@anex:example.com,后半段就是你的服务器域名,天然自带「户口所在地」。 - 房间是分布式的:一个房间的数据会同步到所有参与者所在的服务器上,任何一台服务器下线,房间在其他服务器上照常存在。
- 任何人按协议实现自己的服务器,都能和全世界其他 Matrix 服务器互通,这个互通网络就叫联邦(Federation)。
Synapse 是 Matrix 官方团队用 Python 写的参考服务器实现,生态最成熟、文档最全,本篇就用它。
| 维度 | Rocket.Chat | Matrix(Synapse) |
|---|---|---|
| 定位 | 团队内部聊天(单机) | 联邦化通信网络的一个节点 |
| 用户 ID | 本服务器内唯一 | @用户:域名,全网唯一 |
| 跨服务器互通 | 不支持 | 协议原生支持(联邦) |
| 客户端 | 官方 App | Element、FluffyChat 等多款可选 |
| 数据模型 | 全在本机数据库 | 房间状态在参与服务器间复制 |
| 部署复杂度 | 低 | 中高,域名与联邦配置是门槛 |
| 适合场景 | 公司/小团队内部沟通 | 想拥有全网可达的聊天身份、长期主义 |
一句话结论:Rocket.Chat 是「自建一个聊天室」,Matrix 是「自建一个聊天世界的入口」——你的域名就是你在整个网络里的身份证。
本篇主线:先把域名设计讲透 → Compose 部署 Synapse+PostgreSQL → 配好反向代理与 .well-known 委派 → 建管理员账号 → 部署 Element Web 客户端 → 联邦互通测试 → 媒体保留与备份。
动手前的大坑:域名设计,定下就不能改
Matrix 部署里 90% 的翻车都不是装不上,而是域名没想清楚。核心就一条:
server_name(服务器名)在生成配置的那一刻就被写死进数据库和签名密钥里,部署之后永远不能更改。想改名只能推倒重建,所有用户 ID、房间别名全部作废。所以动手前先把下面三件事定死:
第一,服务器名用哪个域名。 假设你的主域名是 example.com,你希望用户 ID 是 @anex:example.com 这种短域名,那 server_name 就填 example.com。Synapse 本身可以装在子域名 matrix.example.com 上,通过 .well-known 委派把联邦流量指过去——这是官方推荐的标准做法,用户 ID 保持简洁,服务部署又不污染主域名。
第二,联邦流量怎么进来。 Matrix 服务器之间通信默认走 8448 端口:别的服务器找 example.com 的 Matrix 服务时,先查 DNS 里的委派信息,再决定连哪里。两种正规解法:
- .well-known 委派(本篇方案):在
https://example.com/.well-known/matrix/server放一个 JSON,声明{"m.server": "matrix.example.com:443"},联邦流量就走 443 经反向代理进来,不用额外开端口,证书也好管理。 - 直连 8448:让 Synapse 自己监听 8448 并配好 TLS,或者反代 8448。证书、续期、防火墙都要多管一摊事,没必要。
第三,想清楚注册策略。 默认关掉公开注册,只用管理员命令建号。原因写在排障一节里——开放注册的 Matrix 服务器是垃圾账号和滥用内容的重灾区。
域名规划定稿后,DNS 先加好两条记录:
| 记录 | 类型 | 值 | 用途 |
|---|---|---|---|
matrix.example.com | A | 你的服务器 IP | Synapse 与 Element 的访问域名 |
example.com | 已有 | 主站 IP(可与上不同) | 只需要能托管 /.well-known/ 两个静态文件 |
WARNING如果主域名
example.com本身就架在这台服务器上(比如博客也在同一台机),.well-known 文件直接放主站根目录即可;如果主域名在别处(比如托管在静态平台),要确认那个平台能让你自定义.well-known/matrix/路径的文件,否则就只能退回「server_name 直接用 matrix.example.com」的方案,用户 ID 会变长,但功能不受影响。
部署:Synapse + PostgreSQL 的 Compose 编排
目录规划:所有数据放在 /opt/matrix/ 下,Synapse 的配置、媒体、签名密钥都在 synapse-data/ 里,数据库走独立容器。
先生成初始配置。Synapse 的镜像提供 generate 命令,一次性把 homeserver.yaml 和签名密钥写进数据目录:
mkdir -p /opt/matrix/synapse-datacd /opt/matrix
docker run -it --rm \ -v /opt/matrix/synapse-data:/data \ -e SYNAPSE_SERVER_NAME=example.com \ -e SYNAPSE_REPORT_STATS=no \ matrixdotorg/synapse:latest generate注意 SYNAPSE_SERVER_NAME 填的是服务器名 example.com,不是部署域名 matrix.example.com——这是全篇最容易填错的一个地方,填错了整套重来。
然后写 docker-compose.yml:
services: synapse: image: matrixdotorg/synapse:latest container_name: synapse restart: unless-stopped environment: - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml volumes: - ./synapse-data:/data ports: - "127.0.0.1:8008:8008" depends_on: - db
db: image: postgres:16-alpine container_name: synapse-db restart: unless-stopped environment: - POSTGRES_USER=synapse - POSTGRES_PASSWORD=换成你的强密码 - POSTGRES_DB=synapse - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C volumes: - ./pgdata:/var/lib/postgresql/data两个细节:
- Synapse 端口只绑
127.0.0.1,公网流量统一从反向代理进来,和本系列一贯的做法一致。数据库更是绝对不要把 PostgreSQL 的 5432 端口映射到公网,它只和 Synapse 在 Compose 内部网络里通信,连宿主机都不用暴露。 POSTGRES_INITDB_ARGS里的排序规则必须是C。Synapse 对数据库的 collation 有硬性要求,用默认语言环境建库,启动时它会直接报错拒绝运行——这是新手最常见的第二个坑。
接着改 synapse-data/homeserver.yaml,把 SQLite 换成 PostgreSQL 并定下关键开关。找到并修改这几段:
server_name: "example.com"public_baseurl: "https://matrix.example.com/"
listeners: - port: 8008 tls: false type: http x_forwarded: true resources: - names: [client, federation] compress: false
database: name: psycopg2 args: user: synapse password: "换成你的强密码" database: synapse host: db cp_min: 5 cp_max: 10
enable_registration: falseregistration_shared_secret: "用 openssl rand -hex 32 生成一串"
media_store_path: /data/media_storemax_upload_size: 100M要点:x_forwarded: true 必须开,因为 Synapse 在反代后面,要靠 X-Forwarded-For 拿到真实客户端 IP,否则限流和日志全记成反代的地址;enable_registration: false 先关死,后面用共享密钥建管理员号。
启动:
cd /opt/matrix && docker compose up -ddocker compose logs -f synapse日志里出现 SynapseSite starting at tcp:8008 且没有数据库报错,第一关就过了。先别急着配客户端,下一节把入口打通。
反向代理与 .well-known:联邦能不能通,全看这一节
你如果已经按 Nginx Proxy Manager 篇搭好了统一入口,思路是一样的:给 matrix.example.com 建一个反代主机,转发到 127.0.0.1:8008 并申请好 HTTPS 证书。这里把等价的原生 Nginx 配置写全,方便对照检查每一项:
server { listen 443 ssl; listen [::]:443 ssl; server_name matrix.example.com;
# 证书路径按你的实际情况改 ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;
# 必须大于 homeserver.yaml 里的 max_upload_size,否则大文件上传会被 Nginx 先拦下 client_max_body_size 110M;
location / { proxy_pass http://127.0.0.1:8008; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; # 同步(长轮询)接口需要长连接,把超时放宽 proxy_read_timeout 600s; }}然后是委派文件。在主域名 example.com 的站点根目录下建两个静态文件。
/.well-known/matrix/server(注意:没有扩展名,内容是纯 JSON):
{ "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" }}这两个文件的分工:server 是给其他服务器看的,告诉联邦「找 example.com 的 Matrix 服务请去 matrix.example.com 的 443」;client 是给客户端看的,用户在登录框里只输入 @anex:example.com,Element 就靠它知道该连哪台服务器。
自查命令,两个地址都必须能匿名访问、返回 200 和正确 JSON,且不能有跳转把 .well-known 吞掉:
curl -s https://example.com/.well-known/matrix/servercurl -s https://example.com/.well-known/matrix/clientcurl -s https://matrix.example.com/_matrix/client/versions最后一条能返回一串版本号 JSON,说明 Synapse 本身和反代都通了。
联邦的本质就是「发现」:别人能通过 .well-known 找到你、你的证书有效、/_matrix 接口可达,联邦就通了大半,剩下的多半是细节问题。
建管理员账号
注册关着,建号走 Synapse 自带命令,它会用 registration_shared_secret 做校验:
docker exec -it synapse register_new_matrix_user \ -c /data/homeserver.yaml http://localhost:8008交互式地输入用户名、密码,并回答 Make admin? [no] 时填 yes,第一个管理员就建好了,你的用户 ID 就是 @anex:example.com(假设用户名填 anex)。普通用户以后也用同一条命令建(admin 回答 no),或者临时开注册、建完立刻关。
验证一下管理员能登录并拿到 token:
curl -s -X POST https://matrix.example.com/_matrix/client/v3/login \ -H 'Content-Type: application/json' \ -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"@anex:example.com"},"password":"你的密码"}'返回里有 access_token 字段即成功。这个 token 相当于账号的完全控制权,别外泄。
Element Web 客户端:给用户一个网页入口
Element 是 Matrix 生态的官方客户端。部署一个自己的 Element Web,用户打开浏览器就能用,不用装 App,而且服务器地址预填好,登录只需输 ID 和密码。
element: image: vectorim/element-web:latest container_name: element restart: unless-stopped volumes: - ./element-config.json:/app/config.json:ro ports: - "127.0.0.1:8081:80"把这个服务加进同一个 Compose 文件。element-config.json 内容:
{ "default_server_config": { "m.homeserver": { "base_url": "https://matrix.example.com", "server_name": "example.com" } }, "brand": "我的 Matrix", "disable_guests": true, "disable_custom_urls": false}再给 Element 单独配一个反代站点,比如 chat.example.com 转发到 127.0.0.1:8081 并上 HTTPS。打开后登录页默认就指向你的服务器。手机端则直接装 Element 或 FluffyChat,登录时输入完整的 @anex:example.com,客户端会靠 .well-known/matrix/client 自动找到 matrix.example.com——这也是前面那个文件必须配对的原因。
联邦测试:确认全世界能找到你
部署完成不等于联邦通了,按这个顺序自查:
- 官方联邦测试器:打开
https://federationtester.matrix.org/,输入example.com,它会完整走一遍「查 .well-known → 连目标服务器 → 验 TLS 证书 → 调联邦接口」的流程,并给出每一步的结果。这是最权威的一票。 - 证书检查:测试器对证书很严格,自签或过期会直接判联邦失败。用 Let’s Encrypt 的证书并确认自动续期在跑。
- 真实互通验证:用你的账号去加入一个大型公共房间(比如
#matrix:matrix.org),能加载出其他服务器用户发的消息,再用公共服务器上的测试账号(或让朋友在别的服务器上)给你发一条私信,能收到、能回复,联邦双向就实锤了。 - 看日志:
docker compose logs synapse | grep -i federation,联邦请求失败会在这里留下对端域名和错误原因。
媒体存储与保留策略:不设上限必爆盘
Synapse 把用户上传的图片、文件、以及从联邦同步过来的远程媒体缩略图,全都堆在 media_store_path 指向的目录里。聊天越活跃涨得越快,不配保留策略的 Matrix 服务器,磁盘被媒体文件吃满只是时间问题。
在 homeserver.yaml 里加上保留策略(改完重启 Synapse 生效):
media_retention: # 本地用户上传的媒体保留多久,本地媒体是你的核心数据,可以给长一点或不设 local_media_lifetime: 730d # 远程联邦媒体只是缓存,过期删掉不影响,需要时重新拉取 remote_media_lifetime: 30d
# URL 预览会把外链的缩略图也缓存下来,同样吃空间,群聊多时建议直接关url_preview_enabled: false已经涨起来的存量,可以用管理员 API 清理过期的远程缓存:
curl -s -X POST \ "https://matrix.example.com/_synapse/admin/v1/media/<server_name>/delete?before_ts=<毫秒时间戳>" \ -H "Authorization: Bearer <管理员 access_token>"更稳妥的日常做法是把媒体目录大小纳入监控(本系列的监控告警篇讲过思路),设个阈值,涨到警戒线先报警再处理,别等磁盘写满 Synapse 直接罢工。
备份:有一样东西丢了,服务器等于换了身份
按 备份与迁移篇的通用方法,Matrix 需要备三样:
# 1. 数据库docker exec synapse-db pg_dump -U synapse synapse | gzip > synapse-db-$(date +%F).sql.gz
# 2. 配置与密钥(homeserver.yaml、签名密钥都在这个目录里)# 3. 媒体文件tar -czf synapse-data-$(date +%F).tar.gz /opt/matrix/synapse-data其中 synapse-data 里的 example.com.signing.key(签名密钥)是重中之重:联邦里其他服务器靠它认你的身份,丢了它,你的服务器在全网眼里就「不是原来那台了」,房间成员关系和联邦信任全部要重建,实际效果约等于换域名重开。这一条也呼应 安全与访问控制篇的原则:密钥类文件备份要加密、要异地,别和本体放同一块盘。
常见问题与排障
1. 联邦连不上,测试器报错。
按链路顺序查:先 curl 两个 .well-known 文件,确认返回的是 JSON 本身而不是主站的 404 页面或重定向——很多主站框架(包括一些静态托管)会把无扩展名路径吞掉,这是最高频死因。再查委派目标 matrix.example.com:443 的证书是否覆盖该域名、是否过期。最后看 Synapse 日志里对端连接的具体报错。如果你的主域名实在托管不了 .well-known,备选方案是 DNS SRV 记录 _matrix-fed._tcp.example.com 指向 matrix.example.com 8448,但那就得把 8448 端口和它的证书一起管起来,优先级低于 .well-known。
2. Element 登录一直转圈。
九成是客户端侧发现失败:登录时输的 ID 里服务器名部分(example.com)对应的 .well-known/matrix/client 打不开或内容写错,Element 找不到 base_url 就无限重试。其次是 element-config.json 里 base_url 写成了内网地址或 http。浏览器开 F12 看网络面板,找 .well-known 和 /login 两个请求的状态码,定位最快。
3. 媒体文件涨太快。
先分清涨的是本地还是远程:du -sh synapse-data/media_store/local_content synapse-data/media_store/remote_content。远程涨得快是联邦大房间的缩略图缓存,开上面的 remote_media_lifetime 并清一次存量;本地涨得快多半是有人在传大文件,调小 max_upload_size,同时检查 url_preview_enabled 是不是开着在给每个外链存图。
4. 注册被滥用,一夜之间多出一堆垃圾账号。
说明注册被打开过或共享密钥泄漏。个人服务器就不要开放注册:确认 enable_registration: false、换掉 registration_shared_secret,用管理员 API 把陌生账号逐个停用(deactivate)。真有给朋友批量开号的需求,临时开启、建完立刻关闭,并全程盯着用户列表。
5. Synapse 越用越卡。
先看是不是数据库在裸奔:确认 homeserver.yaml 用的是 PostgreSQL 而不是默认的 SQLite(小规模自娱自乐之外 SQLite 必然拖后腿);再给服务器加内存,Synapse 是吃内存大户,1 核 1G 只够勉强启动,长期用建议 2G 起步;房间历史太多时,管理员 API 的 purge history 功能可以清理超大房间的旧状态。
小结
Matrix 这一篇的难点不在装,而在想清楚:server_name 定死不可改,所以域名设计要在部署之前完成;联邦靠 .well-known 发现,所以委派文件和证书就是服务器的「对外名片」;媒体和签名密钥决定这台服务器能活多久、丢没丢身份。把这三件事做对,Synapse+PostgreSQL+Element 这套组合就能长期稳定地跑下去,你的 @你:你的域名 从此是全网可达的、真正属于你自己的聊天身份。