selfhost-matrix-element

Linux Matrix + Element (Synapse) 生产级部署实操指南

本指南基于生产级 Docker Compose 架构规范，介绍如何部署 Matrix 通信生态。该方案采用配置与逻辑分离原则，并实施严格的网络隔离策略以确保数据库安全性。

1. 前置准备

1.1 环境要求

操作系统：Linux (Ubuntu 22.04+ / RocketLinux 8+ 推荐)
核心组件：Docker Engine 24.0+, Docker Compose V2
网络条件：已拥有公网 IP 或内网穿透环境，且 80/443 端口已开放。
域名准备：需准备两个 A 记录指向服务器 IP：
matrix.example.com (服务端)
element.example.com (Web 客户端)

1.2 目录初始化

# 定义基础数据根目录（对应变量 ${BASE_DATA_PATH}）
mkdir -p /opt/matrix-data/{synapse,element,postgres}

2. 核心部署配置

2.1 环境配置文件 (.env)

[!WARNING]
.env 文件包含敏感凭据，严禁上传至公共代码仓库。修改 POSTGRES_PASSWORD 后必须同步更新 homeserver.yaml 中的连接字符串。

# /opt/matrix-data/.env

# 项目基础配置
COMPOSE_PROJECT_NAME=matrix
BASE_DATA_PATH=/opt/matrix-data
PROXY_NETWORK_NAME=proxy_nw
TZ=Asia/Shanghai

# 域名定义
DOMAIN=example.com
MATRIX_SUBDOMAIN=matrix.example.com

# 数据库配置
POSTGRES_VERSION=17-alpine
POSTGRES_USER=synapse
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=synapse

2.2 服务编排文件 (docker-compose.yml)

网络架构模式说明：
本配置采用 标准隔离 / 数据库保护。

拓扑结构:
matrix.synapse 与 matrix.element 同时接入内部 default 网络与外部 ${PROXY_NETWORK_NAME}，实现对外服务与内部通信。
matrix.db 仅接入内部 default 网络，从物理层面禁止外部直接访问数据库。
安全约束: 根据规范，Web UI 及 API 端口（8008, 80）不进行宿主机端口映射（ports），强制通过反向代理网络访问。

# /opt/matrix-data/docker-compose.yml
services:
  # 数据库：后端存储
  db:
    image: postgres:${POSTGRES_VERSION}
    container_name: ${COMPOSE_PROJECT_NAME}-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
      - TZ=${TZ}
    volumes:
      - ${BASE_DATA_PATH}/postgres:/var/lib/postgresql/data

  # Matrix 核心服务
  synapse:
    image: matrixdotorg/synapse:latest
    container_name: ${COMPOSE_PROJECT_NAME}-synapse
    restart: unless-stopped
    networks:
      - default:
      - proxy_net:
    volumes:
      - ${BASE_DATA_PATH}/synapse:/data
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
      - TZ=${TZ}
    depends_on:
      - db

  # Element Web 客户端
  element:
    image: vectorim/element-web:latest
    container_name: ${COMPOSE_PROJECT_NAME}-element
    restart: unless-stopped
    networks:
      default:
      proxy_net:
    volumes:
      - ${BASE_DATA_PATH}/element/config.json:/app/config.json
    environment:
      - TZ=${TZ}

networks:
  # 声明外部反向代理网络
  proxy_net:
    external: true
    name: ${PROXY_NETWORK_NAME}
  # 默认内部网络 (由 Compose 自动管理)
  default:
    name: ${COMPOSE_PROJECT_NAME}_internal

3. 关键应用配置

3.1 Synapse 初始化与数据库接入

生成初始配置：

docker run -it --rm \
    -v "${BASE_DATA_PATH}/synapse:/data" \
    -e SYNAPSE_SERVER_NAME=matrix.example.com \
    -e SYNAPSE_REPORT_STATS=no \
    matrixdotorg/synapse:latest generate

3.2 Synapse 配置优化 (homeserver.yaml)

编辑 ./synapse-data/homeserver.yaml，调整数据库与基础权限：修改 ${BASE_DATA_PATH}/synapse/homeserver.yaml 中的数据库部分：

