VPS 搭建 Matrix Synapse（2026）：Docker、联邦、Element、HTTPS 与备份

Matrix Synapse 是 Matrix 协议的 homeserver 实现，适合把团队聊天、私有社区和跨服务器联邦通信掌握在自己手里。它和普通的即时通讯网页应用不同：除了登录页面，还要正确处理 Server Name、事件签名、联邦发现、媒体存储、邮件和备份。

本文以 Ubuntu 24.04 LTS VPS 为例，使用官方 matrixdotorg/synapse Docker 镜像部署 Synapse，并通过 Caddy 反向代理提供 HTTPS。示例覆盖 PostgreSQL、Element 客户端、联邦端口、/.well-known、管理员账号、TURN、升级和恢复。Synapse 官方文档指出 Server Name 在安装后不能更改，因此域名规划必须在第一步完成。

先确定架构和 VPS 配置

Server Name 不能随便改

Matrix 用户 ID 的格式是 @user:server.name，其中 server.name 就是 homeserver 的 Server Name。它不是简单的网页域名别名，写入数据库和事件签名后不能迁移修改。

常见规划方式有两种：

方案	示例	适合情况
主域名作为 Server Name	`example.com`	希望用户使用 `@alice:example.com`
子域名作为 Server Name	`matrix.example.com`	不影响主站，部署简单

如果选择 example.com，可以把客户端访问地址放在 matrix.example.com，再用 /.well-known/matrix/client 告诉 Element 实际 homeserver 地址。想降低复杂度时，直接把 matrix.example.com 同时作为 Server Name 和访问域名更稳妥。

配置建议

使用规模	建议配置	说明
个人测试	2 核、2 GB、30 GB SSD	可用 SQLite 验证流程，不适合公开运营
小型团队	2-4 核、4 GB、60 GB NVMe	PostgreSQL、媒体和备份分开规划
公开社区	4 核以上、8 GB+、100 GB+ NVMe	预留媒体、搜索、缩略图和联邦流量

Synapse 的媒体文件增长往往比数据库更快。不要只按容器镜像大小购买磁盘，还要计算上传图片、缩略图、远端联邦媒体、PostgreSQL WAL、日志和异地备份。可以先参考 VPS 配置选择指南，再根据用户数和媒体保留周期估算容量。

安装前准备

准备一台全新的 64 位 Ubuntu VPS、root 或 sudo 权限、一个固定公网 IP，以及已经规划好的域名。先设置 DNS：

matrix.example.com    A    203.0.113.10
element.example.com   A    203.0.113.10
~~

如果 Server Name 使用主域名，还需要保留主域名的 `/.well-known` 路径。检查解析、端口和资源：

~~~bash
dig +short matrix.example.com A
curl -4 ifconfig.me
sudo ss -lntup
free -h
df -h

云防火墙和 UFW 可以先开放：

端口	用途	建议
22/TCP	SSH 管理	只允许管理 IP 更安全
80/TCP	ACME HTTP-01 和跳转	公网开放
443/TCP	客户端 HTTPS、联邦入口	公网开放
8448/TCP	传统 Matrix 联邦端口	使用 443 代理时可按架构决定
3478/TCP、3478/UDP	coturn TURN	需要语音视频时开放
49152-65535/UDP	TURN relay	按 coturn 端口范围开放

PostgreSQL、Redis（如另行部署）和 Synapse 管理接口不要暴露公网。若 VPS 上已有 Nginx、Apache、Caddy 或面板，先确认 80/443 没有冲突。

用官方 Docker 镜像生成配置

官方镜像目前使用 matrixdotorg/synapse:latest 标签，生产环境应在验证后固定到明确版本。本文写作时官方最新 Release 为 v1.159.0，上线前请查看 Synapse Releases 再决定是否升级。

创建持久化目录并生成配置：

sudo mkdir -p /opt/synapse/data
sudo chown -R 991:991 /opt/synapse/data
sudo docker run --rm \
  --mount type=bind,src=/opt/synapse/data,dst=/data \
  -e SYNAPSE_SERVER_NAME=matrix.example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:v1.159.0 generate

