办公场景自建Matrix服务器：Synapse+Element私有化部署指南

1. 项目概述与方案选型

1.1 办公场景下为什么要自建 Matrix 服务器

先说说这个项目到底解决了什么问题。办公室里装一套即时通讯工具，表面上不难，真正落地的时候你会发现一堆绕不开的坎：公司内部的数据能不能不出内网、聊天记录归谁管、部门隔离怎么做、新人入职怎么批量开账号、文件传输有没有大小限制，还有最现实的一点——Saas 产品按人头收费，一年下来几十上百号人的费用真不便宜。

Matrix 是这几年开源通讯领域绕不开的一个协议，它最大的特点是开放和去中心化。用户之间的聊天记录不归某一个平台独有，而是由一个个"房间"承载，每个房间可以在任意一台服务器上落地。Synapse 就是 Matrix 协议最成熟的服务器端实现，用 Python 写的，部署在 Ubuntu 上，配合 Element 这套客户端，就能拼出一个完整的私有化办公通讯平台。

这个方案适合谁？适合那种"数据必须留在自己手里"的中小团队、项目组、实验室，或者纯粹想给家里几台设备搭个内网聊天服务的折腾型选手。我不建议大几百人的企业用它替代企业微信或钉钉，管理后台和审批流差得远，但几十人以内、以技术协作和文件沟通为主的场景，Synapse 完全可以胜任。

1.2 为什么选 Synapse 而不选其他开源方案

选型的时候我对比过几个路线，现在的办公通讯开源方案其实不少，但各自的侧重点差别很大。

当时我选 Synapse 的核心理由是三点。第一，Matrix 协议本身是开放的，意味着以后想换服务器端实现（比如换 Dendrite），客户端可以无缝迁移，不会被绑死。第二，房间模型特别适合办公场景——一个项目一个房间，部门之间的隔离天然就能通过房间权限实现。第三，Element 客户端的体验已经相当接近主流商业 IM 了，大家切换过来的学习成本很低。

当然也要说句公道话，Synapse 不是省油的灯，Python 写的服务端在内存占用上确实偏大，官方也一直在推下一代实现 Dendrite，但论功能完整度、文档成熟度和踩坑资料的数量，Synapse 目前依然是自建 Matrix 服务器的首选。

2. 部署前的环境准备

2.1 硬件配置与 Ubuntu 版本选择

先说结论：一台 2 核 4G 内存的机器跑 Synapse，带三十人左右的日常办公完全够用。网上很多教程说 1G 内存就能跑，那是指纯实验环境，真上了办公场景，Element 客户端轮询、媒体文件转存、数据库连接池一起上来，1G 内存会频频触发 OOM。我实际部署的这台机器是 4 核 8G，日常负载很轻松，extra headroom 还能顺便跑个 coturn 转服务器。

操作系统建议直接上 Ubuntu 24.04 LTS，或者保守一点用 22.04 LTS。LTS 版本意味着五年的安全更新，对于要长期跑的服务来说这是底线。新装系统的话顺手确认一下 Python 版本，Synapse 目前要求 Python 3.11 以上，Ubuntu 24.04 自带的就是 3.12，不用额外折腾。

磁盘规划是个容易被忽略的坑。Matrix 的媒体文件（图片、文件、头像）默认都存在本地 media_store 目录里，日积月累非常占空间。建议单独给 /var/lib/matrix-synapse 分一个数据盘，或者至少确保所在分区有足够的余量。我见过有人把服务装在 20G 的系统盘上，跑了三个月磁盘 100%，整个服务直接瘫痪。

2.2 网络规划与基础系统配置

本地网络版的核心是"不出网"，所以网络规划要提前想清楚。首先给服务器设置一个静态内网 IP，比如 192.168.1.10，避免 DHCP 重新分配导致客户端连不上。其次要决定 server_name，这是 Matrix 世界里的身份标识，客户端登录的时候要填这个。没有公网域名的话可以直接用服务器的内网 IP 或者机器名，比如 office-server，只要保持整个局域网内统一就行。

