Matrix 通信及其生态服务自建流程和运维备忘

交流群：博客右上角"账号-联系支持服务"，发送邮件获取Matrix房间邀请。

服务器要求

3种需求：

只本地聊天
性能要求：2核2G，25G SSD。
网络要求：可拉取Docker Hub镜像和GitHub仓库。
推荐搭建环境：家庭NAS。
异地使用+少数联邦
性能要求：2核4G，50G SSD。
网络要求：公网IPv4（用内网穿透也行）。可拉取Docker Hub镜像和GitHub仓库。联邦网络需要能访问指定域名。
推荐搭建环境：家庭NAS（具有透明代理环境）或海外VPS。
全球无障碍通信
性能要求：至少2核4G，50G SSD。如果有大房间聊天和保存大量媒体文件的需求，则推荐2T以上 SSD，或者一台独立的数据库服务器和S3存储盘。
网络要求：可访问全球互联网的服务器
推荐搭建环境：海外VPS

注意：选择海外VPS时，建议优先考虑具有良好网络连接和数据中心合规性的服务商。

域名配置

配置域名DNS

将一级域名指向给matrix提供.well-known配置的服务器IP，如果是cloudflare，可以使用worker代替。
将二级域名指向自己部署matrix服务的IP，如果是cloudflare并且.well-known上使用443 2053 2083 2087 2096 8443中的端口做联邦服务或客户端API端口，则可以启用Cloud CDN，CND有助于在网络直连不佳的情况下加速以及保护源站减少恶意攻击。

服务器环境配置

VPS环境配置

root账号登录ssh：ssh -p port root@ip

启用防火墙（强烈推荐）并开放指定端口，以Ubuntu为例：

# 允许外网访问指定端口
ufw allow 443/tcp
# matrix联邦和客户端端口
ufw allow 8448/tcp
# ssh端口（默认22）
ufw allow 22/tcp
# ssh端口（手动新添加的端口）
ufw allow 2202/tcp
# 其他需要开放的端口，例如25邮箱端口，或指定开放端口范围
ufw allow 8000:9000/tcp
# 允许本地网络访问任意端口
ufw allow from 127.0.0.1
ufw allow from 172.16.0.0/12
ufw allow from 192.168.0.0/16
# 启用防火墙
ufw enable
# 查看规则
ufw status verbose
# ---
# 如果需要删除规则
ufw delete allow 80/tcp
# 重启防火墙
ufw reload
# 或禁用防火墙
ufw disable

修改SSH端口（强烈推荐）

vi /etc/ssh/sshd_config
port 22 # 在配置中找到这一行取消注释并改成指定端口
/etc/init.d/ssh restart

安装Docker和Docker Compose环境

参考文档（以ubuntu为例）；
- 安装 Docker：Ubuntu | Docker Docs
- 安装 Compose：Install the Compose plugin | Docker Docs
设置docker开机自启：

systemctl enable docker.service

申请SSL证书（推荐使用acme.sh）

参考教程：说明 · acmesh-official/acme.sh Wiki

安装Nginx（推荐，也可选择其他反向代理工具）

有三种情况下需要使用反向代理：
- 在本机提供 Matrix 联邦所必须的 .well-known端点，.well-known也可以异机提供或用 cloudflare worker 等云服务的方式。
- 使用alist同步备份Matrix 数据，如果是vps，强烈建议。
- 使用反向代理的方式访问 Matrix，Synapse服务端支持配置多个http/https端口，反向代理不是必须的，但如果想要区分多个端口做不同用途（例如一个用于跨域名联邦一个用于客户端）则反向代理是一种方式。

apt update
apt install nginx

配置nginx： vi /etc/nginx/nginx.conf，参考：

