Matrix+Element私有化部署

[luobo (大白萝卜)]

简介

Matrix和Synapse都是与去中心化通信相关的重要概念和软件项目，以下从多个方面分别对它们进行介绍：

Matrix

• 定义与定位：Matrix是一个开源的去中心化实时通信协议，旨在为即时通讯、VoIP（网络电话）、物联网等场景提供通用的开放标准。它允许不同的通信应用程序之间进行互操作，打破了传统即时通讯平台之间的壁垒，实现类似于电子邮件系统那样，不同服务商的用户能够相互通信。
• 特点
  • 去中心化：Matrix网络由众多独立运行的服务器组成，没有单一的控制中心。每个服务器可以独立管理自己的用户和数据，用户可以选择不同的服务器提供商，增强了数据的安全性和隐私性，也避免了单点故障问题。
  • 互操作性：不同的Matrix客户端和服务器可以相互通信，这意味着用户可以根据自己的喜好选择不同的客户端应用，而这些应用都能接入Matrix网络与其他用户交流，就像不同的电子邮件客户端都能收发邮件一样。
  • 多功能性：不仅支持文本聊天，还能进行语音通话、视频通话、文件共享等多种通信功能，满足了用户多样化的实时通信需求。
• 应用场景
  • 即时通讯：作为一个通用的通信协议，被广泛应用于各种即时通讯应用的开发，许多注重隐私和开放性的聊天工具基于Matrix构建。
  • 团队协作：适用于团队内部的沟通协作，支持创建群组聊天、频道等，方便团队成员之间进行信息交流和项目协作。
  • 物联网通信：在物联网领域，Matrix可用于设备之间以及设备与用户之间的实时通信，实现设备状态监控、远程控制等功能。

Synapse

• 定义与定位：Synapse是一个用Python编写的Matrix homeserver（家庭服务器，是Matrix网络中运行的服务器实例，负责管理用户账户、存储聊天数据、处理通信请求等）参考实现，由Matrix.org基金会开发和维护。它为搭建Matrix服务器提供了一个可靠且功能丰富的解决方案。
• 特点
  • 功能完备：Synapse实现了Matrix协议的大部分功能，包括用户注册与认证、房间管理、消息存储与同步、权限控制等。它可以处理大量的并发用户和消息，具备良好的稳定性和扩展性。
  • 易于部署：提供了相对简单的部署方式，支持在多种操作系统和云平台上安装运行。同时，它也有详细的文档和社区支持，方便开发者和管理员进行部署和维护。
  • 可定制性：允许管理员根据实际需求进行配置和定制，例如设置服务器的性能参数、安全策略、存储方式等。开发者还可以通过插件机制对其功能进行扩展。
• 应用场景
  • 个人服务器搭建：个人用户可以使用Synapse在自己的服务器或云主机上搭建私人的Matrix服务器，完全掌控自己的通信数据，确保隐私安全。
  • 企业通信平台：企业可以基于Synapse搭建内部的即时通讯和协作平台，实现员工之间的安全通信和高效协作，同时满足企业对数据安全和管理的要求。
  • 公共服务提供商：一些公共的Matrix服务提供商使用Synapse作为其服务器端软件，为广大用户提供Matrix网络接入服务，类似于传统的即时通讯服务提供商。

模型：Doubao-1.5-Pro

部署

需要注意的是，Synapse 的部署比较复杂，网上的教程也很多，当然我在这个过程中踩的坑简直无数了，所以仅供参考。

Synapse 部署有两种模式，单域名和双域名模式，但是这两种模式都推荐（或者要求）使用一级域名，也就是 example.com 来部署 homeserver，官方文档里推荐使用双域名模式，将 8448 联邦端口独立出去，但是也不知道到底是官方的文档写的烂还是我个人理解能力不行，反反复复琢磨了好几次，失败了无数次，终于是放弃了常规的部署方法。

下文中的部署方法完全是我 自己瞎琢磨的，不要求使用一级域名，可以在例如 matrix.example.com 的二级域名上使用（我现在就是这么用的），可以保证能用，但是不保证完全能用（实测有小瑕疵，下文会详细的说明）。

docker-compose.yml 配置文件：