官方 Docker 文档说明，generate 会在 /data 中生成 homeserver.yaml、签名密钥和日志配置。Server Name 只在生成时确定；如果要使用 example.com 作为用户域名，应将环境变量改成 SYNAPSE_SERVER_NAME=example.com，不要先用子域名测试后再改回主域名。

检查生成的配置：

sudo grep -E '^(server_name|public_baseurl|listeners|database):' /opt/synapse/data/homeserver.yaml
sudo chmod 750 /opt/synapse/data

PostgreSQL：生产环境不要长期用 SQLite

SQLite 适合个人试用和迁移演练，但公开服务建议使用 PostgreSQL。可以在同一台 VPS 使用 Docker Compose 管理数据库和 Synapse，数据库只加入内部网络：

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: change-this-long-password
      POSTGRES_DB: synapse
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks: [synapse-internal]

  synapse:
    image: matrixdotorg/synapse:v1.159.0
    restart: unless-stopped
    depends_on: [postgres]
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"
    networks: [synapse-internal]

networks:
  synapse-internal:
    driver: bridge

在 homeserver.yaml 中配置 PostgreSQL 的数据库名、用户、密码和服务名 postgres。不要把密码提交到 Git，也不要把 5432 映射到公网。切换数据库前先做完整备份，并按照官方 PostgreSQL 配置文档检查字符集和迁移要求。

启动 Synapse 和检查日志

完成数据库配置后启动：

cd /opt/synapse
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=200 synapse
curl -fsS http://127.0.0.1:8008/_matrix/federation/v1/version

8008 只绑定到回环地址，公网请求由反向代理转发。官方镜像不再根据环境变量自动生成配置，必须先存在有效的 homeserver.yaml，否则容器会直接退出。遇到 permission denied 时，检查宿主机目录是否允许容器 UID 991 读取配置并写入 media、logs 等目录。

Caddy 反向代理和 HTTPS

Synapse 的客户端 API、媒体下载和联邦请求都应该使用有效 HTTPS。Caddy 示例：

matrix.example.com {
    reverse_proxy 127.0.0.1:8008
}

启动 Caddy 后检查：

curl -I https://matrix.example.com/_matrix/client/versions
curl -fsS https://matrix.example.com/_matrix/federation/v1/version

在 homeserver.yaml 中确认 public_baseurl 与真实 HTTPS 地址一致，例如 https://matrix.example.com/。不要在 Cloudflare Flexible 模式下代理，使用 Full (strict) 并确保源站证书有效。若已经有站点使用 Caddy，可按域名拆分站点块，但不要让另一个代理吞掉 Matrix 的长连接和请求头。

配置 Matrix 联邦和 well-known

联邦让不同 homeserver 之间交换房间事件。最容易出错的是 Server Name、证书和端口发现。

直接使用 8448

如果 Server Name 是 matrix.example.com，可以让该域名的 8448/TCP 直接进入 Synapse 的 TLS 监听器。云防火墙、Caddy 或 Nginx 必须允许 8448，证书中的域名也要匹配。

使用 443 和 `/.well-known/matrix/server`

更常见的做法是用 443 接收 HTTPS，然后在 Server Name 所在域名发布：

{
  "m.server": "matrix.example.com:443"
}

如果 Server Name 与访问域名不同，例如 Server Name 是 example.com，需要在主站提供：

https://example.com/.well-known/matrix/server
~~

响应头至少包含 `Content-Type: application/json`，响应体为上面的 JSON。Element 客户端还可以使用：

~~~json
{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  }
}

对应路径是 /.well-known/matrix/client。部署后用 curl -i 检查状态码、Content-Type、JSON 格式和证书链。联邦测试可使用 Matrix Federation Tester；不要只以本地 API 返回 200 判断联邦已经正常。

注册管理员和 Element 客户端

首次创建管理员需要在 homeserver.yaml 临时设置 registration_shared_secret，然后重启容器：

sudo docker compose restart synapse
sudo docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

创建完成后删除 registration_shared_secret 并再次重启。这个密钥只用于注册脚本，不应长期保留，也不要复制到工单或公开日志中。