系统层面的准备工作，我建议按这个顺序过一遍：

# 更新软件源并安装基础工具 sudo apt update && sudo apt upgrade -y sudo apt install -y curl gnupg lsb-release nginx # 设置时区，避免日志时间和实际时间对不上 sudo timedatectl set-timezone Asia/Shanghai # 确认主机名，建议改一个有意义的名字 sudo hostnamectl set-hostname office-server # 查看 IP，确认静态地址已生效 ip addr show

很多人部署完服务才发现日志时间不对、或者客户端连不上，很大一部分原因是宿主机的基础设置没弄干净。SSH 连不上的话，先确认 openssh-server 是否安装：

sudo apt install -y openssh-server sudo systemctl enable --now ssh

防火墙这块，如果公司内网本身有统一的出口管控，内网服务之间通常不用额外开防火墙；但如果你在服务器上启用了 ufw，记得放行 Synapse 和后续依赖的端口。我先说端口规划，后面配置的时候会对应上：

2.3 域名还是 IP：本地网络版的关键取舍

这里值得单独说一下。Matrix 协议设计上是面向公网的去中心化网络，server_name 通常是域名，比如 example.com。但本地网络版不需要对外提供联邦服务，因此有一个取巧但也完全合规的做法：server_name 直接写内网 IP 或者内网主机名。

选择的时候注意一点：server_name 写入配置之后，客户端和服务器之间的交互都会以它为基础。如果你以后可能把这个服务暴露到公网、或者要和其他 Matrix 服务器联邦互通，那 best practice 是用一个有 DNS 解析的域名。但如果确认一辈子只在局域网里跑，用 IP 当 server_name 最省事，省去了改配置的麻烦。唯一要提醒的是，Element 客户端在部分浏览器里对纯 IP 的 server_name 有些小脾气，比如密码存储策略会更保守，这个后面章节我会给解决办法。

3. 安装 Synapse 服务器的两种常用路径

3.1 官方 apt 仓库安装（推荐）

Synapse 官方提供了 Debian/Ubuntu 的 apt 仓库，这是我最推荐的方式——它把 Python 依赖、systemd 服务文件、默认配置模板都打包好了，升级也方便，不用自己维护一套 Python 虚拟环境。

# 添加官方仓库 sudo apt install -y apt-transport-https sudo curl -fsSL https://packages.matrix.org/debian/matrix-org.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/matrix-org.gpg echo "deb [signed-by=/usr/share/keyrings/matrix-org.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list # 安装 sudo apt update sudo apt install -y matrix-synapse-py3

安装过程中会提示输入 server_name 并选择是否上报匿名统计。server_name 就填我们在网络规划阶段确定的那个值，比如 office-server。如果安装时手滑填错了也没关系，后面改 homeserver.yaml 就行。apt 方式装好之后，synapse 用户、/etc/matrix-synapse 配置目录、/var/lib/matrix-synapse 数据目录都已经自动创建好了，省心不少。

3.2 pip 方式安装（适合喜欢完全掌控的环境）

如果你的服务器系统不是 Debian 系、或者想跑最新预发布版本，pip 方式也完全可行。核心思路是先用 venv 建独立 Python 环境，再把 Synapse 装进去，避免污染系统 Python。

# 安装 Python 虚拟环境工具和编译依赖 sudo apt install -y python3-venv python3-dev libffi-dev build-essential libssl-dev # 建目录和虚拟环境 sudo mkdir -p /opt/matrix-synapse sudo chown $USER:$USER /opt/matrix-synapse python3 -m venv /opt/matrix-synapse/env source /opt/matrix-synapse/env/bin/activate # 安装 Synapse pip install --upgrade pip pip install matrix-synapse

pip 装完之后，需要用官方提供的生成配置文件脚本手动初始化：