# This compose file is compatible with Compose itself, it might need some
# adjustments to run properly with stack.

# version: '3'

services:

  synapse:
    # build:
    #   context: ../..
    #   dockerfile: docker/Dockerfile
    image: docker.io/matrixdotorg/synapse:latest
    container_name: matrix-server
    # Since synapse does not retry to connect to the database, restart upon
    # failure
    restart: unless-stopped
    # See the readme for a full documentation of the environment settings
    # NOTE: You must edit homeserver.yaml to use postgres, it defaults to sqlite
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
    volumes:
      # You may either store all the files in a local folder
      - ./files:/data
      # .. or you may split this between different storage points
      # - ./files:/data
      # - /path/to/ssd:/data/uploads
      # - /path/to/large_hdd:/data/media
    depends_on:
      - db
      - element
    # In order to expose Synapse, remove one of the following, you might for
    # instance expose the TLS port directly:
    ports:
      - 9008:8008
      - 9007:8448
      # - 9006:8009
    # networks:
    #   - matrix-network
    # ... or use a reverse proxy, here is an example for traefik:
    # labels:
    #   # The following lines are valid for Traefik version 1.x:
    #   - traefik.enable=true
    #   - traefik.frontend.rule=Host:my.matrix.Host
    #   - traefik.port=8008
    #   # Alternatively, for Traefik version 2.0:
    #   - traefik.enable=true
    #   - traefik.http.routers.http-synapse.entryPoints=http
    #   - traefik.http.routers.http-synapse.rule=Host(`my.matrix.host`)
    #   - traefik.http.middlewares.https_redirect.redirectscheme.scheme=https
    #   - traefik.http.middlewares.https_redirect.redirectscheme.permanent=true
    #   - traefik.http.routers.http-synapse.middlewares=https_redirect
    #   - traefik.http.routers.https-synapse.entryPoints=https
    #   - traefik.http.routers.https-synapse.rule=Host(`my.matrix.host`)
    #   - traefik.http.routers.https-synapse.service=synapse
    #   - traefik.http.routers.https-synapse.tls=true
    #   - traefik.http.services.synapse.loadbalancer.server.port=8008
    #   - traefik.http.routers.https-synapse.tls.certResolver=le-ssl

  db:
    image: docker.io/postgres:15-alpine
    container_name: matrix-database
    # ports:
    #   - 9007:5432/tcp
    # networks:
    #   - matrix-network
    # Change that password, of course!
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=xxxxxxxxxxxxx
      # ensure the database gets created correctly
      # https://element-hq.github.io/synapse/latest/postgres.html#set-up-database
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      # You may store the database tables in a local folder..
      - ./schemas:/var/lib/postgresql/data
      # .. or store them on some high performance storage for better results
      # - /path/to/ssd/storage:/var/lib/postgresql/data
  
  element:
    image: docker.io/vectorim/element-web:latest
    container_name: matrix-element
    ports:
      - 9009:80
    volumes:
      - ./element-web/config.json:/app/config.json
  
# networks:
#   matrix-network:
#     driver: bridge

这份配置文件 必须要修改 的地方只有一处就是数据库密码：

• POSTGRES_PASSWORD= ：自己自定义一个比较复杂的密码，最好含有大小写和数组和艾特或者点符号，不要有特殊符号，密码要记住，下面还要用。

推荐修改的地方只有：

• Synapse的端口：9008:8008 ，前面的 9008 自己改一个自己喜欢的就行（不要占用其他的服务或者特殊端口即可）；9007:8448 这个该不该都无所谓，注释了也行。
• Element的端口：9009:80 ，同上。

如果不修改端口，那么将 https://matrix.example.com 反代到 9008 端口，将 https://element.example.com 反代到 9009 端口即可。

然后在 yml 文件的当前目录，执行：

docker-compose run --rm -e SYNAPSE_SERVER_NAME=matrix.example.host -e SYNAPSE_REPORT_STATS=no synapse generate

按照提示进行输入即可，会生成一个配置文件，在当前目录下的 ./files/homeserver.yml 中，打开这个文件进行修改：