Element Web 可以单独部署在 element.example.com，也可以先使用官方托管客户端登录自定义 homeserver。自建 Element Web 时配置 config.json：

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com",
      "server_name": "matrix.example.com"
    }
  }
}

先用两个普通账号测试登录、建房间、上传媒体、邀请外部 homeserver 用户和注销设备，再开放注册。公开注册前还应配置验证码、速率限制和邮件验证，避免被机器人批量注册。

SMTP、媒体和 TURN

SMTP

邮件用于密码重置、注册验证和通知。使用事务邮件服务商的 587/TLS 端口，并在 DNS 中配置 SPF、DKIM 和 DMARC。邮件密码放在受限配置文件或密钥管理系统中，不要写入文章示例以外的真实凭据。

媒体保留

media_store_path 所在目录会持续增长。可以在 Synapse 配置中设置媒体保留策略，并通过磁盘告警监控目录大小。不要直接删除 media_store 下的文件，否则数据库中仍可能存在失效引用。

TURN 语音视频

官方 Synapse Docker 镜像不包含 TURN 服务。需要语音视频或受限网络兼容时，另行部署 coturn，设置静态认证或短期凭据，并在 turn_uris、turn_shared_secret 等配置项中按官方文档配置。开放 TURN relay 端口后要限制滥用，静态用户名密码会暴露在客户端，生产环境优先使用短期凭据。

备份、升级和恢复

至少备份以下内容：

