Matrix Synapse Docker镜像文档

镜像概述

本镜像基于matrixdotorg的worker Dockerfile构建，是专为Unraid系统设计的Matrix Synapse家庭服务器（homeserver）镜像。它简化了Synapse的部署与管理，提供自动配置生成和多进程工作进程（worker）支持，适合需要高效管理Matrix家庭服务器的用户。

核心功能与特性

1. 自动配置生成
   删除主配置文件homeserver.yaml后，镜像会基于环境变量自动重建配置，保持配置文件清洁且与最新版本同步。若使用现有homeserver.yaml，需手动将主监听端口从默认8008修改为8080（因内部反向代理需求）。

2. 灵活的多进程支持
   通过环境变量指定worker类型即可启用多进程模式，无需复杂配置。镜像会自动处理反向代理和复制，支持动态添加/移除worker，提升服务器性能。

使用场景

• 适用于Unraid系统用户部署Matrix Synapse家庭服务器
• 需要简化配置管理、避免手动编辑配置文件的场景
• 需通过多进程worker提升服务器并发处理能力的场景
• 计划与其他家庭服务器（包括官方matrix.org）进行联邦的部署

重要注意事项

• 服务器名称选择：需提前确定服务器名称。例如，若用户ID格式为@someone:example.com，服务器名称必须设为example.com，而非matrix.example.com。详情参考官方文档。
• 备份要求：开始与其他家庭服务器联邦（包括matrix.org）前，必须备份密钥和数据库。若重建服务器时密钥不一致，其他服务器可能拒绝连接。
• 委托配置：建议了解Matrix委托（delegation）机制，确保服务器可被正确发现。

使用方法与配置说明

前置要求

• 了解Matrix基本概念及家庭服务器运作方式
• 确定服务器名称并规划联邦策略
• 准备持久化存储卷用于配置、媒体文件和数据备份

环境变量配置

必填环境变量

Worker配置

通过SYNAPSE_WORKER_TYPES变量配置工作进程，支持多进程模式：

• 取值说明：

  • 留空或设为空值：单进程模式（monolith mode）
  • 设为full：启用完整worker集（推荐生产环境）
  • 自定义worker类型：从以下列表选择，用空格分隔

• 支持的worker类型：
  account_data, event_persister, presence, receipts, to_device, typing,
  background_worker, event_creator, frontend_proxy, media_repository, pusher, synchrotron, user_dir,
  client_reader, federation_sender, federation_inbound, federation_reader

• full包含的worker：
  account_data, background_worker, event_creator, event_persister, federation_inbound, federation_reader, federation_sender, frontend_proxy, media_repository, presence, pusher, receipts, to_device, typing, synchrotron, user_dir

可选配置变量

附加功能变量

以下变量取值为yes/y/1/true/t/on时启用对应功能，其他值禁用：

卷映射

部署示例

Docker Run命令

docker run -d \
  --name synapse \
  -e SYNAPSE_SERVER_NAME=example.com \
  -e SYNAPSE_REPORT_STATS=yes \
  -e SYNAPSE_WORKER_TYPES=full \
  -e SYNAPSE_MAX_UPLOAD_SIZE=2048M \
  -v /path/to/appdata/synapse:/data \
  -v /path/to/media_store:/data/media_store \
  -v /path/to/prometheus:/var/lib/prometheus \
  -p 8080:8080 \
  your-image-name:latest

Docker Compose配置

version: '3'
services:
  synapse:
    image: your-image-name:latest
    container_name: synapse
    restart: unless-stopped
    environment:
      - SYNAPSE_SERVER_NAME=example.com
      - SYNAPSE_REPORT_STATS=yes
      - SYNAPSE_WORKER_TYPES=full
      - SYNAPSE_MAX_UPLOAD_SIZE=2048M
      - POSTGRES_HOST=postgres
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=your-secure-password
      - POSTGRES_DB=synapse
    volumes:
      - /path/to/appdata/synapse:/data
      - /path/to/media_store:/data/media_store
      - /path/to/prometheus:/var/lib/prometheus
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres:14
    container_name: synapse-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=your-secure-password
      - POSTGRES_DB=synapse
    volumes:
      - /path/to/postgres-data:/var/lib/postgresql/data

参考文档

• Matrix Synapse官方配置手册
• 服务器名称配置说明