记录一次搭建Matrix，使用Ansible搭建Synapse服务端+Element Web/Cinny客户端-THsInk

QQ群频繁被封，不少人开始寻求替代方案。我之前也看过几个自托管聊天室，但动力不足，没精力尝试。今天想起老外那边最近流行Matrix ，部署一个试一下。

Matrix 是一个开源的即时通讯协议和网络平台，旨在提供去中心化、安全、互操作的通信方式。它允许用户在不同的服务器和应用之间进行即时消息、语音通话、视频通话等多种形式的交流，而不依赖于单一的集中式服务。Matrix 的核心优势在于其去中心化的架构，用户可以选择自己信任的服务器，确保更大的隐私和控制权。

本次使用https://github.com/spantaleev/matrix-docker-ansible-deploy ，准备了控制端(ansible)、服务端(synapse)、客户端(element-web/cinny)三个服务器。参考本文时请保持质疑，这不是教程，只是记录我部署和折腾的过程方便以后查看，我自己也是第一次使用！尤其是，我根本没用过Ansible！

1. 简介

理解ansible关键概念，点击查看

Ansible

一个开源的自动化工具，用于配置管理、应用部署、云服务编排等 IT 自动化任务
使用 Python 开发，采用 YAML 语法编写任务

Inventory (清单)

定义要管理的主机列表和主机组
可以是静态文件(通常是 /etc/ansible/hosts)或动态生成
支持定义主机变量和组变量

Playbook (剧本)

Ansible 的配置、部署和编排语言
使用 YAML 格式编写
描述了一系列要在远程主机上执行的任务

Task (任务)

Playbook 中的基本执行单元
定义一个具体的操作，如安装包、复制文件等
每个任务会调用一个 Ansible 模块

Module (模块)

Ansible 的功能执行单元
内置了大量模块，如:
- apt/yum: 包管理
- copy: 文件复制
- service: 服务管理
- template: 模板处理

Role (角色)

将 Playbook 组织成可重用的组件
包含完成特定功能所需的所有文件和配置
标准结构包含: tasks、handlers、files、templates、vars、defaults、meta

Handler (处理器)

特殊的任务，只在被通知时执行
通常用于服务重启等操作
由 task 通过 notify 触发

Variable (变量)

可在 Playbook 中使用的动态值
来源多样: inventory、playbook、role、命令行等
支持不同优先级和作用域

Fact (事实)

通过 ansible 自动收集的目标主机信息
包括操作系统、硬件、网络等系统信息
可在 Playbook 中使用这些信息做条件判断

Control Node (控制节点)

安装 Ansible 的主机
负责执行自动化任务
通过 SSH 连接管理其他节点

Managed Node (被管理节点)

被 Ansible 管理的远程主机
一般只需要支持 SSH 和 Python
不需要安装专门的客户端软件

插件 (Plugin)

扩展 Ansible 功能的组件
类型包括:
- Connection: 连接插件
- Callback: 回调插件
- Filter: 过滤器插件
- 等等

Collection (集合)

Ansible 内容的分发格式
包含 playbook、角色、模块和插件
可通过 ansible-galaxy 管理

Vault (保险库)

用于加密敏感数据
可加密整个文件或单个变量
保护密码、密钥等敏感信息

1. 配置ssh key

如果直接使用root密码登录可以跳过。

在Ansible控制机上放公钥和私钥，目录结构：

~/.ssh/
  ├── matrix_server_key      # Matrix服务器私钥
  ├── matrix_server_key.pub  # Matrix服务器公钥
  └── config                 # SSH配置文件

SSH配置文件(~/.ssh/config)示例:

Host matrix-server
    HostName matrix.yourdomain.com
    User root
    IdentityFile ~/.ssh/matrix_server_key
    IdentitiesOnly yes

编辑添加公钥私钥：

# 创建目录(如果不存在)
mkdir -p /root/.ssh

# 设置正确的权限
chmod 700 /root/.ssh

# 现在创建/编辑密钥文件
vim /root/.ssh/matrix_server_key

# 设置密钥文件权限
chmod 600 /root/.ssh/matrix_server_key
设置公钥
vim /root/.ssh/matrix_server_key.pub
chmod 644 ~/.ssh/matrix_server_key.pub

如果ssh key 有密码，运行playbook的时候会提示输入，如果没有，点击查看折叠框内。

如果ssh key还有密码，使用ssh-agent来管理密钥和密码：

# 启动ssh-agent
eval $(ssh-agent)

# 添加密钥到ssh-agent
ssh-add ~/.ssh/matrix_server_key

# 此时会要求输入一次密码，之后就不需要再输入了
# 将ssh-agent启动命令添加到~/.bashrc：
echo 'eval $(ssh-agent) > /dev/null' >> ~/.bashrc