source /opt/matrix-synapse/env/bin/activate python -m synapse.app.homeserver \ --server-name office-server \ --config-path /opt/matrix-synapse/homeserver.yaml \ --generate-config \ --data-directory /opt/matrix-synapse/data \ --report-stats=no

这两种方式我实测下来，apt 版升级最省心，sudo apt upgrade就完事了；pip 版适合需要跑特定版本或者改源码的场景。个人建议生产环境一律走 apt。

3.3 数据库配置：为什么生产环境必须用 PostgreSQL

Synapse 默认用 SQLite，单文件数据库，零配置，跑测试完全没问题。但办公场景多人并发时，SQLite 的写锁会变成明显的瓶颈，尤其是存在大量事件写入的房间，检索会越来越慢。官方文档也明确说了生产环境用 PostgreSQL。

sudo apt install -y postgresql postgresql-contrib # 切换到 postgres 用户，创建 Matrix 专用账号和库 sudo -u postgres psql <<EOF CREATE USER matrix WITH PASSWORD '这里换成你自己的强密码'; CREATE DATABASE matrix ENCODING 'UTF8'; GRANT ALL PRIVILEGES ON DATABASE matrix TO matrix; EOF

然后在 homeserver.yaml 里把数据库配置改掉：

database: name: psycopg2 args: user: matrix password: 这里换成你自己的强密码 database: matrix host: localhost port: 5432 cp_min: 5 cp_max: 10

改完配置重启 Synapse 之前，建议先验证一下连接：

PGPASSWORD='这里换成你自己的强密码' psql -h localhost -U matrix -d matrix -c "SELECT version();"

看到 PostgreSQL 版本号就说明数据库通路没问题。这里有个细节，cp_min 和 cp_max 控制连接池大小，办公场景 5 到 10 足够，不用贪多，连接数太高反而给 PostgreSQL 增加无谓的开销。

4. 核心配置与本地化设置

4.1 homeserver.yaml 关键参数解读

安装完成后的核心工作就是改 homeserver.yaml，这个文件是 Synapse 的命脉。默认模板生成的配置往往偏保守或者偏公网场景，我们按本地网络版的需求逐项调整。

先看最重要的几个参数：

# 服务器标识，客户端登录时填这个名字 server_name: "office-server" # 监听配置：默认监听 8008，改为监听所有内网接口 listeners: - port: 8008 type: http bind_addresses: ['0.0.0.0'] tls: false x_forwarded: false resources: - names: [client, federation] compress: true # 本地网络版不需要联邦，关闭对外联系 enable_registration: false registration_shared_secret: "用 openssl rand -base64 48 生成一串" # 关闭联邦功能，防止内网服务器主动外连 federation_enabled: false

重点解释一下 registration_shared_secret 的作用。它是一把"注册签名密钥"，配合官方提供的register_new_matrix_user脚本，可以不用开放注册就能创建账号。这在办公场景下特别实用——不允许员工随便注册，但管理员又能随时批量开号。

监听地址配置成 0.0.0.0 是为了让局域网内其他设备能通过服务器 IP 访问 8008 端口。如果你只在服务器本机测试，用 127.0.0.1 也行。

4.2 启动服务并纳入 systemd 管理

apt 方式安装后，systemd 服务已经自动创建好了，服务名是matrix-synapse。改完配置直接:

sudo systemctl enable matrix-synapse sudo systemctl restart matrix-synapse sudo systemctl status matrix-synapse

看到active (running)就说明起服务了。验证服务是否正常，最直接的办法是请求一下健康检查接口:

curl http://localhost:8008/_matrix/client/versions curl http://localhost:8008/health

第一条命令返回一串 JSON，里面列出了客户端 API 支持的版本号；第二条命令返回{"status": "OK"}之类的健康状态。如果 curl 没反应，先看日志:

sudo journalctl -u matrix-synapse -f