/opt/synapse/data/homeserver.yaml
/opt/synapse/data/*.signing.key
/opt/synapse/data/media_store/
/opt/synapse/postgres/
/opt/synapse/compose.yaml

数据库要使用 PostgreSQL 原生备份或一致性快照，配置和签名密钥必须加密异地保存。可以结合 VPS 备份恢复演练怎么做实际演练：新建临时 VPS，恢复数据库和 /data，再用 Element 登录和联邦测试验证结果。

升级前记录版本、创建 VPS 快照和数据库备份：

sudo docker compose exec synapse python -m synapse.app.homeserver --version
sudo docker compose pull synapse
sudo docker compose up -d synapse
sudo docker compose logs --tail=200 synapse

生产环境不要长期使用 latest。先阅读 Release Notes，在预发布或临时 VPS 验证数据库迁移，再把镜像标签更新到目标版本。升级后检查登录、媒体、邮件、联邦和后台任务，而不是只看容器状态为 Up。

常见故障排查

容器启动后立即退出

sudo docker compose logs synapse
sudo ls -l /opt/synapse/data/homeserver.yaml
sudo docker compose config

重点检查 homeserver.yaml 是否存在、YAML 缩进、数据库连接、容器 UID 权限和签名密钥是否可读。

客户端能登录但联邦失败

检查 Server Name 的 DNS、8448/TCP 或 443 端口、/.well-known/matrix/server、证书 SAN 和反向代理请求头。若使用 Cloudflare，确认代理方式不会拦截联邦请求，并从外部网络运行 Federation Tester。

Element 显示 homeserver 不可用

curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://example.com/.well-known/matrix/client

确认 public_baseurl、CORS、JSON Content-Type 和证书链；不要把浏览器访问 Element Web 的域名误当成 homeserver 地址。

上传媒体失败或磁盘暴涨

df -h
sudo du -sh /opt/synapse/data/media_store
sudo docker system df

先清理无用 Docker 镜像和日志，再按保留策略处理媒体。不要在没有数据库记录和备份的情况下手工删除媒体文件。

语音视频没有声音或只能一对一

检查 coturn 是否可达、relay 端口范围是否放行、VPS 公网 IP 是否正确，以及短期凭据是否过期。TURN 只解决 NAT 穿透，不会替代足够的出口带宽。

上线检查清单

Matrix Synapse 的难点不是把一个容器启动起来，而是让身份域名、联邦发现、数据库、媒体、邮件和备份形成完整闭环。先用 2 核 4GB VPS 和独立子域名完成验证，再根据媒体增长和联邦流量扩容，通常比一开始堆复杂组件更容易维护。

官方资料

先确定架构和 VPS 配置

Server Name 不能随便改

常见规划方式有两种：

方案	示例	适合情况
主域名作为 Server Name	`example.com`	希望用户使用 `@alice:example.com`
子域名作为 Server Name	`matrix.example.com`	不影响主站，部署简单

配置建议

使用规模	建议配置	说明
个人测试	2 核、2 GB、30 GB SSD	可用 SQLite 验证流程，不适合公开运营
小型团队	2-4 核、4 GB、60 GB NVMe	PostgreSQL、媒体和备份分开规划
公开社区	4 核以上、8 GB+、100 GB+ NVMe	预留媒体、搜索、缩略图和联邦流量

安装前准备

准备一台全新的 64 位 Ubuntu VPS、root 或 sudo 权限、一个固定公网 IP，以及已经规划好的域名。先设置 DNS：

matrix.example.com    A    203.0.113.10
element.example.com   A    203.0.113.10
~~

如果 Server Name 使用主域名，还需要保留主域名的 `/.well-known` 路径。检查解析、端口和资源：

~~~bash
dig +short matrix.example.com A
curl -4 ifconfig.me
sudo ss -lntup
free -h
df -h

云防火墙和 UFW 可以先开放：

端口	用途	建议
22/TCP	SSH 管理	只允许管理 IP 更安全
80/TCP	ACME HTTP-01 和跳转	公网开放
443/TCP	客户端 HTTPS、联邦入口	公网开放
8448/TCP	传统 Matrix 联邦端口	使用 443 代理时可按架构决定
3478/TCP、3478/UDP	coturn TURN	需要语音视频时开放
49152-65535/UDP	TURN relay	按 coturn 端口范围开放

PostgreSQL、Redis（如另行部署）和 Synapse 管理接口不要暴露公网。若 VPS 上已有 Nginx、Apache、Caddy 或面板，先确认 80/443 没有冲突。

用官方 Docker 镜像生成配置

创建持久化目录并生成配置：

sudo mkdir -p /opt/synapse/data
sudo chown -R 991:991 /opt/synapse/data
sudo docker run --rm \
  --mount type=bind,src=/opt/synapse/data,dst=/data \
  -e SYNAPSE_SERVER_NAME=matrix.example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:v1.159.0 generate

检查生成的配置：

sudo grep -E '^(server_name|public_baseurl|listeners|database):' /opt/synapse/data/homeserver.yaml
sudo chmod 750 /opt/synapse/data

PostgreSQL：生产环境不要长期用 SQLite

SQLite 适合个人试用和迁移演练，但公开服务建议使用 PostgreSQL。可以在同一台 VPS 使用 Docker Compose 管理数据库和 Synapse，数据库只加入内部网络：

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: change-this-long-password
      POSTGRES_DB: synapse
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks: [synapse-internal]

  synapse:
    image: matrixdotorg/synapse:v1.159.0
    restart: unless-stopped
    depends_on: [postgres]
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"
    networks: [synapse-internal]

networks:
  synapse-internal:
    driver: bridge

启动 Synapse 和检查日志

完成数据库配置后启动：

cd /opt/synapse
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=200 synapse
curl -fsS http://127.0.0.1:8008/_matrix/federation/v1/version

Caddy 反向代理和 HTTPS

Synapse 的客户端 API、媒体下载和联邦请求都应该使用有效 HTTPS。Caddy 示例：

matrix.example.com {
    reverse_proxy 127.0.0.1:8008
}

启动 Caddy 后检查：

curl -I https://matrix.example.com/_matrix/client/versions
curl -fsS https://matrix.example.com/_matrix/federation/v1/version

配置 Matrix 联邦和 well-known

联邦让不同 homeserver 之间交换房间事件。最容易出错的是 Server Name、证书和端口发现。

直接使用 8448

使用 443 和 `/.well-known/matrix/server`

更常见的做法是用 443 接收 HTTPS，然后在 Server Name 所在域名发布：

{
  "m.server": "matrix.example.com:443"
}

如果 Server Name 与访问域名不同，例如 Server Name 是 example.com，需要在主站提供：

https://example.com/.well-known/matrix/server
~~

响应头至少包含 `Content-Type: application/json`，响应体为上面的 JSON。Element 客户端还可以使用：

~~~json
{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  }
}

注册管理员和 Element 客户端

首次创建管理员需要在 homeserver.yaml 临时设置 registration_shared_secret，然后重启容器：

sudo docker compose restart synapse
sudo docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

创建完成后删除 registration_shared_secret 并再次重启。这个密钥只用于注册脚本，不应长期保留，也不要复制到工单或公开日志中。

Element Web 可以单独部署在 element.example.com，也可以先使用官方托管客户端登录自定义 homeserver。自建 Element Web 时配置 config.json：

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com",
      "server_name": "matrix.example.com"
    }
  }
}

SMTP、媒体和 TURN

SMTP

媒体保留

TURN 语音视频

备份、升级和恢复

至少备份以下内容：

/opt/synapse/data/homeserver.yaml
/opt/synapse/data/*.signing.key
/opt/synapse/data/media_store/
/opt/synapse/postgres/
/opt/synapse/compose.yaml

升级前记录版本、创建 VPS 快照和数据库备份：

sudo docker compose exec synapse python -m synapse.app.homeserver --version
sudo docker compose pull synapse
sudo docker compose up -d synapse
sudo docker compose logs --tail=200 synapse

常见故障排查

容器启动后立即退出

sudo docker compose logs synapse
sudo ls -l /opt/synapse/data/homeserver.yaml
sudo docker compose config

重点检查 homeserver.yaml 是否存在、YAML 缩进、数据库连接、容器 UID 权限和签名密钥是否可读。

客户端能登录但联邦失败

Element 显示 homeserver 不可用

curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://example.com/.well-known/matrix/client

确认 public_baseurl、CORS、JSON Content-Type 和证书链；不要把浏览器访问 Element Web 的域名误当成 homeserver 地址。

上传媒体失败或磁盘暴涨

df -h
sudo du -sh /opt/synapse/data/media_store
sudo docker system df

先清理无用 Docker 镜像和日志，再按保留策略处理媒体。不要在没有数据库记录和备份的情况下手工删除媒体文件。

语音视频没有声音或只能一对一

检查 coturn 是否可达、relay 端口范围是否放行、VPS 公网 IP 是否正确，以及短期凭据是否过期。TURN 只解决 NAT 穿透，不会替代足够的出口带宽。

先确定架构和 VPS 配置

Server Name 不能随便改

配置建议

安装前准备

用官方 Docker 镜像生成配置

PostgreSQL：生产环境不要长期用 SQLite

启动 Synapse 和检查日志

Caddy 反向代理和 HTTPS

配置 Matrix 联邦和 well-known

直接使用 8448

使用 443 和 /.well-known/matrix/server

注册管理员和 Element 客户端

SMTP、媒体和 TURN

SMTP

媒体保留

TURN 语音视频

备份、升级和恢复

常见故障排查

容器启动后立即退出

客户端能登录但联邦失败

Element 显示 homeserver 不可用

上传媒体失败或磁盘暴涨

语音视频没有声音或只能一对一

上线检查清单

官方资料

Loading...

先确定架构和 VPS 配置

Server Name 不能随便改

配置建议

安装前准备

用官方 Docker 镜像生成配置

PostgreSQL：生产环境不要长期用 SQLite

启动 Synapse 和检查日志

Caddy 反向代理和 HTTPS

配置 Matrix 联邦和 well-known

直接使用 8448

使用 443 和 /.well-known/matrix/server

注册管理员和 Element 客户端

SMTP、媒体和 TURN

SMTP

媒体保留

TURN 语音视频

备份、升级和恢复

常见故障排查

容器启动后立即退出

客户端能登录但联邦失败

Element 显示 homeserver 不可用

上传媒体失败或磁盘暴涨

语音视频没有声音或只能一对一

上线检查清单

官方资料

使用 443 和 `/.well-known/matrix/server`

使用 443 和 `/.well-known/matrix/server`