如果重启服务器后需要重新执行:

ssh-add ~/.ssh/matrix_server_key

测试SSH连接:

ssh -i ~/.ssh/matrix_server_key root@your_ip

2. 安装Ansible(控制端)

我在一个1H1G30G的小鸡安装。用配置更高的服务器或本地运行应该能提高效率，我这台在运行剧本时经常cpu100%

apt update
apt install ansible python3 python3-pip git pwgen just -y

目录结构

~/matrix/
  ├── matrix-docker-ansible-deploy/    # playbook 目录
  ├── backups/                         # 配置文件备份
  └── logs/                           # 部署日志

git项目

git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
cd matrix-docker-ansible-deploy

编辑配置

# 创建配置目录
mkdir -p inventory/host_vars/matrix.yourdomain.com/

# 复制示例配置
cp examples/vars.yml inventory/host_vars/matrix.yourdomain.com/vars.yml

# 编辑主机配置文件
cp examples/hosts inventory/hosts

编辑 inventory/hosts, 其中修改ansible_ssh_private_key_file的值为ssh私钥位置

[matrix_servers]
matrix.yourdomain.com ansible_host=YOUR_SERVER_IP ansible_ssh_user=root ansible_ssh_private_key_file=~/.ssh/authorized_keys/matrix_server_key

打开编辑 inventory/host_vars/matrix.yourdomain.com/vars.yml,

以下是需要修改的关键配置:

# 基础域名配置
matrix_domain: example.com
matrix_server_fqn_matrix: "matrix.{{ matrix_domain }}"

# 用pwgen -s 64 1 生成
matrix_homeserver_generic_secret_key
# 用pwgen -s 32 1 生成
devture_postgres_connection_password

# 填写邮箱用于申请ssl
traefik_config_certificatesResolvers_acme_email

以下是我添加的配置

# 禁用 coturn(音视频通话)
matrix_coturn_enabled: false

# 禁用默认安装的element客户端，我要分离部署
matrix_client_element_enabled: false

# 禁用内置邮件服务，通过smtp发送邮件
matrix_mailer_enabled: false
exim_relay_sender_address: "another.sender@example.com"
exim_relay_relay_use: true
exim_relay_relay_host_name: "mail.example.com"
exim_relay_relay_host_port: 587
exim_relay_relay_auth: true
exim_relay_relay_auth_username: "another.sender@example.com"
exim_relay_relay_auth_password: "some-password"

# 填写邮箱用于申请ssl
traefik_config_certificatesResolvers_acme_email

# 允许注册，但需要邀请码
matrix_synapse_enable_registration: true
matrix_synapse_registration_requires_token: true

# 启用 Synapse Admin,可以生成邀请码管理用户等，链接为matrix.example.com/synapse-admin/
matrix_synapse_admin_enabled: true

此折叠框内是我添加的更多可选配置，点击查看

限制上传大小

# 限制最大上传大小之类，还可以添加数据库备份等设置
matrix_synapse_max_upload_size_mb: 10

管理机器人,我使用pantalaimon不能正常运行，不知道为什么

matrix_bot_draupnir_enabled: true
matrix_bot_draupnir_access_token: "修改"  # 在无痕浏览器打开element web获取后，不要登出，直接关闭窗口
matrix_bot_draupnir_management_room: "修改"

chatgpt机器人baibot

matrix_bot_baibot_enabled: true
matrix_bot_baibot_config_user_password: '生成强密码'
matrix_bot_baibot_config_user_encryption_recovery_passphrase: '编写'
matrix_bot_baibot_config_persistence_session_encryption_key: '生成强密码'
matrix_bot_baibot_config_persistence_config_encryption_key: '生成强密码'
matrix_admin: '@l1angth6:{{ matrix_domain }}'

Matrix Corporal,用来限制用户权限，比如创建房间。

此处内容已隐藏，请评论后刷新页面查看.

Matrix Corporal添加允许私聊管理员配置，未测试

此处内容已隐藏，请评论后刷新页面查看.

在运行 playbook 之前,需要配置以下 DNS 记录:

# A 记录
matrix    IN A      YOUR_SERVER_IP
element   IN A      YOUR_SERVER_IP  # 如果需要 Element Web 客户端

3. 部署Synapse(服务端)

在服务端synapse安装：

apt install python3 python3-pip sudo git -y

以下操作都在ansible控制端进行：

安装just：

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/local/bin

# 检查是否安装成功
just --version

启动安装步骤:

# 更新 ansible roles
just roles
# 安装
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start

通过ansible添加管理员用户：

just register-user <your-username> <your-password> <admin access: yes or no>

# Example: `just register-user john secret-password yes`

# 或者使用
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=admin password=YOUR_STRONG_PASSWORD admin=yes' --tags=register-user