如果是 pip 方式安装的，需要自己写 systemd 服务文件。我把常用的 unit 配置贴在下面，注意路径按实际安装位置调整：

[Unit] Description=Matrix Synapse After=network.target postgresql.service [Service] User=synapse Group=synapse WorkingDirectory=/opt/matrix-synapse EnvironmentFile=-/etc/default/matrix-synapse ExecStart=/opt/matrix-synapse/env/bin/python -m synapse.app.homeserver --config-path=/opt/matrix-synapse/homeserver.yaml Restart=on-failure RestartSec=5s [Install] WantedBy=multi-user.target

4.3 Element Web 客户端的部署方式

Matrix 官方推荐的 Web 客户端是 Element，用户打开浏览器输入地址就能用。它的部署方式很简单：把静态文件拉到 Nginx 的 web 目录，再做一个简单反代就行。

# 下载 Element Web 最新版，注意替换版本号 cd /var/www sudo wget https://github.com/element-hq/element-web/releases/download/v1.11.70/element-v1.11.70.tar.gz sudo tar -xzf element-v1.11.70.tar.gz sudo mv element-v1.11.70 element

然后写一个 Nginx 站点配置，把 /var/www/element 作为根目录，同时把 /_matrix 路径反向代理到本机的 Synapse 8008 端口：

