简介

Matrix 是一种开源的通信协议，可以根据应用需求和场景自行搭建

服务器要求

只本地聊天

性能要求：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

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

代码块

language	shell

# 允许外网访问指定端口
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

2、修改SSH端口（强烈推荐）

代码块

language	shell

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

3、安装Docker和Docker Compose环境

安装 Docker：Ubuntu | Docker Docs
安装 Compose：Install the Compose plugin | Docker Docs

设置docker开机自启：

代码块

language	shell

systemctl enable docker.service

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

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

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

有三种情况下需要使用反向代理：

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

代码块

language	shell

apt update
apt install nginx

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

代码块

language	nginx

# 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配置并重载：

代码块

language	shell

nginx -t
systemctl reload nginx

如果是家庭 NAS

确定家庭网络是否有公网 IP，如果没有则需要做内网穿透
如果有公网IP，则需要：
- 路由器上开启端口转发，如果路由器使用桥接模式，还需要在光猫上开启端口转发（或DNZ）
- 在路由器或NAS上安装DDNS服务，将公网IP定时上报给DNS服务商。
- 在NAS上安装证书并定时更新，参考上一节

安装 Matrix 服务

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

用docker创建数据库

中国推荐用 pgzhparser，包含中文分词的 postgres 数据库。synapse不原生支持中文搜索，具体参考博文：给 Matrix Synapse 添加中文搜索。

代码块

language	shell

# 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）：

代码块

language	shell

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 分词：

代码块

language	sql

# 再次进入 `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：

代码块

language	shell

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

代码块

language	yaml

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，未来还可以支持二维码和验证码等。

启动服务

代码块

language	shell

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

Matrix 服务使用指南

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

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

代码块

language	shell

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）：

代码块

language	shell

# 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，最流行的全平台客户端，支持最多功能，例如线程消息列、视频会议、消息置顶等，新一代移动客户端 Element X 还支持滑动同步、二维码登录等 Matrix 2.0功能。

SchildiChat，Element的扩展分支，Element支持的都支持，可以在这里找到功能特点：SchildiChat

SchildiChat，Element的扩展分支，Element支持的都支持，可以在这里找到功能特点：SchildiChat-android/FEATURES.md

NerChat，也是Element的分支，有Web和Android端，为国内用户做了优化。
Cinny，专注在PC平台的客户端，UI更加简洁。

NerChat，也是 Element 的分支，有 Web 和 Android 端，为国内用户做了优化。
Cinny，专注在 PC 平台的客户端，UI 更加简洁。
Neo - Matrix

Messenger，在IOS设备上内置本地AI聊天和消息翻译的客户端，支持多账号。

Messenger，在 IOS 设备上内置本地AI聊天和消息翻译的客户端，支持多账号。
alexispurslane/

neo，：一个

neo：一个 Android Matrix

客户端，UI更接近Discord，手势优先的设计，支持自定义反应，项目处于早期

客户端，UI 更接近 Discord，手势优先的设计，支持自定义反应，项目处于早期 Alpha 阶段。

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

注册保护

根据服务端配置，有三种方式注册用户：SSH终端用预共享密钥注册（synapse）：

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

代码块

language	shell

# 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

Plain text
使用admin2、使用admin_api注册：注册用户 - Synapse，可以在Synapse-Admin进行。

在客户端注册，需要在配置中启用注册功能，为防滥用，有以下几种配置方式：

邮箱验证，需要有可以发件的smtp邮箱，以及正则表达式限制可注册的邮箱域名。

Synapse，可以在 Synapse-Admin 进行。

3、在客户端注册，需要在配置中启用注册功能，为防滥用，有以下几种配置方式：

邮箱验证，需要有可以发件的 smtp 邮箱，以及正则表达式限制可注册的邮箱域名。
captcha，谷歌的注册验证码，国内不可访问，
Registration

tokens，邀请码，启用registration

tokens，邀请码，启用 registration_requires_

token并在admin_api创建令牌，在移动端不可用。