# Configuration file for Synapse.
#
# This is a YAML file: see [1] for a quick introduction. Note in particular
# that *indentation is important*: all the elements of a list or dictionary
# should have the same indentation.
#
# [1] https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html
#
# For more information on how to configure Synapse, including a complete accounting of
# each option, go to docs/usage/configuration/config_documentation.md or
# https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html
server_name: "matrix.exacple.com"
pid_file: /data/homeserver.pid
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true    # 位于反向代理后面，监听 http 时启用
    # bind_addresses: ['::1', '127.0.0.1']    # 监听所有本地流量，docker 部署不要启用
    resources:
      - names: [client, federation]
        compress: false
database:
  # name: sqlite3
  # args:
  #   database: /data/homeserver.db
  name: psycopg2
  args:
    user: synapse
    password: xxxxxxxxxxxxxx
    dbname: synapse
    host: db
    cp_min: 5
    cp_max: 10
    # seconds of inactivity after which TCP should send a keepalive message to the server
    keepalives_idle: 10
    # the number of seconds after which a TCP keepalive message that is not
    # acknowledged by the server should be retransmitted
    keepalives_interval: 10
    # the number of TCP keepalives that can be lost before the client's connection
    # to the server is considered dead
    keepalives_count: 3
enable_registration: true    # 是否允许注册
registration_requires_token: true    # 注册是否需要token
serve_server_wellknown: true    # 8448 托管到 443
public_baseurl: https://matrix.exacple.com/    # 客户端用于访问该家庭服务器的面向公众的基本 URL
web_client_location: https://element.exacple.com/    # 重定向 / 到 web 客户端
extra_well_known_client_content:    # 客户端标头 /.well-known/matrix/client 
  identity_server: "https://vector.im/"
  web_client: "https://element.exacple.com/"    # element 客户端的地址
report_stats: false    # 匿名发送报告
max_avatar_size: 1M    # 默认上传的头像文件大小
log_config: "/data/matrix.example.com.log.config"
media_store_path: /data/media_store
registration_shared_secret: "xxxxxxxxxxxxxxxxxxxxxxxxx"
macaroon_secret_key: "xxxxxxxxxxxxxxxxxxxxxxxxx"
form_secret: "xxxxxxxxxxxxxxxxxxxxxxxxx"
signing_key_path: "/data/matrix.example.com.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"


# vim:ft=yaml

注：这里的 serve_server_wellknown: true 必须要设置。

将数据库密码修改为 docker-compose.yml 文件中自己修改的，然后修改下面几个配置项：

• server_name ：如果生成配置的命令中已经修改过了，这里默认是自己matrix的服务端域名即可。
• public_baseurl ：等于 server_name 即可。
• web_client_location ：部署的element-web客户端的域名。
• web_client ：等于 web_client_location 即可（可选项）。

下面的xxxxxx部分是自动生成的密钥，默认即可。

然后返回 docker-compose.yml 所在目录，创建一个 element-web 文件夹（如果你docker-compose配置文件没有改element路径的话），在这个文件夹里创建一个 config.json 文件，写入：

{
    "default_server_name": "matrix.example.com",
    "default_server_config": {
        "m.homeserver": {
            "base_url": "https://matrix.example.com"
        },
        "m.identity_server": {
            "base_url": "https://vector.im"
        }
    }
}

更改域名为matrix的服务地址，身份验证服务器默认即可。

然后回到 docker-compose.yml 所在的文件夹，执行 docker compose up -d 启动容器。

等待容器的状态变成 healthy 之后，说明服务已经启动完成了，且没啥毛病。

注册用户

注册管理员账户，进入容器，执行：

register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -a

这个命令啥也不用修改，直接在容器内回车执行即可。

按照提示输入管理员账号和密码注册管理员即可。

注册普通账户首先必须确保开启了允许注册：

• enable_registration: true ：允许注册用户

其次，如果还开启了邀请码：

• registration_requires_token: true ：注册需要邀请码

那么首先需要生成一个邀请码，通过第三方管理接口进行登录：Synapse-Admin

输入自己的服务地址和刚才创建好的管理员账户和密码，登录，新建一个邀请码：

字段说明：

