Instalar Matrix Synapse en VPS (2026): Docker, federación, Element, HTTPS

Matrix Synapse es una implementación de homeserver del protocolo Matrix, adecuada para mantener en tus propias manos el chat de equipo, las comunidades privadas y la comunicación federada entre servidores. Se diferencia de una aplicación web de mensajería instantánea normal: además de la página de inicio de sesión, hay que gestionar correctamente el Server Name, la firma de eventos, el descubrimiento de federación, el almacenamiento de medios, el correo y las copias de seguridad.

Este artículo toma como ejemplo un VPS con Ubuntu 24.04 LTS, despliega Synapse con la imagen oficial de Docker matrixdotorg/synapse y ofrece HTTPS mediante un proxy inverso Caddy. Los ejemplos cubren PostgreSQL, el cliente Element, los puertos de federación, /.well-known, las cuentas de administrador, TURN, las actualizaciones y la recuperación. La documentación oficial de Synapse indica que el Server Name no se puede cambiar después de la instalación, por lo que la planificación del dominio debe completarse en el primer paso.

Primero define la arquitectura y la configuración del VPS

El Server Name no se puede cambiar a la ligera

El formato de un ID de usuario de Matrix es @user:server.name, donde server.name es el Server Name del homeserver. No es un simple alias del dominio web; una vez escrito en la base de datos y en las firmas de eventos, no se puede migrar ni modificar.

Hay dos formas habituales de planificarlo:

Enfoque	Ejemplo	Adecuado para
Dominio principal como Server Name	`example.com`	Que los usuarios usen `@alice:example.com`
Subdominio como Server Name	`matrix.example.com`	No afecta al sitio principal, despliegue más sencillo

Si eliges example.com, puedes poner la dirección de acceso del cliente en matrix.example.com y luego usar /.well-known/matrix/client para indicar a Element la dirección real del homeserver. Para reducir la complejidad, es más seguro usar matrix.example.com como Server Name y como dominio de acceso a la vez.

Recomendaciones de configuración

Escala de uso	Configuración recomendada	Notas
Pruebas personales	2 núcleos, 2 GB, 30 GB SSD	Se puede usar SQLite para validar el flujo, no apto para operación pública
Equipo pequeño	2-4 núcleos, 4 GB, 60 GB NVMe	Planifica por separado PostgreSQL, medios y copias de seguridad
Comunidad pública	4+ núcleos, 8 GB+, 100 GB+ NVMe	Reserva capacidad para medios, búsqueda, miniaturas y tráfico de federación

Los archivos multimedia de Synapse suelen crecer más rápido que la base de datos. No compres disco solo según el tamaño de la imagen del contenedor; calcula también las imágenes subidas, las miniaturas, los medios federados remotos, el WAL de PostgreSQL, los registros y las copias de seguridad externas. Puedes consultar primero la guía de selección de configuración de VPS y luego estimar la capacidad según el número de usuarios y el periodo de retención de medios.

Preparación antes de la instalación

Prepara un VPS nuevo con Ubuntu de 64 bits, permisos de root o sudo, una IP pública fija y un dominio ya planificado. Primero configura el 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
~~

Las cabeceras de respuesta deben incluir al menos `Content-Type: application/json`, y el cuerpo de la respuesta es el JSON anterior. El cliente Element también puede usar:

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

La ruta correspondiente es /.well-known/matrix/client. Tras el despliegue, usa curl -i para comprobar el código de estado, el Content-Type, el formato JSON y la cadena de certificados. Para probar la federación puedes usar Matrix Federation Tester; no des por hecho que la federación funciona solo porque la API local devuelva 200.

Registrar el administrador y el cliente Element

Para crear el primer administrador hay que establecer temporalmente registration_shared_secret en homeserver.yaml y luego reiniciar el contenedor:

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

Una vez creado, elimina registration_shared_secret y reinicia de nuevo. Esta clave solo se usa para el script de registro; no debe conservarse a largo plazo ni copiarse en tickets o registros públicos.

Element Web se puede desplegar por separado en element.example.com, o puedes usar primero el cliente alojado oficial para iniciar sesión en tu homeserver personalizado. Al autoalojar Element Web, configura config.json:

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