server { listen 80; server_name office-server; root /var/www/element; index index.html; # Element 是单页应用，所有未命中路径都返回 index.html location / { try_files $uri $uri/ /index.html; } # Matrix 客户端 API 反向代理到 Synapse location /_matrix { 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; } }

为什么需要 Nginx？直接让用户访问 8008 端口其实也能用，但有三个问题：一是客户端 API 和 Web 静态资源混杂在同一个端口上，二是不方便控制上传大小，三是以后要加 HTTPS 证书时候没有入口。走一层 Nginx 反代，权限控制、限流、日志全部都统一了。

4.4 通过 Nginx 统一暴露 Synapse 与 Element

上面那段配置已经包含了反代，但还有个细节要处理：Element Web 默认的配置地址。Element 有个配置文件 config.json，可以指定它默认连接哪个 homeserver，这样用户在登录页就不用手动填服务器地址了。

sudo nano /var/www/element/config.json

典型配置如下：

{ "m.homeserver": { "base_url": "http://office-server:8008" }, "m.identity_server": { "base_url": "http://office-server:8008" }, "default_server_config": { "m.homeserver": { "base_url": "http://office-server:8008", "server_name": "office-server" } } }

如果 Element 是通过 Nginx 访问的同源路径（也就是浏览器地址是 http://office-server，而 API 也走同一主机的 /_matrix），base_url 可以留空字符串让浏览器自动用当前域名。但本地网络版经常出现"大家用 IP 访问"的情况，服务器名又是主机名，所以显式写上 base_url 最稳。

5. 办公场景落地配置细节

5.1 账号创建与注册策略

前面把 enable_registration 设成了 false，现在需要手动创建账号。官方提供了一个命令行工具：

# 进入虚拟环境（apt 方式服务端自带了） sudo -u matrix-synapse register_new_matrix_user \ -c /etc/matrix-synapse/homeserver.yaml \ -u zhangsan \ -p '初始密码' \ -a

这里有个小坑：register_new_matrix_user 这个命令在 apt 安装时默认放在 /usr/bin 下，但你要是用的自定义数据目录，注意-c参数一定要指向实际使用的配置文件，否则工具会拿着默认配置去读注册密钥，结果对不上数据库，报各种奇怪的错。

-a参数表示让这个用户成为管理员。管理员账号以后有什么用？在 Element 界面里可以管理所有房间、查看服务器状态、踢人、封号。办公场景建议至少创建两个管理员账号，一个日常用，一个留作应急备用，避免把鸡蛋放一个篮子里。

账号多了之后，逐个手工创建显然不现实。Synapse 提供了 admin API，支持通过 HTTP 调用创建用户。写个简单的批量脚本，从 Excel 或 CSV 里读姓名和工号，循环调用 API 就能实现批量开户：

# 先获取管理员 access_token curl -s http://localhost:8008/_matrix/client/v3/login \ -X POST \ -d '{"type":"m.login.password","user":"zhangsan","password":"初始密码"}' \ -H 'Content-Type: application/json' # 拿到 token 后批量创建用户 curl -s http://localhost:8008/_synapse/admin/v2/users/@lisi:office-server \ -X PUT \ -d '{"password":"初始密码","displayname":"李四","admin":false}' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json'

5.2 音视频通话少不了 TURN 服务器

这是最容易被人忽略的一块。Element 客户端之间的文字聊天走 Synapse 的 8008 端口就够了，但语音和视频通话走的是 WebRTC，需要一套 TURN 服务器来打洞和转发媒体流。不配 TURN 的话，很多在复杂网络环境下的办公室（多层 NAT、统一出口代理）会出现"能看到对方在线，一打电话就卡死"的情况。

coturn 是搭配 Synapse 最常用的 TURN 实现：

sudo apt install -y coturn

配置 /etc/turnserver.conf，关键配置如下：

listening-port=3478 tls-listening-port=5349 fingerprint lt-cred-mech use-auth-secret static-auth-secret=用 openssl rand -base64 32 生成 realm=office-server total-quota=300 stale-nonce=600

然后把这个 static-auth-secret 同步到 homeserver.yaml 的 turn 配置段：

turn_uris: - "turn:office-server:3478?transport=udp" - "turn:office-server:3478?transport=tcp" turn_shared_secret: "和 turnserver.conf 保持一致的那串密钥" turn_allow_guests: true

另外记得在防火墙里放行端口。很多办公室网络环境对 UDP 限制很严，NTP、QUIC 都受影响，WebRTC 恰恰主要走 UDP，所以一旦发现音视频质量差，先查 UDP 通不通。放行命令如下：

sudo ufw allow 3478/udp sudo ufw allow 3478/tcp sudo ufw allow 5349/udp sudo ufw allow 5349/tcp sudo ufw allow 49152:49200/udp

5.3 文件上传大小与媒体存储策略

办公场景离不开传文件，Element 默认上传限制是 50MB，这个数值在 Synapse 的配置里是max_upload_size，单位是字节。要放宽到 200MB，在 homeserver.yaml 里加一行：

max_upload_size: 200M

注意，Synapse 支持50M这种简写。但真正卡文件的通常是 Nginx 那一层，默认client_max_body_size只有 1MB，不配置的话大文件传一半会被 Nginx 直接断开连接。所以在 Nginx 的 server 块里加：

client_max_body_size 200m;

媒体文件存储路径是media_store_path，默认在数据目录下。建议定期用du -sh看看这个目录的占用，我跑了一个季度之后发现头像、截图、文档附件加起来已经接近 20GB，这个增长速度在办公场景是很正常的。

6. 常见问题与排查实录

6.1 日志查看与基础排查方法

Synapse 出问题，第一件事就是看日志。apt 装的服务日志走 systemd:

sudo journalctl -u matrix-synapse -n 200

同时还有一个独立的应用日志 homeserver.log，路径通常在 /var/log/matrix-synapse 下。这个日志会记录从客户端 API 请求到联邦事件处理的完整信息。调试的时候建议把日志级别临时调低，在 homeserver.yaml 里：

log_level: "DEBUG"

调试完记得改回 INFO，不然日志量会非常惊人，半天就能写满一个 G。

6.2 高频问题速查表

我把自己从部署到日常维护踩过的坑整理成一张表，基本覆盖了 80% 的常见问题。

6.3 亲自踩过的几个坑

第一个大坑是默认用 IP 当 server_name 的浏览器密码问题。Element 是个 Web 应用，在纯 HTTP 环境下，浏览器对密码框的自动填充策略非常保守——很多同事反映密码输入框不提示保存。这个没法根治，只要内网不开 HTTPS 就会存在。我的做法是建议团队用桌面端 Element，低频场景用 Web 版，毕竟桌面端没有这个限制。

第二个坑是 SQLite 转 PostgreSQL 时机的选择。我一开始图省事，用 SQLite 跑了两周，二十几个人聊天没什么问题。后来数据量到了几万条事件，每次打开房间都要卡一下。迁移本身不算难，官方提供了脚本synapse_port_db，但迁移期间服务必须停，如果你用 SQLite 跑了很久、已经有大量媒体文件，迁移的耗时和风险都会增加。所以建议从一开始就上 PostgreSQL，不要留这个后患。

第三个坑是系统重启之后 coturn 没起来。coturn 安装后默认是 disabled 状态，需要手动 enable，否则服务器重启后 TURN 服务不会自动启动，第二天所有人语音全挂。这个坑特别隐蔽，因为文字聊天一切正常，只有打电话才暴露。记得执行：

sudo systemctl enable coturn sudo systemctl restart coturn sudo systemctl status coturn

还有一个经验是备份策略。Synapse 的数据包括三部分：PostgreSQL 数据库、媒体文件的 media_store 目录、以及 homeserver 的配置文件。数据库每天凌晨 dump 一次，media_store 可以做增量同步。我写了一个简单 cron 做数据库备份：

30 3 * * * PGPASSWORD='密码' pg_dump -h localhost -U matrix matrix | gzip > /backup/matrix-$(date +\%F).sql.gz

媒体文件比数据库大得多，每天全量备份不现实，我用的 rsync 增量同步到另一台服务器或移动硬盘上。

7. 本地化部署的长期运维心得

7.1 资源监控与日常巡检

Synapse 跑稳之后，日常运维其实很轻，但有几个指标值得盯一盯。内存是大头，Synapse 是 Python 写的单进程多协程应用，内存使用量会随着房间数和在线用户数波动。建议配一个简单的监控脚本，或者用现成的 node_exporter 把指标推到监控面板里。

磁盘是另一个重点。media_store 目录的增量速度取决于团队的使用习惯，如果同事们习惯在群里发截图和文档，一个月几个 GB 非常正常。我给自己定的规则是：每周一早晨看一眼df -h，低于 30% 剩余空间就启动清理流程。Synapse 没有内置的媒体过期删除功能，要清旧文件得自己写脚本调 admin API，比较麻烦，所以更推荐从一开始就规划好磁盘容量。

7.2 后续可以扩展的方向

这套系统跑起来之后，如果想往更完整的办公平台方向发展，有几个比较容易落地的扩展。接入 LDAP 或 AD 域控，员工用公司账号直接登录 Matrix，账号注销时自动禁用。启用户注销与数据清理策略，配合管理员 API 实现离职员工的账号回收。部署 nginx 反向代理时顺手加一套 HTTPS 证书，浏览器密码管理和安全性立刻上一个台阶。这些都是基于现有架构可以平滑演进的功能，不会推翻重来。

如果团队后续扩大到上百人，或者对性能要求更高，可以考虑把 TURN 和 Synapse 拆到不同机器，Synapse 本身也可以做多实例扩展。但那是另一个量级的问题，至少对于二三十人的办公网络，这篇文章里这套方案已经非常够用了。

最后说一点个人体会：自建通讯系统最大的价值不是省钱，而是把你对"数据在哪里、谁能看到、谁能删"这件事的控制权拿回来了。Matrix 的开放协议意味着今天用 Synapse，明天也能切换到其他实现，数据永远是你的。这个自由度，是商用 SaaS 给不了的。这套部署方案我前后调试了两三天，踩完坑总结下来，其实真正动手配置的部分就那么几个文件，趁周末在虚拟机上走一遍流程，你会发现它远没有想象中复杂。