Implantar Matrix Synapse em VPS (2026): Docker, federação, Element, HTTPS

O Matrix Synapse é uma implementação de homeserver do protocolo Matrix, adequada para manter nas próprias mãos o chat da equipe, comunidades privadas e a comunicação federada entre servidores. Ele é diferente de um aplicativo web comum de mensagens instantâneas: além da página de login, é preciso lidar corretamente com o Server Name, a assinatura de eventos, a descoberta de federação, o armazenamento de mídia, o e-mail e os backups.

Este artigo usa como exemplo uma VPS com Ubuntu 24.04 LTS, implanta o Synapse com a imagem oficial do Docker matrixdotorg/synapse e fornece HTTPS por meio de um proxy reverso Caddy. Os exemplos cobrem PostgreSQL, o cliente Element, as portas de federação, /.well-known, contas de administrador, TURN, atualizações e recuperação. A documentação oficial do Synapse afirma que o Server Name não pode ser alterado após a instalação, portanto o planejamento do domínio deve ser concluído na primeira etapa.

Primeiro defina a arquitetura e a configuração da VPS

O Server Name não pode ser alterado de qualquer jeito

O formato de um ID de usuário do Matrix é @user:server.name, em que server.name é o Server Name do homeserver. Ele não é um simples alias do domínio web; depois de gravado no banco de dados e nas assinaturas de eventos, não pode ser migrado nem alterado.

Há duas formas comuns de planejamento:

Abordagem	Exemplo	Indicado para
Domínio principal como Server Name	`example.com`	Que os usuários usem `@alice:example.com`
Subdomínio como Server Name	`matrix.example.com`	Não afeta o site principal, implantação mais simples

Se você escolher example.com, pode colocar o endereço de acesso do cliente em matrix.example.com e depois usar /.well-known/matrix/client para informar ao Element o endereço real do homeserver. Para reduzir a complexidade, é mais seguro usar matrix.example.com como Server Name e domínio de acesso ao mesmo tempo.

Recomendações de configuração

Escala de uso	Configuração recomendada	Observações
Teste pessoal	2 núcleos, 2 GB, 30 GB SSD	Pode usar SQLite para validar o fluxo, não indicado para operação pública
Equipe pequena	2-4 núcleos, 4 GB, 60 GB NVMe	Planeje PostgreSQL, mídia e backups separadamente
Comunidade pública	4+ núcleos, 8 GB+, 100 GB+ NVMe	Reserve capacidade para mídia, busca, miniaturas e tráfego de federação

Os arquivos de mídia do Synapse costumam crescer mais rápido que o banco de dados. Não compre disco apenas com base no tamanho da imagem do contêiner; calcule também as imagens enviadas, as miniaturas, a mídia federada remota, o WAL do PostgreSQL, os logs e os backups externos. Você pode consultar primeiro o guia de escolha de configuração de VPS e depois estimar a capacidade com base no número de usuários e no período de retenção de mídia.

Preparação antes da instalação

Prepare uma VPS nova com Ubuntu de 64 bits, permissões de root ou sudo, um IP público fixo e um domínio já planejado. Primeiro configure o 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
~~

Os cabeçalhos de resposta devem incluir pelo menos `Content-Type: application/json`, e o corpo da resposta é o JSON acima. O cliente Element também pode usar:

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

O caminho correspondente é /.well-known/matrix/client. Após a implantação, use curl -i para verificar o código de status, o Content-Type, o formato JSON e a cadeia de certificados. Para testar a federação, você pode usar o Matrix Federation Tester; não conclua que a federação está funcionando apenas porque a API local retorna 200.

Registrar o administrador e o cliente Element

Para criar o primeiro administrador, é preciso definir temporariamente registration_shared_secret em homeserver.yaml e depois reiniciar o contêiner:

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

Após a criação, exclua registration_shared_secret e reinicie novamente. Essa chave é usada apenas para o script de registro; não deve ser mantida por longo prazo nem copiada para tickets ou logs públicos.

O Element Web pode ser implantado separadamente em element.example.com, ou você pode primeiro usar o cliente hospedado oficial para entrar no seu homeserver personalizado. Ao auto-hospedar o Element Web, configure config.json:

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