Primero prueba con dos cuentas normales el inicio de sesión, la creación de salas, la subida de medios, la invitación a usuarios de homeservers externos y el cierre de sesión de dispositivos; después abre el registro. Antes del registro público también deberías configurar captcha, límites de velocidad y verificación por correo para evitar registros masivos de bots.

SMTP, medios y TURN

SMTP

El correo se usa para restablecer contraseñas, verificar registros y enviar notificaciones. Usa el puerto 587/TLS del proveedor de correo transaccional y configura SPF, DKIM y DMARC en el DNS. Guarda la contraseña del correo en un archivo de configuración restringido o en un gestor de secretos; no escribas credenciales reales fuera de los ejemplos del artículo.

Retención de medios

El directorio donde se encuentra media_store_path crecerá continuamente. Puedes establecer una política de retención de medios en la configuración de Synapse y monitorizar el tamaño del directorio con alertas de disco. No borres directamente los archivos bajo media_store, ya que podrían quedar referencias no válidas en la base de datos.

TURN para voz y vídeo

La imagen oficial de Docker de Synapse no incluye un servicio TURN. Si necesitas voz y vídeo o compatibilidad con redes restringidas, despliega coturn por separado, configura autenticación estática o credenciales de corta duración, y configúralo según la documentación oficial en elementos como turn_uris y turn_shared_secret. Tras abrir los puertos de relay de TURN, limita el abuso; los nombres de usuario y contraseñas estáticos quedan expuestos a los clientes, así que en producción es preferible usar credenciales de corta duración.

Copias de seguridad, actualización y recuperación

Haz copia de seguridad al menos de lo siguiente:

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

Para la base de datos, usa copias nativas de PostgreSQL o instantáneas consistentes; la configuración y las claves de firma deben guardarse cifradas fuera del sitio. Puedes combinarlo con Cómo hacer un simulacro de copia de seguridad y recuperación de VPS para practicar de verdad: crea un VPS temporal, restaura la base de datos y /data, y luego verifica el resultado iniciando sesión con Element y ejecutando una prueba de federación.

Antes de actualizar, registra la versión, crea una instantánea del VPS y una copia de seguridad de la base de datos:

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

No uses latest a largo plazo en producción. Lee primero las Release Notes, valida la migración de la base de datos en un entorno de preproducción o en un VPS temporal y luego actualiza la etiqueta de la imagen a la versión objetivo. Tras la actualización, comprueba el inicio de sesión, los medios, el correo, la federación y las tareas en segundo plano, en lugar de fijarte solo en que el estado del contenedor sea Up.

Solución de problemas habituales

El contenedor se cierra inmediatamente después de arrancar

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

Revisa sobre todo si existe homeserver.yaml, la indentación YAML, la conexión a la base de datos, los permisos UID del contenedor y si la clave de firma es legible.

El cliente puede iniciar sesión pero la federación falla

Comprueba el DNS del Server Name, el puerto 8448/TCP o 443, /.well-known/matrix/server, el SAN del certificado y las cabeceras de la petición del proxy inverso. Si usas Cloudflare, confirma que el modo de proxy no bloquea las peticiones de federación y ejecuta Federation Tester desde una red externa.

Element muestra que el homeserver no está disponible

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

Confirma public_baseurl, CORS, el Content-Type JSON y la cadena de certificados; no confundas el dominio usado en el navegador para acceder a Element Web con la dirección del homeserver.

Falla la subida de medios o el disco crece de golpe

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

Primero limpia imágenes de Docker y registros no utilizados, y luego gestiona los medios según la política de retención. No borres manualmente archivos de medios sin registros en la base de datos y sin copias de seguridad.

La voz o el vídeo no tienen sonido o solo funcionan uno a uno

Comprueba si coturn es accesible, si el rango de puertos de relay está abierto, si la IP pública del VPS es correcta y si las credenciales de corta duración han caducado. TURN solo resuelve el traspaso de NAT; no sustituye a un ancho de banda de salida suficiente.

Lista de comprobación antes de publicar

La dificultad de Matrix Synapse no es arrancar un contenedor, sino hacer que el dominio de identidad, el descubrimiento de federación, la base de datos, los medios, el correo y las copias de seguridad formen un ciclo completo. Primero valida con un VPS de 2 núcleos y 4 GB y un subdominio independiente, y luego amplía según el crecimiento de medios y el tráfico de federación; normalmente es más fácil de mantener que acumular componentes complejos desde el principio.