token 并在 admin_api 创建令牌，在移动端不可用。
隐私策略（Privacy Policy），要求用户同意条款才能注册和收发消息。

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

代码块

language	shell

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": "欢迎来到我们的服务器！"}}'

Plain text

服务端自动运维

更新服务组件

代码块

language	shell

docker compose -f /root/synapse/docker-compose.yaml pull


docker compose -f /root/synapse/docker-compose.yaml up -d


docker image prune -f

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

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

代码块

language	shell

# 更新证书


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

Plain text

备份数据库

定时备份数据库1、定时备份数据库

使用pg_dumpall热备份整个

PostgreSQL 实例中的所有数据库

PostgreSQL 实例中的所有数据库

代码块

language	shell

# 对数据库进行热备份并映射到外部目录


docker exec pgzhparser pg_dumpall -h synapsedb | gzip -c > /root/backup/pgzhparser_backup.sql.gz

Bash

可选的备份方式：BorgBackup -- 基于命令行的增量备份工具（冷备份，需要先停止容器）

可选的备份方式：用postgres数据库的WAL

可选的备份方式：用 postgres 数据库的 WAL 日志进行增量备份

定时任务脚本2、定时任务脚本

在 /root/

cron目录创建文件

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

代码块

language	shell

# 每天 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

Plain text

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

异地同步备份

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

映射matrix服务套件及其备份数据的目录（见上）

在Alist上创建管理用户
在Alist中添加本地存储挂载路径

在 Alist 上创建管理用户
在 Alist 中添加本地存储挂载路径
记得关闭访客账号以及对数据目录进行元信息加密

在其他服务器（如本地NAS）实时同步VPS数据
通过Alist的WebDAV或S3功能

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

通过 Alist 的 WebDAV 或 S3 功能
同步的数据包括：
- 各个容器服务映射到磁盘空间的静态文件
- docker-

compse文件和定时任务脚本

- compse 文件和定时任务脚本
- 数据库备份文件

服务端性能优化

清除无人值守的房间：synapse1、清除无人值守的房间：synapse-admin里面删一下admin 里面删一下

设置消息保留策略，不需要永久保留的房间可以单独设置短一些：Message 2、设置消息保留策略，不需要永久保留的房间可以单独设置短一些：Message Retention Policies - Synapse单独设计房间的消息过期时间：Message

3、单独设计房间的消息过期时间：Message Retention Policies - Synapse清除房间历史记录：Purge

4、清除房间历史记录：Purge History - Synapse

按用户5、按用户|房间|大小|时间清理媒体文件：Media 清理媒体文件：Media - Synapse清除远程用户设备列表的缓存：Useful

6、清除远程用户设备列表的缓存：Useful SQL for Admins - Synapse

使用工具压缩数据库：matrix7、使用工具压缩数据库：matrix-org/rust-synapse-compress-state: A tool to compress some state in a Synapse instance's databasehomeserver

8、homeserver.yaml 中有关优化的配置：

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

目录

空间快捷链接

页面树结构

版本比较

旧版本 1

新版本 2

标识

简介

服务器要求

域名配置

服务器环境配置

VPS环境配置

安装 Matrix 服务

用docker创建数据库

初始化

修改 homeserver.yaml 配置文件

编排docker-compose：

其他推荐的组件

启动服务

Matrix 服务使用指南

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

客户端推荐

注册保护

服务端自动运维

更新服务组件

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

备份数据库

异地同步备份

服务端性能优化

空间快捷链接

页面树结构

页面历史记录

版本比较

旧版本 1

新版本 2

标识

简介

服务器要求

域名配置

服务器环境配置

VPS环境配置

安装 Matrix 服务

用docker创建数据库

初始化

修改 homeserver.yaml 配置文件

编排docker-compose：

其他推荐的组件

启动服务

Matrix 服务使用指南

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

客户端推荐

注册保护

服务端自动运维

更新服务组件

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

备份数据库

异地同步备份

服务端性能优化