搬瓦工搭建 Matrix Synapse 即时通讯服务完整教程

Matrix 是一个开放的去中心化即时通讯协议，Synapse 是其官方参考服务器实现。Matrix 支持端到端加密、联邦互通、语音视频通话等功能，可以作为 Slack 或 Telegram 的自托管替代品。配合 Element 客户端使用，可以获得类似微信的聊天体验。本文将介绍如何在搬瓦工 VPS 上通过 Docker 部署 Matrix Synapse。

一、准备工作

1.1 系统要求

操作系统：Ubuntu 20.04+（推荐 Ubuntu 22.04）。
内存：至少 1GB，推荐 2GB 以上。
磁盘空间：至少 10GB。
域名：需要准备域名并配置 DNS。
Docker：需提前安装，参考 Docker 安装教程。

1.2 创建目录

mkdir -p /opt/matrix/data
mkdir -p /opt/matrix/element

二、部署 Synapse 服务器

2.1 生成初始配置

docker run -it --rm \
  -v /opt/matrix/data:/data \
  -e SYNAPSE_SERVER_NAME=matrix.example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

2.2 编辑配置文件

编辑 /opt/matrix/data/homeserver.yaml，修改以下关键配置：

# 修改数据库为 PostgreSQL
database:
  name: psycopg2
  args:
    user: synapse
    password: your_db_password
    database: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10

# 启用注册（按需开启）
enable_registration: true
enable_registration_without_verification: false

# 媒体存储配置
max_upload_size: 50M

2.3 创建 Docker Compose 文件

cd /opt/matrix
cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  db:
    image: postgres:16-alpine
    container_name: matrix-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: your_db_password
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
    volumes:
      - ./postgres:/var/lib/postgresql/data

  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "127.0.0.1:8008:8008"
    volumes:
      - ./data:/data

  element:
    image: vectorim/element-web:latest
    container_name: element
    restart: unless-stopped
    ports:
      - "127.0.0.1:8088:80"
    volumes:
      - ./element/config.json:/app/config.json
EOF

2.4 配置 Element Web 客户端

cat > /opt/matrix/element/config.json <<'EOF'
{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com",
      "server_name": "matrix.example.com"
    }
  },
  "brand": "Element",
  "integrations_ui_url": "",
  "integrations_rest_url": "",
  "disable_guests": true,
  "disable_3pid_login": false
}
EOF

2.5 启动服务

docker compose up -d

三、Nginx 反向代理

# Synapse API
server {
    listen 443 ssl http2;
    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;

    client_max_body_size 50M;

    location ~* ^(\/_matrix|\/_synapse\/client) {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# Element Web 客户端
server {
    listen 443 ssl http2;
    server_name chat.example.com;

    ssl_certificate /etc/letsencrypt/live/chat.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3.1 Federation 配置

为了让其他 Matrix 服务器能发现你的实例，需要配置 .well-known 或在 DNS 中添加 SRV 记录。最简单的方式是在 Nginx 中添加：

    location /.well-known/matrix/server {
        return 200 '{"m.server": "matrix.example.com:443"}';
        add_header Content-Type application/json;
    }

    location /.well-known/matrix/client {
        return 200 '{"m.homeserver": {"base_url": "https://matrix.example.com"}}';
        add_header Content-Type application/json;
        add_header Access-Control-Allow-Origin *;
    }

四、创建管理员账户

docker exec -it synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  -a -u admin -p your_password

五、客户端使用

Matrix 拥有丰富的客户端生态：

Web：Element Web（自托管或使用 app.element.io）。
桌面：Element Desktop（Windows/macOS/Linux）。
移动端：Element（iOS/Android）。
终端：gomuks、weechat-matrix。

连接时将 Homeserver 地址设为 https://matrix.example.com。

六、端到端加密

Matrix 原生支持端到端加密（E2EE）。在 Element 客户端中创建聊天室时，可以开启加密选项。加密后的消息在服务器上以密文存储，即便管理员也无法查看消息内容。首次使用加密功能时，请务必备份恢复密钥。

七、维护与更新

7.1 更新组件

cd /opt/matrix
docker compose pull
docker compose up -d

7.2 备份数据

# 备份数据库
docker exec matrix-db pg_dump -U synapse synapse > matrix-db.sql

# 备份媒体文件
tar -czf matrix-media.tar.gz -C /opt/matrix/data media_store/

7.3 清理缓存

# 清理远程媒体缓存
docker exec synapse python -m synapse._scripts.update_synapse_database \
  --database-config /data/homeserver.yaml

总结

Matrix Synapse 是搭建自托管即时通讯服务的绝佳选择，其联邦架构和端到端加密让你在享受便捷通讯的同时保护隐私。在搬瓦工 VPS 上部署后，配合 Element 客户端可以获得优秀的跨平台聊天体验。如果你更偏好团队协作类的聊天工具，可以参考 Mattermost 或 Rocket.Chat 教程。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。如遇问题，可前往搬瓦工官网提交工单。