4. 部署element-web 或 cinny 等(客户端)

安全提示：不要使用和matrix同一个主域名以避免出现跨域安全问题。

我最开始尝试使用ansible单独安装客户端，发现并不怎么方便。直接安装配置客户端非常简单，因此我还是直接用docker dompose安装了。

4.1 element-web

我觉得这个客户端最大的问题是没有手机网页端适配。

docker-compose.yml

services:
  element-web:
    image: vectorim/element-web:latest
    volumes:
      - ./config.json:/app/config.json
    restart: unless-stopped

config.json, 比如要限制home server等。如果要默认配置可以不添加config文件

{
    "default_server_config": {
        "m.homeserver": {
            "base_url": "https://matrix.example.com",
            "server_name": "example.com"
        }
    },
    "brand": "Element",
    "default_country_code": "CN",
    "disable_custom_urls": true,
    "disable_guests": true,
    "disable_login_language_selector": false,
    "disable_3pid_login": true,
    "default_federate": false,
    "default_theme": "light",
    "room_directory": {
        "servers": [
            "example.com"
        ]
    },
    "enable_presence_by_hs_url": {
        "https://matrix.org": false,
        "https://matrix-client.matrix.org": false
    },
    "setting_defaults": {
        "breadcrumbs": true,
        "MessageSearch": true
    },
    "features": {
        "feature_thread": true,
        "feature_location_share": false,
        "feature_voice_messages": false
    },
    "labs_group": {
        "enableNewRoomList": true
    },
    "showDevTools": false,
    "auto_join_rooms": [
        "!WdXUlsYTkFWaSPDyKK:example.com"
    ]
}

4.2 cinny

这个客户端最大的问题是没有多语言适配，自定义项麻烦。对于另一些人来说，消息通知也是问题。

docker-compose.yml

services:
  cinny:
    image: ghcr.io/cinnyapp/cinny:latest
    container_name: cinny
    restart: unless-stopped
    volumes:
      - ./config.json:/app/config.json

config.json

{
  "defaultHomeserver": 0,
  "homeserverList": [
    "matrix.example.com"
  ],
  "allowCustomHomeservers": false,

  "featuredCommunities": {
    "openAsDefault": true,
    "spaces": [
      "#main:example.com"
    ],
    "rooms": [
      "!DhWOamsXYxbaYISjiF:example.com"
    ],
    "servers": ["matrix.example.com"]
  },

  "roomDirectory": {
    "enabled": true
  },
  "spaceDirectory": {
    "enabled": true
  },

  "hashRouter": {
    "enabled": false,
    "basename": "/"
  },

  "default_routes": {
    "after_login": "#main:example.com"
  },

  "auto_join": {
    "spaces": [
      "#main:example.com"
    ]
  }
}

5. 其他维护

版本控制建议

cd matrix-docker-ansible-deploy
git init
git add inventory/
git commit -m "Initial matrix config"

备份建议

定期备份以下内容:

整个 playbook 目录
SSH 密钥
inventory 配置

可以创建简单的备份脚本:

#!/bin/bash
BACKUP_DIR=~/matrix/backups
DATE=$(date +%Y%m%d)

# 备份配置
tar czf $BACKUP_DIR/matrix-config-$DATE.tar.gz matrix-docker-ansible-deploy/inventory/

# 备份 SSH 密钥
cp ~/.ssh/id_ed25519* $BACKUP_DIR/

日常使用建议

更新 playbook:

cd matrix-docker-ansible-deploy
git pull
ansible-galaxy install -r requirements.yml --force

2. 修改配置后:

# 保存配置变更
git add inventory/
git commit -m "Update configuration"

# 应用配置
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

6. 迁移备份

刚搭建完成后发现推送了更新2024-11-23：（向后兼容性中断）剧本现在默认为 Valkey，而不是 KeyDB。

需要另行处理，懒得搞了，有时间再说吧。

其他

搭建完成后发现对我来说实际用途并不大。并且在matrix这个主要目的为去中心化的项目上添加各种管理和限制是有些麻烦和水土不服的。现在确实有成品解决方案，但热度太低，浪费了我比较多时间。

另外，matrix的管理机器人和gpt等机器人设计及其反人类，完全不是面向用户设计的。如果你习惯用discord机器人应该能感受到。

总之我折腾部署这个项目本来是打算实际使用的，现在看来可能大概率是要吃灰了。虽然我花了大量时间，熟悉了多项流程，解决了多个问题，让这个项目能在我们的需求下大致实际应用了，但用户并不买单——你不能出于想要解决监管问题简单的期望能用matrix替代discord或是qq群之类。这可能也是很多自建im的人遇到的问题。

文章版权归作者所有，未经允许请勿转载。

THE END