2026 私有 Matrix 社交矩阵搭建全记录：从 502 到全线打# 2026 私有 Matrix 社交矩阵搭建全记录：从 502 到全线通

本文记录了基于 Synapse + Sliding Sync Proxy 架构的 Matrix 服务器搭建全过程。该方案完美支持下一代极速客户端 Element X，并采用 Nginx 实现多域名环境下的精准分流。

1. 核心架构与准备

• Matrix 核心: Synapse (Python)
• 数据库: PostgreSQL 16
• 缓存: Redis
• 加速代理: Sliding Sync Proxy (Element X 必备)
• 反向代理: 宿主机 Nginx

目录结构

mkdir -p ~/matrix/data ~/matrix/pgdata
cd ~/matrix

服务器配置

• **供应商 **: 阿里云（AlibabaCloud）
• 核心数: 2核
• 内存: 1G+2G（swap）
• 硬盘: 40G SSD
• 带宽: 30Mbps
• 系统环境: Debian12

2. Docker Compose 配置

新建并进入~/matrix创建 docker-compose.yml填入下方配置文件

services:
  # Matrix 核心服务端
  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    restart: unless-stopped
    networks:
      - matrix-network
    volumes:
      - ./data:/data
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
    depends_on:
      - db
      - redis
    ports:
      - "127.0.0.1:8010:8008" # 映射宿主机端口

  # 数据库 (PostgreSQL 16)
  db:
    image: postgres:16-alpine
    container_name: synapse_db
    restart: unless-stopped
    networks:
      - matrix-network
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=Your_Strong_Password
      - POSTGRES_DB=synapse
      # 关键：初始化为 C 排序规则以满足 Synapse 性能要求
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  # 缓存加速
  redis:
    image: redis:alpine
    container_name: synapse_redis
    restart: unless-stopped
    networks:
      - matrix-network

  # Sliding Sync Proxy (Element X 必备)
  sliding-sync:
    image: ghcr.io/matrix-org/sliding-sync:latest
    container_name: matrix_sliding_sync
    restart: unless-stopped
    networks:
      - matrix-network
    environment:
      - SYNCV3_SERVER=[https://matrix.yourdomain.com](https://matrix.yourdomain.com)
      - SYNCV3_DB=postgres://synapse:Your_Strong_Password@db/synapse?sslmode=disable
      - SYNCV3_SECRET=$(openssl rand -base64 32)
      - SYNCV3_BINDADDR=0.0.0.0:8008
    ports:
      - "127.0.0.1:8009:8008"
    depends_on:
      - db

networks:
  matrix-network:
    driver: bridge

运行docker-compose

docker compose up -d

生成与深度配置 Synapse

生成初始文件

docker run -it --rm \
    -v $(pwd)/data:/data \
    -e SYNAPSE_SERVER_NAME=matrix.undefim.com \
    -e SYNAPSE_REPORT_STATS=yes \
    matrixdotorg/synapse:latest generate

修改 homeserver.yaml 数据库配置

编辑 ~/matrix/data/homeserver.yaml。将默认的 sqlite3 完整替换为 psycopg2：

database:
  name: psycopg2
  args:
    user: synapse
    password: Your_Strong_Password
    database: synapse
    host: db
    cp_min: 5
    cp_max: 10

# 建议在文件末尾开启 Redis
redis:
  enabled: true
  host: redis
  port: 6379

进行宿主机 Nginx 域名分流

为了不影响服务器上现有的其他服务（如博客、面板），通过 server_name 进行分流。

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name matrix.undefim.com;

    ssl_certificate /etc/nginx/ssl/matrix.undefim.com.pem;
    ssl_certificate_key /etc/nginx/ssl/matrix.undefim.com.key;

    client_max_body_size 50M;

    # Synapse API
    location /_matrix {
        proxy_pass [http://127.0.0.1:8010](http://127.0.0.1:8010);
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    # Sliding Sync (Element X 转发路径)
    location ~ ^/(client/|v3/|proxy/)(.*)$ {
        proxy_pass [http://127.0.0.1:8009](http://127.0.0.1:8009);
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 客户端发现协议 (必须配置)
    location /.well-known/matrix/client {
        add_header Access-Control-Allow-Origin *;
        add_header Content-Type application/json;
        return 200 '{"m.homeserver": {"base_url": "[https://matrix.yourdomain.com](https://matrix.yourdomain.com)"}, "org.matrix.msc3575.proxy": {"url": "[https://matrix.yourdomain.com](https://matrix.yourdomain.com)"}}';
    }

    location / {
        proxy_pass [http://127.0.0.1:8010](http://127.0.0.1:8010);
        proxy_set_header Host $host;
    }
}

测试是否成功启动

curl -I http://127.0.0.1:8010/_matrix/static/

如果返回200 OK即为成功

生成管理员账号

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

END

现在你可以愉快的使用Element X享受你的Matrix了