Primeiro teste com duas contas comuns o login, a criação de salas, o upload de mídia, o convite de usuários de homeservers externos e o logout de dispositivos; depois abra o registro. Antes do registro público, você também deve configurar captcha, limites de taxa e verificação por e-mail para evitar registros em massa por bots.

SMTP, mídia e TURN

SMTP

O e-mail é usado para redefinição de senha, verificação de registro e notificações. Use a porta 587/TLS do provedor de e-mail transacional e configure SPF, DKIM e DMARC no DNS. Guarde a senha do e-mail em um arquivo de configuração restrito ou em um gerenciador de segredos; não escreva credenciais reais fora dos exemplos do artigo.

Retenção de mídia

O diretório onde fica media_store_path vai crescer continuamente. Você pode definir uma política de retenção de mídia na configuração do Synapse e monitorar o tamanho do diretório com alertas de disco. Não exclua diretamente os arquivos em media_store, pois podem restar referências inválidas no banco de dados.

TURN para voz e vídeo

A imagem oficial do Docker do Synapse não inclui um serviço TURN. Se precisar de voz e vídeo ou de compatibilidade com redes restritas, implante o coturn separadamente, configure autenticação estática ou credenciais de curta duração e configure-o conforme a documentação oficial em itens como turn_uris e turn_shared_secret. Depois de abrir as portas de relay do TURN, limite o abuso; nomes de usuário e senhas estáticos ficam expostos aos clientes, então em produção prefira credenciais de curta duração.

Backup, atualização e recuperação

Faça backup de pelo menos o seguinte:

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

Para o banco de dados, use backups nativos do PostgreSQL ou snapshots consistentes; a configuração e as chaves de assinatura devem ser armazenadas criptografadas fora do site. Você pode combinar com Como fazer um simulado de backup e recuperação de VPS para praticar de verdade: crie uma VPS temporária, restaure o banco de dados e /data e depois verifique o resultado entrando com o Element e executando um teste de federação.

Antes de atualizar, registre a versão, crie um snapshot da VPS e um backup do banco de dados:

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

Não use latest por longo prazo em produção. Leia primeiro as Release Notes, valide a migração do banco de dados em um ambiente de pré-produção ou em uma VPS temporária e depois atualize a tag da imagem para a versão de destino. Após a atualização, verifique login, mídia, e-mail, federação e tarefas em segundo plano, em vez de olhar apenas se o status do contêiner é Up.

Solução de problemas comuns

O contêiner encerra logo após iniciar

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

Verifique principalmente se homeserver.yaml existe, a indentação YAML, a conexão com o banco de dados, as permissões de UID do contêiner e se a chave de assinatura é legível.

O cliente consegue entrar, mas a federação falha

Verifique o DNS do Server Name, a porta 8448/TCP ou 443, /.well-known/matrix/server, o SAN do certificado e os cabeçalhos de requisição do proxy reverso. Se usar Cloudflare, confirme que o modo de proxy não bloqueia as requisições de federação e execute o Federation Tester a partir de uma rede externa.

O Element mostra que o homeserver está indisponível

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

Confirme public_baseurl, CORS, o Content-Type JSON e a cadeia de certificados; não confunda o domínio usado no navegador para acessar o Element Web com o endereço do homeserver.

O upload de mídia falha ou o disco cresce de repente

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

Primeiro limpe imagens do Docker e logs não utilizados, depois trate a mídia conforme a política de retenção. Não exclua manualmente arquivos de mídia sem registros no banco de dados e sem backups.

Voz e vídeo sem som ou funcionando apenas um a um

Verifique se o coturn está acessível, se o intervalo de portas de relay está liberado, se o IP público da VPS está correto e se as credenciais de curta duração expiraram. O TURN só resolve a travessia de NAT; ele não substitui largura de banda de saída suficiente.

Lista de verificação antes de entrar no ar

A dificuldade do Matrix Synapse não é fazer um contêiner iniciar, mas fazer com que o domínio de identidade, a descoberta de federação, o banco de dados, a mídia, o e-mail e os backups formem um ciclo completo. Primeiro valide com uma VPS de 2 núcleos e 4 GB e um subdomínio separado, depois amplie conforme o crescimento da mídia e o tráfego de federação; isso costuma ser mais fácil de manter do que empilhar componentes complexos desde o início.