# matrix的.well-known（服务发现）配置，如果.well-known异机提供则不需要
# 联邦（server）和客户端（client）路由可使用不同的端点
server {
    listen 443 ssl;
    server_name your_domain.com;
    # ssl证书放在自己手动上传的位置
    ssl_certificate /root/ssl/fullchain.cer;
    ssl_certificate_key /root/ssl/*.your_domain.com.key;
    location = /.well-known/matrix/server {
        default_type application/json;
        add_header Access-Control-Allow-Origin "*";
        return 200 '{"m.server": "matrix.your_domain.com:8448"}';
    }
    location = /.well-known/matrix/client {
        default_type application/json;
        add_header Access-Control-Allow-Origin "*";
        return 200 '{"m.homeserver": {"base_url": "https://matrix.your_domain.com:8448"}}';
    }
}
# 使用alist备份 matrix 数据
server {
    listen 443 ssl;
    server_name alist.your_domain.com;
    ssl_certificate /root/ssl/fullchain.cer;
    ssl_certificate_key /root/ssl/*.your_domain.com.key;
    location / {
        proxy_pass http://localhost:5244;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
        proxy_redirect off;
        client_max_body_size 20000m;
    }
}
# 给 matrix 反代（联邦和客户端可共用）
server {
    listen 8448 ssl;
    listen [::]:8448 ssl;
    server_name matrix.your_domain.com;
    ssl_certificate /root/ssl/fullchain.cer;
    ssl_certificate_key /root/ssl/*.your_domain.com.key;
    add_header Strict-Transport-Security "max-age=15768000; includeSubdomains; preload" always;
    proxy_ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
    location ~ ^(/_matrix|/_synapse/client) {
        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;
        client_max_body_size 1024M;
        proxy_connect_timeout 300;
        proxy_read_timeout 300;
        proxy_send_timeout 300;
        proxy_http_version 1.1;
    }
    location / {
        proxy_pass http://localhost:8008;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

检查nginx配置并重载：

nginx -t
systemctl reload nginx

如果是家庭NAS

确定家庭网络是否有公网IP，如果没有则需要做内网穿透
如果有公网IP，则需要：

路由器上开启端口转发，如果路由器使用桥接模式，还需要在光猫上开启端口转发（或DNZ）
在路由器或NAS上安装DDNS服务，将公网IP定时上报给DNS服务商。
在NAS上安装证书并定时更新，参考上一节。
其他防火墙、反向代理、Docker环境配置参考上一节。

开始安装 Matrix 服务

推荐用 Synapse.，目前最成熟的matrix服务端实现，可选dendrite（go语言编写，理论上性能更优，但项目缺少维护），以下教程使用synapse。

用docker创建数据库（中国推荐用pgzhparser，包含中文分词的postgres数据库，）：

synapse不原生支持中文搜索，具体参考博文：给 Matrix Synapse 添加中文搜索。

# database_user、database_password、path填入自己新数据库的设置
# 可以使用bridge模式，指定端口映射
# 建议用17而不是latest标签，因为latest会有大版本更新，导致后续更新后数据库不兼容
docker run -d --restart=unless-stopped --name pgzhparser --net=host -e POSTGRES_USER=database_user -e POSTGRES_PASSWORD=database_password -e POSTGRES_DB=postgres -e PGDATA=/var/lib/postgresql/data -v /root/pgzhparser/data:/var/lib/postgresql/data abcfy2/zhparser:17

记住database_user、database_password。进入数据库容器创建matrix数据库（指定LC_COLLATE、LC_CTYPE）：

docker exec -it pgzhparser bash
# 使用 `psql` 连接到 默认的 PostgreSQL 数据库
psql -U database_user -d postgres
-- 在 `psql` 提示符下，执行以下 SQL 命令
-- synapsedb是新的数据库名称，database_user是之前使用的数据库用户名
CREATE DATABASE synapsedb
    WITH OWNER = database_user
    ENCODING = 'UTF8'
    LC_COLLATE = 'C'
    LC_CTYPE = 'C'
    TEMPLATE = template0;
    
`\q`退出

中文搜索需要启用 Zhparser 分词：

# 再次进入 `psql` 提示符，并切换到新创建的数据库：
psql -U database_user -d synapsedb
-- 在 `psql` 提示符下，执行以下 SQL 命令来创建zhparser扩展和配置：
CREATE EXTENSION IF NOT EXISTS zhparser;
-- “chinese”是一个自定义名称，后续将用到
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
-- 在 event_search 表中添加 chinese_vector 列，用于存储中文分词后的向量
ALTER TABLE event_search ADD COLUMN IF NOT EXISTS chinese_vector tsvector;
-- 对已有数据进行中文分词处理
UPDATE event_search SET chinese_vector = to_tsvector('chinese', vector::text);
-- 为中文列创建 GIN 索引
CREATE INDEX CONCURRENTLY event_search_chinese_vector_idx ON event_search USING GIN (chinese_vector)

-- 退出交互命令

删除上述创建的数据库容器（数据已映射到本地）：docker rm pgzhparser

使用docker run命令初始化synapse的homeserver.yaml 文件，自动生成以下参数：

log_config：日志格式
registration_shared_secret：共享密钥
macaroon_secret_key：
form_secret：
signing_key_path：

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

修改homeserver.yaml配置文件

参考文档：Configuration Manual - Synapse

编排docker-compose：

如果使用Zhparser，下载包含中文搜索的search.py，注意这个脚本可能在项目开发中改动，可以监控这个API，随时更新脚本
推荐下载密码提供程序模块（通常用来桥接其他聊天工具）：matrix-synapse-shared-secret-auth

services:
  pgzhparser:
    image: abcfy2/zhparser:17
    container_name: pgzhparser
    restart: unless-stopped
    # ports:
    #   - "5503:5432"
    environment:
      POSTGRES_USER: 上一步创建的数据库账号
      POSTGRES_PASSWORD: 上一步创建的数据库密码
      POSTGRES_DB: postgres
      PGDATA: /var/lib/postgresql/data
    volumes:
      - /root/pgzhparser/data:/var/lib/postgresql/data
    network_mode: host
    # network_mode: bridge
  
  synapse:
    image: docker.io/matrixdotorg/synapse:latest
    container_name: synapse
    restart: unless-stopped
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
      - UID=0
      - GID=0
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/data
      - /root/ssl/your_domain.key:/ssl/your_domain.key:ro
      - /root/ssl/your_domain.cer:/ssl/your_domain.cer:ro
      # 映射上一节下载的自定义搜索脚本
      - ./py_config/search.py:/usr/local/lib/python3.11/site-packages/synapse/storage/databases/main/search.py
      # 映射上一级下载的密码提供程序
      - ./py_config/shared_secret_authenticator.py:/usr/local/lib/python3.11/site-packages/shared_secret_authenticator.py
      # .. or you may split this between different storage points
      # - /path/to/ssd:/data/uploads
      # - /path/to/large_hdd:/data/media
    network_mode: host
    # network_mode: bridge
    depends_on:
      - pgzhparser
    # ports:
    #   - 8228:8448
    #   - 8008:8008
    #   - 8413:8413
    healthcheck:
      disable: true

  alist:
      image: 'xhofe/alist:latest'
      container_name: alist
      volumes:
          - /root/alist/data:/opt/alist/data
          - /root:/backupsync
      # ports:
      #     - '5244:5244'
      # network_mode: bridge
      network_mode: host
      environment:
          - PUID=0
          - PGID=0
          - UMASK=022
          - TZ=Asia/Shanghai
      restart: unless-stopped

其他推荐的组件：

synapse-admin，synapse的管理平台，集中了比较常用的admin_api和简单的UI界面。
coturn，用来做1:1通话（需要服务器有公网IP，或者使用cloudflare turn），新的MAtrix 2.0将原生的MatrixRTC取代。
element-call，MatrixRTC的实现，Element X客户端上将取代cotun和Jitsi 音视频会议，安装教程参考文章：Matrix 安装 Element Call 加密通话组件教程。
baibot，matrix上流行的AI聊天机器人，支持文本、语音和图片生成，暂不支持文件和图片识别。
matrix_chatgpt_bot，另一款AI聊天机器人，配置相对简单，适合中文用户，支持图片识别，不支持语音。
Maubot，插件平台，支持许多机器人插件，例如rss、webhook，在这里可以找到插件列表：Maubot Plugins
mautrix-telegram，桥接telegram的框架，类似的还有桥接twitter等。
element-web，网页客户端，还有桌面和移动版，为目前最流行的matrix 客户端。
postmoogle，将matrix作为电子邮局，在matrix上收发邮件。
matrix-registration，一个简单的web程序，用于邀请注册（目前移动客户端缺少支持邀请注册而element-web对手机浏览器没有适配）。
matrix-authentication-service，MAS是 Matrix身份验证程序，支持使用第三方社交登录或单点登录Matrix，未来还可以支持二维码和验证码等。

启动服务：

# 在docker compse所在的文件夹
docker compose up -d
# 检查一下日志有没有错误
docker logs -f synapse
# 如果出现错误，停止服务，根据错误进行修正
docker compose down

Matrix服务使用指南

管理员账号创建（两种方式）

在element-web等客户端注册账号（需要配置中启用注册），然后进行数据库将账号指定为管理员：

docker exec -it pgzhparser bash
psql -U database_user -d synapsedb
UPDATE users SET admin = 1 WHERE name = '@your_id:your_domain.com';
\q

使用预共享密钥创建管理员账号（需要配置有registration_shared_secret）：

# http://localhost:8008 为synapse的服务端地址
docker exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml --help

管理员账号可以用来管理用户、房间、媒体、服务器监控和性能优化等，可以用Synapse-Admin这个web端和Admin API - Synapse。

客户端推荐

matrix的支持客户端：Matrix.org - Clients，以下是推荐：

Element，最流行的全平台客户端，支持最多功能，例如线程消息列、视频会议、消息置顶等，新一代移动客户端 Element X 还支持滑动同步、二维码登录等 Matrix 2.0功能。
SchildiChat，Element的扩展分支，Element支持的都支持，可以在这里找到功能特点：SchildiChat-android/FEATURES.md
NerChat，也是Element的分支，有Web和Android端，为国内用户做了优化。
Cinny，专注在PC平台的客户端，UI更加简洁。
Neo - Matrix Messenger，在IOS设备上内置本地AI聊天和消息翻译的客户端，支持多账号。
alexispurslane/neo，：一个 Android Matrix 客户端，UI更接近Discord，手势优先的设计，支持自定义反应，项目处于早期 Alpha 阶段。

国内手机用户推荐Element及其分支，它支持通过保持在后台或使用第三方网关的方式接收消息通知。Element官版移动端首次登录或默认连接matrix.org服务器，有较长的超时响应，然后可以改为自己的服务器。

注册保护

根据服务端配置，有三种方式注册用户：

SSH终端用预共享密钥注册（synapse）：

# synapse 注册新用户
# http://localhost:8008 为synapse的服务端地址
docker exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml --help
# dendrite 注册新用户
docker exec -it dendrite /usr/bin/create-account -config /etc/dendrite/dendrite.yaml -username xxx

使用admin_api注册：注册用户 - Synapse，可以在Synapse-Admin进行。
在客户端注册，需要在配置中启用注册功能，为防滥用，有以下几种配置方式：
- 邮箱验证，需要有可以发件的smtp邮箱，以及正则表达式限制可注册的邮箱域名。
- captcha，谷歌的注册验证码，国内不可访问，
- Registration tokens，邀请码，启用registration_requires_token并在admin_api创建令牌，在移动端不可用。
- 隐私策略（Privacy Policy），要求用户同意条款才能注册和收发消息。

发送通知测试：https://element-hq.github.io/synapse/latest/admin_api/server_notices.html

curl -X  -v POST "https://matrix.your_domain.com:8443/_synapse/admin/v1/send_server_notice" \
     -H "Authorization: Bearer syt_Z2Fs_qzgGUPbSiCunXXLaJKrT_0xFdnM" \
     -H "Content-Type: application/json" \
     -d '{"user_id": ""@youername:your_domain.com", "content": {"msgtype": "m.text", "body": "欢迎来到我们的服务器！"}}'

服务端自动运维

更新服务组件

docker compose -f /root/synapse/docker-compose.yaml pull
docker compose -f /root/synapse/docker-compose.yaml up -d
docker image prune -f

更新SSL证书（如果是手动方式创建的证书）

# 更新证书
docker run --rm -v "/root/ssl":/acme.sh -e CF_Token="xxx" --net=host  neilpang/acme.sh  --renew --force --dns dns_cf --ocsp --server letsencrypt   -d "*.your_domain.com"
# 安装证书
acme.sh --install-cert -d example.com \
--key-file       /path/to/keyfile/in/nginx/key.pem  \
--fullchain-file /path/to/fullchain/nginx/cert.pem \
--reloadcmd     "service nginx force-reload"
# 重启synapse
docker restart synapse
# 重载nginx
service nginx force-reload

备份数据库

定时备份数据库

使用pg_dumpall热备份整个 PostgreSQL 实例中的所有数据库

# 对数据库进行热备份并映射到外部目录
docker exec pgzhparser pg_dumpall -h synapsedb | gzip -c > /root/backup/pgzhparser_backup.sql.gz

可选的备份方式：BorgBackup -- 基于命令行的增量备份工具（冷备份，需要先停止容器）
可选的备份方式：用postgres数据库的WAL 日志进行增量备份

定时任务脚本

在/root/cron目录创建文件: vim mycron
粘贴上述脚本任务（分别在每天04:00、每天08:00，每88天执行）

# 每天 08:00 更新服务组件
0 4 * * * cd /root/synapse && docker compose pull && docker compose up -d && docker image prune -f

# 每天 04:00 备份数据库
0 8 * * * docker exec pgzhparser pg_dumpall -h synapsedb | gzip -c > /root/backup/pgzhparser_backup.sql.gz

# 每88天更新SSL证书
0 0 */88 * * docker run --rm -v "/root/ssl":/acme.sh -e CF_Token="xxx" --net=host neilpang/acme.sh --renew --force --dns dns_cf --ocsp --server letsencrypt -d "*.your_domain.com" && acme.sh --install-cert -d example.com --key-file /path/to/keyfile/in/nginx/key.pem --fullchain-file /path/to/fullchain/nginx/cert.pem --reloadcmd "service nginx force-reload" && docker restart synapse && service nginx force-reload

导入到crontab: crontab mycron
确认导入成功: crontab -l

异地同步备份

使用Alist，Alist的使用参考 AList文档。

映射matrix服务套件及其备份数据的目录（见上）
在Alist上创建管理用户
在Alist中添加本地存储挂载路径
记得关闭访客账号以及对数据目录进行元信息加密

在其他服务器（如本地NAS）实时同步VPS数据

通过Alist的WebDAV或S3功能
同步的数据包括：
- 各个容器服务映射到磁盘空间的静态文件
- docker-compse文件和定时任务脚本
- 数据库备份文件

服务端性能优化

清除无人值守的房间：synapse-admin里面删一下
设置消息保留策略，不需要永久保留的房间可以单独设置短一些：Message Retention Policies - Synapse
单独设计房间的消息过期时间：Message Retention Policies - Synapse
清除房间历史记录：Purge History - Synapse
按用户|房间|大小|时间清理媒体文件：Media - Synapse
清除远程用户设备列表的缓存：Useful SQL for Admins - Synapse
使用工具压缩数据库：matrix-org/rust-synapse-compress-state: A tool to compress some state in a Synapse instance's database
homeserver.yaml 中有关优化的配置：

redaction_retention_period ——编辑事件的保留期
caches——指定较小的缓存
thumbnail_sizes——限制缩略图生成
media_retention——媒体文件的保留期
url_preview_url_blacklist——关闭或限制部分域名的url预览生成

标签： Matrix 自托管

作者：gal

日期：2025年05月03日