3891 字
19 分钟
自建服务实战:Matrix(Synapse)搭建去中心化聊天服务器
2026-11-15

先分清:Matrix 不是又一个聊天软件,而是一套联邦协议#

自建聊天这件事,前面已经写过 Rocket.Chat 篇:一台服务器、一个团队、装好就能用,数据全在自己手里。但 Rocket.Chat 有个天然边界——它是一座孤岛。你服务器上的用户,只能和同一台服务器上的人聊天,想联系另一台 Rocket.Chat 上的人,做不到。

Matrix 走的是完全不同的路线。它不是某个软件,而是一套开放的去中心化通信协议,思路和电子邮件一模一样:Gmail 的用户能给 Outlook 的用户发邮件,不需要他们在同一家服务商注册。Matrix 里也一样:

  • 你的用户 ID 长这样:@anex:example.com,后半段就是你的服务器域名,天然自带「户口所在地」。
  • 房间是分布式的:一个房间的数据会同步到所有参与者所在的服务器上,任何一台服务器下线,房间在其他服务器上照常存在。
  • 任何人按协议实现自己的服务器,都能和全世界其他 Matrix 服务器互通,这个互通网络就叫联邦(Federation)。

Synapse 是 Matrix 官方团队用 Python 写的参考服务器实现,生态最成熟、文档最全,本篇就用它。

维度Rocket.ChatMatrix(Synapse)
定位团队内部聊天(单机)联邦化通信网络的一个节点
用户 ID本服务器内唯一@用户:域名,全网唯一
跨服务器互通不支持协议原生支持(联邦)
客户端官方 AppElement、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.comA你的服务器 IPSynapse 与 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 和签名密钥写进数据目录:

Terminal window
mkdir -p /opt/matrix/synapse-data
cd /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: false
registration_shared_secret: "用 openssl rand -hex 32 生成一串"
media_store_path: /data/media_store
max_upload_size: 100M

要点:x_forwarded: true 必须开,因为 Synapse 在反代后面,要靠 X-Forwarded-For 拿到真实客户端 IP,否则限流和日志全记成反代的地址;enable_registration: false 先关死,后面用共享密钥建管理员号。

启动:

Terminal window
cd /opt/matrix && docker compose up -d
docker 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 吞掉:

Terminal window
curl -s https://example.com/.well-known/matrix/server
curl -s https://example.com/.well-known/matrix/client
curl -s https://matrix.example.com/_matrix/client/versions

最后一条能返回一串版本号 JSON,说明 Synapse 本身和反代都通了。

联邦的本质就是「发现」:别人能通过 .well-known 找到你、你的证书有效、/_matrix 接口可达,联邦就通了大半,剩下的多半是细节问题。

建管理员账号#

注册关着,建号走 Synapse 自带命令,它会用 registration_shared_secret 做校验:

Terminal window
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:

Terminal window
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——这也是前面那个文件必须配对的原因。

联邦测试:确认全世界能找到你#

部署完成不等于联邦通了,按这个顺序自查:

  1. 官方联邦测试器:打开 https://federationtester.matrix.org/,输入 example.com,它会完整走一遍「查 .well-known → 连目标服务器 → 验 TLS 证书 → 调联邦接口」的流程,并给出每一步的结果。这是最权威的一票。
  2. 证书检查:测试器对证书很严格,自签或过期会直接判联邦失败。用 Let’s Encrypt 的证书并确认自动续期在跑。
  3. 真实互通验证:用你的账号去加入一个大型公共房间(比如 #matrix:matrix.org),能加载出其他服务器用户发的消息,再用公共服务器上的测试账号(或让朋友在别的服务器上)给你发一条私信,能收到、能回复,联邦双向就实锤了。
  4. 看日志: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 清理过期的远程缓存:

Terminal window
curl -s -X POST \
"https://matrix.example.com/_synapse/admin/v1/media/<server_name>/delete?before_ts=<毫秒时间戳>" \
-H "Authorization: Bearer <管理员 access_token>"

更稳妥的日常做法是把媒体目录大小纳入监控(本系列的监控告警篇讲过思路),设个阈值,涨到警戒线先报警再处理,别等磁盘写满 Synapse 直接罢工。

备份:有一样东西丢了,服务器等于换了身份#

按 备份与迁移篇的通用方法,Matrix 需要备三样:

Terminal window
# 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 这套组合就能长期稳定地跑下去,你的 @你:你的域名 从此是全网可达的、真正属于你自己的聊天身份。

自建服务实战:Matrix(Synapse)搭建去中心化聊天服务器
https://www.anexns.cloudns.org/posts/selfhost-matrix-synapse/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0