Recursos oficiais

Primeiro defina a arquitetura e a configuração da VPS

O Server Name não pode ser alterado de qualquer jeito

Há duas formas comuns de planejamento:

Abordagem	Exemplo	Indicado para
Domínio principal como Server Name	`example.com`	Que os usuários usem `@alice:example.com`
Subdomínio como Server Name	`matrix.example.com`	Não afeta o site principal, implantação mais simples

Recomendações de configuração

Escala de uso	Configuração recomendada	Observações
Teste pessoal	2 núcleos, 2 GB, 30 GB SSD	Pode usar SQLite para validar o fluxo, não indicado para operação pública
Equipe pequena	2-4 núcleos, 4 GB, 60 GB NVMe	Planeje PostgreSQL, mídia e backups separadamente
Comunidade pública	4+ núcleos, 8 GB+, 100 GB+ NVMe	Reserve capacidade para mídia, busca, miniaturas e tráfego de federação

Preparação antes da instalação

Prepare uma VPS nova com Ubuntu de 64 bits, permissões de root ou sudo, um IP público fixo e um domínio já planejado. Primeiro configure o 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
~~

Os cabeçalhos de resposta devem incluir pelo menos `Content-Type: application/json`, e o corpo da resposta é o JSON acima. O cliente Element também pode usar:

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

Registrar o administrador e o cliente Element

Para criar o primeiro administrador, é preciso definir temporariamente registration_shared_secret em homeserver.yaml e depois reiniciar o contêiner:

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

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

SMTP, mídia e TURN

SMTP

Retenção de mídia

TURN para voz e vídeo

Backup, atualização e recuperação

Faça backup de pelo menos o seguinte:

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

Antes de atualizar, registre a versão, crie um snapshot da VPS e um backup do banco de dados:

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

Solução de problemas comuns

O contêiner encerra logo após iniciar

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

Verifique principalmente se homeserver.yaml existe, a indentação YAML, a conexão com o banco de dados, as permissões de UID do contêiner e se a chave de assinatura é legível.

O cliente consegue entrar, mas a federação falha

O Element mostra que o homeserver está indisponível

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

Confirme public_baseurl, CORS, o Content-Type JSON e a cadeia de certificados; não confunda o domínio usado no navegador para acessar o Element Web com o endereço do homeserver.

O upload de mídia falha ou o disco cresce de repente

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

Primeiro defina a arquitetura e a configuração da VPS

O Server Name não pode ser alterado de qualquer jeito

Recomendações de configuração

Preparação antes da instalação

用官方 Docker 镜像生成配置

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

启动 Synapse 和检查日志

Caddy 反向代理和 HTTPS

配置 Matrix 联邦和 well-known

直接使用 8448

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

Registrar o administrador e o cliente Element

SMTP, mídia e TURN

SMTP

Retenção de mídia

TURN para voz e vídeo

Backup, atualização e recuperação

Solução de problemas comuns

O contêiner encerra logo após iniciar

O cliente consegue entrar, mas a federação falha

O Element mostra que o homeserver está indisponível

O upload de mídia falha ou o disco cresce de repente

Voz e vídeo sem som ou funcionando apenas um a um

Lista de verificação antes de entrar no ar

Recursos oficiais

Carregando…

Primeiro defina a arquitetura e a configuração da VPS

O Server Name não pode ser alterado de qualquer jeito

Recomendações de configuração

Preparação antes da instalação

用官方 Docker 镜像生成配置

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

启动 Synapse 和检查日志

Caddy 反向代理和 HTTPS

配置 Matrix 联邦和 well-known

直接使用 8448

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

Registrar o administrador e o cliente Element

SMTP, mídia e TURN

SMTP

Retenção de mídia

TURN para voz e vídeo

Backup, atualização e recuperação

Solução de problemas comuns

O contêiner encerra logo após iniciar

O cliente consegue entrar, mas a federação falha

O Element mostra que o homeserver está indisponível

O upload de mídia falha ou o disco cresce de repente

Voz e vídeo sem som ou funcionando apenas um a um

Lista de verificação antes de entrar no ar

Recursos oficiais

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

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