• Token，这里填入我们想创建的 token 内容，允许为空。
• Length，在 Token 字段为空的情况下，需要填入 Length，会自动生成一个指定长度的随机 token 值。
• Uses allowed，允许 token 使用多少次，填 null（不填）则是无限次。
• Expiry time，token 的过期时间，填 null（不填）则是没有过期时间。

如果不想要别人托管好的管理面板，可以自己再部署一个管理员面板，我这里就懒得弄了，这个管理员面板的仓库：Awesome/synapse-admin ，支持与 docker-compose 集成部署。

然后访问上文部署的 element-web 客户端，也就是 https://element.example.com ，点击注册，输入用户名和密码，输入邀请码即可。

测试联邦

一切就绪之后可以通过官方的这个工具进行测试联邦：Matrix Federation Tester ，访问之后输入自己的 server_name ，点击 Go，结果如图：

我这里是两个 v4 两个 v6，所以是四个，出现绿色的 Success 代表联邦没有问题。

然后访问 https://matrix.example.com/.well-known/matrix/server ，返回结果为：

{
  "m.server": "matrix.example.com:443"
}

继续访问 https://matrix.example.com/.well-known/matrix/client ，返回结果为：

{
  "m.homeserver": {
    "base_url": "https://matrix.example.com/"
  },
  "identity_server": "https://vector.im/",
  "web_client": "https://element.example.com/"
}

说明 8448 委托和客户端标头也都没问题。

当然，最好的测试办法就是去加一个其他服务器的公共聊天，看能否顺利加入和发送消息。

注意

• 域名反代，我用的是 1Panel 默认的 OpenResty，反代 没有任何特殊设置
• serve_server_wellknown: true 配置项必须要有
• 其实 Synapse 的端口暴露 8008 一个即可
• 数据库本地连接 host 直接是 db，也就是数据库 service 的名字即可，因为 docker-compose 默认在同一网络下
• element 手机端 App 的地址要写 element.example.com ，直接写 matrix.example.com 可能会产生如下报错：

瑕疵

我自己琢磨的这套部署方法，忽略了非常非常重要的一点，就是官方文档中所推荐的 8448 端口的监听，并且要将 8448 端口转发到 443，而且官方的反代中还进行了一些特殊的设置，因为我看不明白，所以压根就没弄，不过庆幸的是已经可以用了，也可以访问到其他服务器上的人和群聊，我就没管了。

不过贴上官方的 nginx 反代配置，你能看懂的话可以自己设置：

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    # For the federation port
    listen 8448 ssl default_server;
    listen [::]:8448 ssl default_server;

    server_name matrix.example.com;

    location ~ ^(/_matrix|/_synapse/client) {
        # note: do not add a path (even a single /) after the port in `proxy_pass`,
        # otherwise nginx will canonicalise the URI and cause signature verification
        # errors.
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host:$server_port;

        # Nginx by default only allows file uploads up to 1M in size
        # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
        client_max_body_size 50M;
    
    # Synapse responses may be chunked, which is an HTTP/1.1 feature.
    proxy_http_version 1.1;
    }
}

然后有个大佬给了我一份他自己的简单化的配置文件可以供参考：

location / {
    proxy_pass http://127.0.0.1:8008;
    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_http_version 1.1;
    proxy_set_header Connection "";
}

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

# 联邦请求代理
location /_matrix/federation {
    proxy_pass https://127.0.0.1:8448;
    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;
}

配置未经测试，请慎重哦~

参考资料

• Synapse 仓库：element-hq/synapse
• Synapse 文档：synapse/installation
• Synapse compose 示例：element-hq/synapse/docker-compose.yml
• element-web 说明：element-hq/element-web/install
• element-web config 示例：element-web/config.json
• Matrix Synapse 服务安装(Docker) | 侯坤林博客
• 超详细 Matrix Synapse 部署教程：搭建去中心化加密聊天服务器 - 白鱼小栈
• Docker部署Matrix&Element | OrdisBlog

[luobo (大白萝卜)]

如果迁移之后发现 server 容器一直在重启，查看日志报错无权限，可以试着先关闭容器，然后更改一下权限：

docker compose down

chown -R 70:0 ./schemas
chown -R 991:991 ./files

docker compose up -d

[luobo (大白萝卜)]

补充一个进阶配置和优化教程：

Docker Compose with Templates - Tom's Docs