Recursos oficiales

Primero define la arquitectura y la configuración del VPS

El Server Name no se puede cambiar a la ligera

Hay dos formas habituales de planificarlo:

Enfoque	Ejemplo	Adecuado para
Dominio principal como Server Name	`example.com`	Que los usuarios usen `@alice:example.com`
Subdominio como Server Name	`matrix.example.com`	No afecta al sitio principal, despliegue más sencillo

Recomendaciones de configuración

Escala de uso	Configuración recomendada	Notas
Pruebas personales	2 núcleos, 2 GB, 30 GB SSD	Se puede usar SQLite para validar el flujo, no apto para operación pública
Equipo pequeño	2-4 núcleos, 4 GB, 60 GB NVMe	Planifica por separado PostgreSQL, medios y copias de seguridad
Comunidad pública	4+ núcleos, 8 GB+, 100 GB+ NVMe	Reserva capacidad para medios, búsqueda, miniaturas y tráfico de federación

Preparación antes de la instalación

Prepara un VPS nuevo con Ubuntu de 64 bits, permisos de root o sudo, una IP pública fija y un dominio ya planificado. Primero configura el 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
~~

Las cabeceras de respuesta deben incluir al menos `Content-Type: application/json`, y el cuerpo de la respuesta es el JSON anterior. El cliente Element también puede usar:

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

Registrar el administrador y el cliente Element

Para crear el primer administrador hay que establecer temporalmente registration_shared_secret en homeserver.yaml y luego reiniciar el contenedor:

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, medios y TURN

SMTP

Retención de medios

TURN para voz y vídeo

Copias de seguridad, actualización y recuperación

Haz copia de seguridad al menos de lo siguiente:

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

Antes de actualizar, registra la versión, crea una instantánea del VPS y una copia de seguridad de la base de datos:

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

Solución de problemas habituales

El contenedor se cierra inmediatamente después de arrancar

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

Revisa sobre todo si existe homeserver.yaml, la indentación YAML, la conexión a la base de datos, los permisos UID del contenedor y si la clave de firma es legible.

El cliente puede iniciar sesión pero la federación falla

Element muestra que el homeserver no está disponible

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

Confirma public_baseurl, CORS, el Content-Type JSON y la cadena de certificados; no confundas el dominio usado en el navegador para acceder a Element Web con la dirección del homeserver.

Falla la subida de medios o el disco crece de golpe

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

Primero define la arquitectura y la configuración del VPS

El Server Name no se puede cambiar a la ligera

Recomendaciones de configuración

Preparación antes de la instalación

用官方 Docker 镜像生成配置

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

启动 Synapse 和检查日志

Caddy 反向代理和 HTTPS

配置 Matrix 联邦和 well-known

直接使用 8448

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

Registrar el administrador y el cliente Element

SMTP, medios y TURN

SMTP

Retención de medios

TURN para voz y vídeo

Copias de seguridad, actualización y recuperación

Solución de problemas habituales

El contenedor se cierra inmediatamente después de arrancar

El cliente puede iniciar sesión pero la federación falla

Element muestra que el homeserver no está disponible

Falla la subida de medios o el disco crece de golpe

La voz o el vídeo no tienen sonido o solo funcionan uno a uno

Lista de comprobación antes de publicar

Recursos oficiales

Cargando…

Primero define la arquitectura y la configuración del VPS

El Server Name no se puede cambiar a la ligera

Recomendaciones de configuración

Preparación antes de la instalación

用官方 Docker 镜像生成配置

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

启动 Synapse 和检查日志

Caddy 反向代理和 HTTPS

配置 Matrix 联邦和 well-known

直接使用 8448

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

Registrar el administrador y el cliente Element

SMTP, medios y TURN

SMTP

Retención de medios

TURN para voz y vídeo

Copias de seguridad, actualización y recuperación

Solución de problemas habituales

El contenedor se cierra inmediatamente después de arrancar

El cliente puede iniciar sesión pero la federación falla

Element muestra que el homeserver no está disponible

Falla la subida de medios o el disco crece de golpe

La voz o el vídeo no tienen sonido o solo funcionan uno a uno

Lista de comprobación antes de publicar

Recursos oficiales

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

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