前言

Matrix 是一套去中心化通讯协议，可用于搭建属于个人或团体的独立聊天系统。

Element 是基于 Matrix 的客户端，支持网页、手机和桌面端；支持文字聊天，语音/视频通话、文件传输、群组管理等。

它的优势在于端到端加密 核心原理：消息在发送方设备上加密，只能在接收方设备上解密。传输过程中，包括服务器在内的任何中间环节都无法读取消息内容 保障安全，支持跨平台同步，并可完全自主管理，打造专属、安全的通讯环境。

Matrix官网：https://matrix.org/

Element官网：https://element.io/

创建项目目录

1
2
mkdir -p /root/data/docker_data/matrix
cd /root/data/docker_data/matrix

生成 Synapse 配置文件

首先运行以下命令生成初始配置：

1
2
3
4
5
sudo docker run -it --rm \
-v /root/data/docker_data/matrix/data:/data \
-e SYNAPSE_SERVER_NAME=matrix.yourdomain.com \  # 替换Matrix 服务域名
-e SYNAPSE_REPORT_STATS=yes \
matrixdotorg/synapse:latest generate

参数说明：

  • -v /root/data/docker_data/matrix/data:/data - 将宿主机目录挂载到容器，存储配置和数据；
  • --rm - 完成映射后删除容器
  • SYNAPSE_SERVER_NAME - 必须替换为您的 Matrix 服务器域名
  • SYNAPSE_REPORT_STATS - 是否向 Matrix.org 发送匿名统计信息

Synapse 配置文件 (homeserver.yaml)

生成后会在 ./data 目录下创建配置文件，homeserver.yaml主要内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# Configuration file for Synapse.
server_name: "matrix.yourdomain.com"
pid_file: /data/homeserver.pid

listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true  # 启用反向代理支持
    resources:
      - names: [client, federation]  # 客户端和联邦协议支持
        compress: false

database:
  name: sqlite3  # 小规模使用，大规模建议 PostgreSQL
  args:
    database: /data/homeserver.db

log_config: "/data/matrix.yourdomain.com.log.config"  # 会自动生成对应文件名
media_store_path: /data/media_store

# 以下密钥会自动生成，请保持唯一性
registration_shared_secret: "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6"
macaroon_secret_key: "B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A1"
form_secret: "C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A1B2"

signing_key_path: "/data/matrix.yourdomain.com.signing.key"  # 会自动生成对应文件名

trusted_key_servers:
  - server_name: "matrix.org"  # 信任的密钥服务器

# 注册设置(首次启动可以设为true开启注册，注册后再这里修改为false，然后重启服务)
enable_registration: false  
enable_registration_without_verification: false

# 管理员账号列表（完整 Matrix ID 格式）
admin_users:
  - "@admin:matrix.yourdomain.com" 

report_stats: true  # 发送匿名统计信息

# vim:ft=yaml

添加的配置项（可选）：

1
2
3
4
5
enable_registration: false
enable_registration_without_verification: false
encryption_enabled_by_default_for_room_type: all  # 所有房间默认加密
admin_users:                                      # 设置用户为管理员
  - "@admin:matrix.yourdomain.com"

需修改的配置项：

  • server_name - Matrix 服务器域名
  • admin_users - 管理员账号用户名
  • enable_registration - 关闭或开启公开注册

Docker Compose 配置

创建 docker-compose.yml 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
cat > /root/data/docker_data/matrix/docker-compose.yml <<'EOF'
version: "3.3"
services:
  synapse:
    image: "matrixdotorg/synapse:latest"
    container_name: "matrix_synapse"
    restart: unless-stopped
    ports:
      - 6235:8008  # 可以修改宿主机端口号
    volumes:
      - ./data:/data
    environment:
      # 反向代理配置（如使用 nginx-proxy）
      VIRTUAL_HOST: "matrix.yourdomain.com"  # 替换Matrix 域名
      VIRTUAL_PORT: 8008
      LETSENCRYPT_HOST: "matrix.yourdomain.com"  # 替换Matrix 域名
      SYNAPSE_SERVER_NAME: "matrix.yourdomain.com"  # 替换Matrix 域名
      SYNAPSE_REPORT_STATS: "yes"
  
  element-web:
    image: vectorim/element-web:latest
    container_name: "matrix_element"
    restart: unless-stopped
    ports:
      - 6241:80  # 可以修改宿主机端口号
    volumes:
      - ./element-config.json:/app/config.json:ro
    environment:
      # Element Web 使用不同域名提高安全性
      VIRTUAL_HOST: "element.yourdomain.com"  # 替换Element 域名
      VIRTUAL_PORT: 80
      LETSENCRYPT_HOST: "element.yourdomain.com"  # 替换Element 域名
EOF

配置说明：

  • 端口可以根据需要修改
  • Element Web 建议使用与 Matrix 不同的域名提高安全性
  • 环境变量用于 nginx-proxy 自动配置 SSL

Element Web 配置

有了这个配置文件：Element 界面会自动预填您的服务器信息，用户只需要输入用户名和密码就能登录

创建 element-config.json 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
cat > /root/data/docker_data/matrix/element-config.json <<'EOF'
{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.yourdomain.com",
      "server_name": "matrix.yourdomain.com"
    }
  },
  "features": {
    "feature_dm_encryption": true,
    "feature_cross_signing": true
  },
  "defaultCountryCode": "CN"
}
EOF

feature_dm_encryption：私聊默认加密

feature_cross_signing: 更好的设备验证体验

defaultCountryCode：中国使用时开启默认CN

管理员账号设置

方法1：配置文件声明（推荐）

在 homeserver.yaml 中配置 admin_users：

1
2
3
admin_users:
  - "@admin:matrix.yourdomain.com"     # 替换域名
  - "@username:matrix.yourdomain.com"  # 可以添加多个管理员

格式要求：

  • 必须是完整的 Matrix ID 格式：@用户名:服务器域名
  • 用户必须先注册账号，然后重启服务器生效

方法2：直接注册管理员账号

1
2
3
4
5
# 进入容器
docker exec -it matrix_synapse /bin/bash

# 运行注册命令
register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

交互流程：

  1. 输入用户名
  2. 输入密码
  3. 确认密码
  4. 询问是否为管理员时输入 yes

创建管理员账号