# 数据库连接配置
database:
  name: psycopg2
  args:
    user: synapse           # 对应 .env 中的 POSTGRES_USER
    password: your_password # 对应 .env 中的 POSTGRES_PASSWORD
    database: synapse       # 对应 .env 中的 POSTGRES_DB
    host: matrix-db         # 对应 container_name
    cp_min: 5
    cp_max: 10

配置项	说明	建议值
`database.name`	数据库驱动	`psycopg2`
`database.args.host`	数据库主机名	`matrix.db` (对应 Compose 别名)
`enable_registration`	开放注册	`false` (生产环境建议关闭)
`use_presence`	在线状态追踪	`false` (关闭可降低 CPU/内存压力)
`max_upload_size`	最大附件限制	`50M`

3.3 Element 客户端配置 (config.json)

编辑 ${BASE_DATA_PATH}/element/config.json：

{
    "default_server_config": {
        "m.homeserver": {
            "base_url": "https://matrix.example.com",
            "server_name": "matrix.example.com"
        }
    },
    "brand": "Matrix Private Cloud",
    "disable_custom_urls": true,
    "disable_guests": true,
    "default_theme": "dark"
}

4. 宿主机反向代理 (Nginx 示例)

需在宿主机 Nginx 配置文件中添加以下虚拟主机逻辑，并处理 SSL 证书。

4.1 Matrix 服务端配置

server {
    listen 443 ssl;
    server_name matrix.example.com;

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

    # Federation 联邦发现配置
    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" "*";
    }
}

由于容器未暴露端口，Nginx 必须接入 ${PROXY_NETWORK_NAME} 网络或通过容器名进行转发。若 Nginx 运行在宿主机，请确保防火墙允许反代网络段访问容器。

# 转发至 Synapse API
server {
    server_name matrix.example.com;
    listen 443 ssl;
    location / {
        # 使用容器名及内部端口通信
        proxy_pass http://matrix-synapse:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# 转发至 Element Web
server {
    server_name element.example.com;
    listen 443 ssl;
    location / {
        proxy_pass http://matrix-element:80;
        proxy_set_header Host $host;
    }
}

5. 账户管理与运维

5.1 启动服务

docker compose up -d

5.2 账号创建方案

方案 A：命令行创建（推荐）

适用于初始化管理员或手动录入用户。

# 创建管理员账号
docker exec -it matrix-synapse register_new_matrix_user \
    http://localhost:8008 -c /data/homeserver.yaml --admin

# 创建普通账号
docker exec -it matrix-synapse register_new_matrix_user \
    http://localhost:8008 -c /data/homeserver.yaml --no-admin

注：localpart 提示符处输入所需用户名（如 root），生成的完整 ID 为 @root:matrix.example.com。

方案 B：数据库直接提权

若需将已有账号 user_id 提升为管理员：

docker exec -it matrix-db psql -U synapse -d synapse -c "UPDATE users SET admin = 1 WHERE name = '@user_id:domain';"

6. 常见问题排查

数据库连接失败：确保 homeserver.yaml 中的 database.args.host 指向 matrix.db 而非 localhost。
联邦通信失败：需确保 .well-known 路径可正常访问且返回正确的 JSON 格式。
移动端登录错误：在移动端 Element 登录时，必须手动修改“服务器 URL”为 https://matrix.example.com，而非默认的 matrix.org。

参考资料

5. 常见管理操作

5.1 用户注册 (本地管理)

在禁用公开注册的情况下，通过容器内工具手动创建用户：

# 创建管理员
docker exec -it matrix-synapse register_new_matrix_user \
    http://localhost:8008 -c /data/homeserver.yaml --admin

# 按照提示输入用户名 (localpart) 和密码

5.2 数据库维护

# 进入数据库命令行
docker exec -it matrix-db psql -U synapse -d synapse

6. 参考资料

Would you like me to generate a monitoring sidecar configuration (e.g., Prometheus Exporter) based on this Network Mode A architecture?

selfhost-matrix-element

http://blog.zhens.site/selfhost-matrix-element/

作者

zhens

发布于

2026年2月24日

许可协议

WSL2/Docker/Miniconda：深度学习LLM环境配置指南下一篇