简介
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为例：
# 允许外网访问指定端口 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端口（强烈推荐）
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开机自启：
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 端口，反向代理不是必须的，但如果想要区分多个端口做不同用途（例如一个用于跨域名联邦一个用于客户端）则反向代理是一种方式。
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上安装证书并定时更新，参考上一节
安装 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 服务器，有较长的超时响应，然后可以改为自己的服务器。
注册保护
根据服务端配置，有三种方式注册用户：
1、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 |
2、使用admin_api注册：注册用户 - Synapse，可以在 Synapse-Admin 进行。
3、在客户端注册，需要在配置中启用注册功能，为防滥用，有以下几种配置方式：
- 邮箱验证，需要有可以发件的 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 |
备份数据库
1、定时备份数据库
- 使用pg_dumpall热备份整个 PostgreSQL 实例中的所有数据库
# 对数据库进行热备份并映射到外部目录 docker exec pgzhparser pg_dumpall -h synapsedb | gzip -c > /root/backup/pgzhparser_backup.sql.gz |
- 可选的备份方式：BorgBackup -- 基于命令行的增量备份工具（冷备份，需要先停止容器）
- 可选的备份方式：用 postgres 数据库的 WAL 日志进行增量备份
2、定时任务脚本
- 在 /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
异地同步备份
1、使用 Alist，Alist 的使用参考 AList 文档。
- 映射matrix服务套件及其备份数据的目录（见上）
- 在 Alist 上创建管理用户
- 在 Alist 中添加本地存储挂载路径
- 记得关闭访客账号以及对数据目录进行元信息加密
2、在其他服务器（如本地 NAS ）实时同步 VPS 数据
- 通过 Alist 的 WebDAV 或 S3 功能
- 同步的数据包括：
- 各个容器服务映射到磁盘空间的静态文件
- docker-compse 文件和定时任务脚本
- 数据库备份文件
服务端性能优化
1、清除无人值守的房间：synapse-admin 里面删一下
2、设置消息保留策略，不需要永久保留的房间可以单独设置短一些：Message Retention Policies - Synapse
3、单独设计房间的消息过期时间：Message Retention Policies - Synapse
4、清除房间历史记录：Purge History - Synapse
5、按用户|房间|大小|时间 清理媒体文件：Media - Synapse
6、清除远程用户设备列表的缓存：Useful SQL for Admins - Synapse
7、使用工具压缩数据库：matrix-org/rust-synapse-compress-state: A tool to compress some state in a Synapse instance's database
8、homeserver.yaml 中有关优化的配置：
- redaction_retention_period ——编辑事件的保留期
- caches——指定较小的缓存
- thumbnail_sizes——限制缩略图生成
- media_retention——媒体文件的保留期
- url_preview_url_blacklist——关闭或限制部分域名的url预览生成