1. 为什么在办公场景里我更愿意用 Synapse 而不是临时拉个群前段时间帮团队整理内部通讯方案的时候我决定把 Matrix 协议的服务端 Synapse 装到一台 Ubuntu 服务器上做一套只跑在本地网络里的办公平台。选这套东西的原因很直接它自带端到端加密、房间权限、历史消息同步而且服务端、客户端都是开源软件数据完全落在自己手里。文章面向的是准备在自己团队里搭内部聊天的同学不一定有很深的运维基础但至少会用 Linux 命令行能照着复制命令、改几行配置。在正式动手之前我想先把方案选型说清楚。Synapse 不是那种装完就能自动弹窗的“局域网聊天工具”而是一个需要认真对待的通讯服务器。它负责账号验证、消息路由、历史记录存储实际聊天的图形界面通常由 Element 来做。两者组成一套完整的自托管消息系统。你可以把它理解成一个开源的内部 IM 后端所有人在电脑、手机上看到的会话、房间、文件都通过同一个 Synapse 服务端同步交换。有人会问公司现成的云通讯软件不也挺好吗对小团队用着确实省事但有两个隐性代价。一是数据在别人服务器上办公文件、聊天记录、项目讨论里的敏感信息本质上不在你控制范围内二是平台的开放规则、账号体系、踢人权限、消息保留策略都是别人定好的你想做内部隔离、只给项目组开独立空间反而要迁就产品设计。Synapse 的特点是协议开放、服务端可控、房间权限精细。你今天搭好明天想接机器人、接企业微信风格的 Webhook、甚至把聊天记录导出做审计都有官方接口和社区方案。还有一点很关键Matrix 是一套协议不是某个公司垄断的产品。Synapse 只是其中最常见的服务端实现之一。也就是说哪天你嫌 Synapse 太重可以换其他兼容实现客户端基本不用换。这种“协议层不被锁定”的特性对长期使用的办公平台来说比什么都重要。我见过不少团队在某个云 IM 里积攒了大量消息记录后来因为收费政策调整想迁走结果发现根本导不出来只能忍气吞声继续用。开源协议加自托管至少让你永远保留“数据可以打包带走”的自由。1.1 一套本地办公通讯系统要满足什么我列了一下办公场景对聊天工具的核心诉求拿这套标准去比 Matrix你就知道它为什么值得投入精力。第一是账号可控——员工离职能把账号直接停用聊天记录能按策略保留或清理。第二是历史消息可查——新同事加入项目组能看到之前的讨论内容不用反复问“之前那个决定是怎么做的”。第三是权限分级——不同项目之间互相隔离外部访客只能看到特定房间。第四是消息安全——尤其是法务、财务、人事这类部门端到端加密不是可选项而是刚需。这四条 Synapse 都能满足但需要注意它不是开箱即用。默认配置偏保守很多功能需要管理员手动开启。比如端到端加密服务器默认支持协议但客户端之间要主动启用再比如“只看指定房间”的访客模式需要改配置才能开放。这正是我写这篇文章的原因把部署过程中会踩的配置坑、命名坑、权限坑提前帮你趟平。1.2 核心概念server_name、房间、端到端加密上手之前三个概念必须理解否则配置时很容易一头雾水。第一个是server_name。它相当于这台服务器的“身份证号”所有用户 ID 都由它组成比如chen:matrix.local。注意它不是访问地址。你通过192.168.1.20:8008访问服务器没关系但用户 ID 后缀依然会是matrix.local。这个设计很多新手第一次搞不明白我后面会专门展开。第二个是“房间”。Matrix 里所有聊天都在房间中进行每个房间有独立的 ID 和访问控制策略。你可以把房间理解为“带权限的微信群”公开房间任何人可见私有房间只有成员能进还能设置禁言、踢人、指定管理员。办公场景下我会按“流程组”“研发小组”“管理团队”分别建房间每个房间单独拉人。第三个是端到端加密。Matrix 默认的加密协议理论上服务器即使被入侵也拿不到消息正文只能看到元数据。这个特性对办公场景很友好但配套要解决“密钥备份”问题不然用户换手机后可能看不到历史加密消息。这个后面讲到客户端配置时再细说。2. 部署前的三个关键判断版本、拓扑、命名每次我给别人讲自托管服务都提醒先别急着敲命令。先花十分钟想清楚装在什么系统、怎么跑、叫什么名字。这三个决定直接决定后期维护成本。出问题是小事最怕的是上线两周后发现架构选错再迁移数据。2.1 Ubuntu 版本与硬件底线我建议用 Ubuntu 20.04 LTS 或 22.04 LTS24.04 LTS 也可以但 20.04 和 22.04 的资料最多遇到问题最容易搜到答案。服务器配置方面单纯跑 Synapse 做内部聊天4 核 4G 内存就非常宽裕。如果团队在 30 人以内2G 内存也能跑但我不建议再低了。因为 Synapse 是 Python 写的启动时吃内存比较猛日常运行基本保持在 1GB 到 1.5GB 左右加上系统本身的开销2G 内存会显得紧巴巴。硬盘反而是更要关注的。聊天记录、图片、语音消息、文件分享会持续占用空间建议给 Synapse 单独挂一块至少 100GB 的数据盘并把 Docker 数据目录迁移到这块盘上。别跟系统盘挤在一起否则哪天聊天文件把根目录塞满整台服务器都会出问题。磁盘类型方面普通 SATA SSD 就够了不一定要 NVMe因为消息读写的压力远没有数据库那种高频随机读写夸张。2.2 域名方案局域网内怎么解决 server_nameserver_name的取名有个原则在你组织的内部环境中唯一、稳定、好记。常见做法是直接用公司内部域名比如matrix.company.local或者简化为matrix.local。如果你没有内部 DNS 服务器也不打算给客户端配 hosts 文件可以用 IP 吗技术上演戏但我不推荐。原因是你给用户注册账号之后用户 ID 就是chen:192.168.1.20以后换服务器 IP账号就全乱了。最好还是固定一个内部域名跟具体 IP 解耦。本地网络版有个好处是不需要考虑公网 DNS 解析不需要跟公共的 Matrix 服务器做联邦。所以server_name随便起只要团队内部认账就行。但如果你以后想跟其他单位的 Matrix 服务器互联那server_name必须是对外可解析的真实域名。我在办公场景默认先不考虑联邦把系统做成一个封闭的、只有内网能访问的独立聊天平台。这样最安全也最简单。实际操作中我会在局域网内的一台设备上写 hosts 解析比如 Windows 电脑把C:\Windows\System32\drivers\etc\hosts里加一行192.168.1.20 matrix.local手机端也同样处理。如果公司本来就有内部 DNS直接在 DNS 上加一条 A 记录即可所有客户端都不用动。这一步千万别省后面客户端连接的时候你就知道有多省事。2.3 Docker Compose 还是裸装 PythonSynapse 官方给了两种主流部署方式直接用 Python 安装或者用 Docker。我个人的判断是除非你特别熟悉 Python 虚拟环境和依赖管理否则优先用 Docker Compose。原因很简单Synapse 的依赖很多直接装在系统里容易把 Python 环境搞脏以后升级还可能踩依赖冲突的坑。用 Docker 把 Synapse 和系统隔离数据放在宿主机目录里升级就是拉新镜像、重启容器干净利落。Docker 还有一个好处未来如果想加 PostgreSQL、Redis、Nginx 反向代理都可以通过 Compose 文件一起管理不用再另外维护一套安装流程。办公平台最难的不是第一次装好而是三个月后做安全升级、加组件时还能保持环境可控。Compose 让整套服务变成“代码即配置”改一行文件、执行一条命令服务就变了这对小型团队的运维来说非常友好。3. 从零开始在 Ubuntu 上部署 Synapse现在进入正题。我按“目录准备 → 生成配置 → 修改配置 → 启动服务 → 创建管理员”这条线走。整个过程我用的是/srv/matrix作为数据目录你可以按自己习惯换但后续命令里的路径也要一起换。3.1 通过 Docker Compose 生成初始配置先安装 Docker 和 Compose 插件sudo apt update sudo apt install -y docker.io docker-compose-v2 sudo systemctl enable --now docker然后创建数据目录并生成初始配置sudo mkdir -p /srv/matrix/data cd /srv/matrix sudo docker run --rm \ -e SYNAPSE_SERVER_NAMEmatrix.local \ -e SYNAPSE_REPORT_STATSno \ -e SYNAPSE_NO_TLS1 \ -v /srv/matrix/data:/data \ matrixdotorg/synapse:latest generate这条命令会生成一个标准的 Synapse 配置目录。解释一下几个参数SYNAPSE_SERVER_NAME就是前面说的用户 ID 后缀我用的matrix.local你改成自己的内部域名SYNAPSE_NO_TLS1表示不在 Synapse 内部启用 TLS 证书。本地网络内部用 HTTP 即可如果要挂 HTTPS后面再在 Nginx 层处理不要把 TLS 堆在 Synapse 里避免配置复杂化。生成之后/srv/matrix/data下会出现homeserver.yaml文件和签名密钥文件。签名密钥很重要千万别弄丢它相当于这台 Synapse 服务器的印章以后客户端验证服务器身份就靠它。备份数据时一定要把这个文件一起备份。接着写一个 Compose 文件services: synapse: image: matrixdotorg/synapse:latest container_name: office-matrix restart: unless-stopped ports: - 8008:8008 volumes: - ./data:/data保存为/srv/matrix/docker-compose.yml然后执行cd /srv/matrix sudo docker compose up -d sudo docker compose ps看到容器状态为 running就说明 Synapse 已经启动监听在 8008 端口。如果启动失败docker compose logs是排第一的排查命令大部分问题是配置文件路径不对、权限不足或者端口被占用。3.2 修改 homeserver.yaml本地办公版的关键参数生成出来的homeserver.yaml能直接跑但离“办公可用”还差几处关键配置。我建议打开文件重点检查以下内容。第一public_baseurl。这一项是给客户端生成链接用的。如果你让用户通过http://matrix.local:8008访问就写public_baseurl: http://matrix.local:8008/如果直接用 IP 访问也可以写http://192.168.1.20:8008/。但前面说过尽量用域名因为用户 ID 后缀是固定的不能随意改。第二注册限制。办公平台一般不希望任何人跑到登录页注册一个账号进来。默认配置里enable_registration通常是关闭的这正合适。我会保持关闭然后用管理员手动创建账号或者临时开启注册再关闭。如果团队超过几十人每次手动建账号不现实可以在内网环境下暂时打开注册但一定要加上registration_shared_secret防止外部扫描到端口后随便注册。第三联邦功能。本地网络版不需要对外通信建议把联邦白名单设为空federation: domain_whitelist: []这样 Synapse 不会主动连接外部 Matrix 服务器别人也无法通过联邦把消息投递进来。如果你未来有与其他单位互联的需求再去掉这个限制并把server_name换成公开域名即可。第四上传限制。办公场景里经常有人发大文件、录屏默认的 10MB 限制会让人抓狂。改成 50MB 或 100MB 都比较合理max_upload_size: 100M需要注意这只是 Synapse 侧的配置客户端 App 本身也可能有自己的上传限制。Element 桌面端一般没有手机端看版本。3.3 创建管理员账号并验证服务修改完配置后重启容器cd /srv/matrix sudo docker compose restart等几秒然后用客户端或命令行检查 8008 端口是否正常响应curl -I http://127.0.0.1:8008/_matrix/client/versions能返回 HTTP 200 就说明服务活着。接着创建管理员账号sudo docker exec -it office-matrix \ register_new_matrix_user \ -u admin \ -p 你的强密码 \ -c /data/homeserver.yaml \ http://127.0.0.1:8008有些版本的命令行工具支持-a参数直接标记管理员如果不支持就需要去数据库里调整用户的 admin 字段。初次使用建议直接建一个带管理员身份的高权限账号接下来在管理后台建房间、封禁用户都方便。我踩过一个小坑建完账号后马上用 Element 登录结果提示账号不存在。后来发现是容器内时区或数据库初始化还没完成稍微等十几秒再试就好了。如果你是刚启动完立刻注册遇到登录失败不要慌等容器日志稳定后重试。4. 客户端登录与办公房间配置服务端跑起来只是第一步。真正让团队用起来还要解决客户端访问和房间体系设计。这部分我按照“怎么让同事连上来”和“怎么组织房间权限”两条线来讲。4.1 Element Web 与桌面端接入最省事的客户端方案是让同事安装 Element 桌面版登录页选择“自定义服务器”填入http://matrix.local:8008。手机端同样可以填自定义服务器地址。前提是手机能访问到这个内部域名或 IP。办公网络一般没问题但要注意 Wi-Fi 和有线网如果不是同一 VLAN可能需要网络同事开放相应策略。Element Web 我有一个经验不建议单独再搭一套 Web 托管桌面端和手机端已经覆盖绝大多数场景。除非你团队里有临时访客不方便装客户端才拿一台内网 Nginx 托管 Element Web 静态页面。如果只是自己测试直接用桌面端就好别把部署复杂度浪费在 Web 上。登录时如果服务器地址填的是http://matrix.local:8008Element 会根据server_name自动拼出账号格式你:matrix.local。这里再次体现 hosts 解析的价值。如果你没配 hosts而是用 IP 登录虽然也能登录但用户 ID 会变成你:192.168.1.20难受。4.2 房间权限按项目组隔离给访客开局部可见Matrix 权限体系的核心是“房间状态事件”。你可以把每个房间想象成一个小型组织创建者是最高权限可以改房间属性、踢人、设管理员管理员可以管理成员普通成员只能发消息和上传文件访客只能看公开内容不能发言。办公场景我的建议是三层结构。第一层是全员大厅比如“公司公告”“茶水间”全员加入任何人可发言第二层是项目组房间比如“某某项目X”默认只拉项目成员其他同事看不到房间存在第三层是保密房间比如人事讨论组创建后设为私密成员不能邀请外部人只能由管理员拉人。操作上创建房间时打开 Element 的“房间设置”权限模型选“仅限受邀成员”。房间一旦设为私有未经邀请的账号在服务器上搜索不到这个房间这在办公场景里非常重要不同项目之间不必互相干扰。如果某个房间需要向全公司公开浏览就把访问策略改成“服务器上的任何人都可以看到房间内容”发言权限仍可控制。4.3 用户注册与密码管理因为前面关掉了开放注册管理员需要手动给同事建号。命令行方法就是register_new_matrix_user但每次敲命令比较麻烦。一个小技巧是写一个简单的 Shell 脚本#!/bin/bash docker exec -it office-matrix \ register_new_matrix_user \ -u $1 \ -p $2 \ -c /data/homeserver.yaml \ http://127.0.0.1:8008存成add_user.sh以后./add_user.sh zhangsan 初始密码就能添加用户。给同事的初始密码一定要求首次登录后修改Element 端支持改密码。密码找回是另外一个容易忽略的点。Synapse 默认不支持管理员直接在后台重置密码得去数据库里把密码哈希改掉或者用命令行工具。我倾向于在homeserver.yaml里设置registration_shared_secret这样可以用 API 快速重置密码。具体用法文档里写得很清楚我这里提醒一句就够了这条信息一定要保存好不要泄露。5. 本地办公版运维与调优建议长期维护中有几个点比第一次部署更重要。实话讲部署只要照着抄就行维护才是真正考验人的地方。5.1 存储架构先用 SQLite 还是直接上 PostgreSQLSynapse 默认用 SQLite 数据库文件就放在数据目录里。对于 30 人以下的办公场景SQLite 完全够用部署最简单、备份也简单。但有个前提不要一个人在里面疯狂拉历史记录也不要让机器人高频写入。只要日常聊天负载平稳SQLite 不会成为瓶颈。团队规模超过 50 人或者你打算长期保留所有历史消息我建议一步到位换 PostgreSQL。迁移过程不算复杂但需要停服操作。我会在服务刚搭好的时候就直接用 PostgreSQL因为这比以后数据多了再迁移省事得多。用 Compose 管理的话加一个 PostgreSQL 容器再把 Synapse 的数据库配置指过去即可。篇幅有限我不展开全部配置文件核心思路是Synapse 支持 SQLite 迁移到 PostgreSQL官方文档有现成步骤。5.2 备份与恢复数据无价配置也一样Synapse 的数据分三块数据库里的账号、房间、消息索引媒体文件图片、视频、文件签名密钥。备份策略很简单数据库文件或 SQL 定时备份到另外一台机器媒体目录整目录同步密钥文件单独加密保存。恢复的时候三个数据要配套还原缺一个都会出错。我自己的做法是写一个凌晨执行的定时任务把/srv/matrix/data整体打包上传到公司内部的对象存储或另一台机器的磁盘。因为聊天数据每天都在变备份周期不要超过 24 小时。如果团队里有人频繁发文件也可以把媒体目录单独增量同步减少打包体积。这里强调一句签名密钥丢失的后果非常严重可能会导致所有客户端无法信任服务器所以密钥文件一定要和数据库分开备份。5.3 升级策略不要追新版本但要定期更新Synapse 更新频率不算低。我的原则是不要在办公平台刚跑稳定时频繁升级但也不要半年不升。每次升级前先看官方 Changelog确认没有破坏性的配置变更然后拉新镜像、重启容器观察半小时日志。如果有异常马上回滚到旧镜像。容器化部署的最大优势就是升级方便。Compose 文件里如果写了image: matrixdotorg/synapse:latest每次docker compose pull会拉最新版但latest标签在长时间运行后可能跟旧数据不兼容。建议改用明确的版本标签比如matrixdotorg/synapse:v1.105.0升级时手动改版本号。这样即使升级出错也能迅速退回去。6. 常见问题排查实录这部分内容整理自我一路部署和日常运维里真实遇见的问题每条都配上排查思路希望能帮你在最快时间内定位问题。6.1 客户端提示“无法连接到服务器”但服务端看起来正常最常见的坑不是端口不通而是server_name与访问地址不一致。Synapse 的配置里server_name决定用户 ID而客户端填的服务器地址是“连接地址”两者不需要相同但用户容易搞混。我建议先在浏览器访问http://matrix.local:8008能打开就说明网络通再打开客户端服务器地址随手补上完整的http://前缀很多客户端不填前缀会自动当 HTTPS 解析导致握手失败。真正网络层的排查用三条命令ss -lntp | grep 8008 sudo ufw status sudo docker compose logs --tail 100 synapse第一条看进程是否监听第二条看防火墙第三条看日志。办公网络环境里问题大概率出在客户端电脑的 DNS 解析或者服务器防火墙没放行 8008 端口。6.2 登录时报“Invalid username or password”先确认账号确实创建成功。用管理员账号在 Element 登录看能否进入管理功能。如果管理员也登不上重点检查数据库是否初始化完成。轻量环境下数据库初始化可能需要几秒刚启动马上注册账号容易出现这种问题。另一种可能是时间不同步。Matrix 的端到端加密和会话认证依赖时间戳服务器时间和客户端时间差太大会直接认证失败。执行timedatectl status看系统时间不对就配置 NTP 同步。这个坑最容易忽略因为它跟配置完全无关纯粹是物理世界的时间偏差。6.3 消息能发出去但加密会话失败登录正常、发消息也正常但点开加密房间就报错这多半是密钥备份没配好。Matrix 的端到端加密密钥存在客户端本地换设备后需要从密钥服务器恢复。Synapse 本身可以托管加密密钥但需要在客户端设置里主动开启“创建恢复密钥”并记录恢复码。行政、财务这类账号尤其要提醒否则换了电脑就看不到历史加密消息。我建议在团队引入 Matrix 的第一周就发一页内部说明教大家设置密钥备份并把恢复码保存到公司密码管理器。这一段内容虽然简单但直接影响员工对加密功能的信任度。6.4 服务器内存占满、响应缓慢如果只有少数用户但内存占用异常高常见原因是媒体缩略图生成和日志堆积。Synapse 收到图片会生成多种尺寸的缩略图图片多的时候 CPU、内存直线上涨。可以调整生成策略限制缩略图尺寸规格减少计算量。日志方面Compose 默认不限制日志大小跑久了可能吃掉几 GB 磁盘。在 Compose 文件里加一段配置可以控制日志上限services: synapse: logging: driver: json-file options: max-size: 50m max-file: 3重启容器后生效。这条配置我建议从第一天就加上别等磁盘满了再处理。7. 长期使用后的几个实用小经验把这个办公平台跑起来以后我总结了些文档里不会写清楚的小经验不妨直接拿去用。第一房间命名要规范。Matrix 房间 ID 是随机字符串不好看但你可以给每个房间设置一个稳定的房间别名比如#研发-客户端:matrix.local。同事之间发链接就把别名发出来点开就能进房间不用在服务器列表里筛。第二机器人接入是办公效率的一倍提升点。Synapse 支持应用服务你可以自己写一个简单的通知机器人把代码仓库的 CI 结果、监控告警、运维事件发到指定房间。内部系统对接这个场景云平台往往要收费或者限制 API自托管完全自己说了算。第三千万别什么都往全员房间丢。聊天平台用久了全员房间里堆积大量无意义消息后来的人根本翻不动。我给团队定的规则是全员房间只放公告和必读信息讨论一律进项目组房间。技术上的权限隔离有了习惯上的内容隔离同样重要。第四如果哪天真要开放对外联邦记得在防火墙放行 8448 端口。本地网络版配置里如果只是白名单留空联邦就是关闭状态8448 端口不用开。一旦改成开放联邦这个端口必须暴露否则外部服务器连不进来但对外的一刻整个安全模型也会改变需要重新评估公网入口的风险。最后说一个我这段时间用得最多的技巧出问题先看日志不要动不动重启。Synapse 日志本身写得相当清晰很多错误信息已经给出原因“Invalid configuration”会告诉你具体是哪一行有问题“Federation is disabled”会提醒你干了件不可能的事。学会从日志往回倒推配置问题比盲目重装要高效得多。这套办公平台我目前已经稳定跑了几个月几十个同事日常聊天、传文件、会议室讨论都用它基本没有让人操心的故障。对于一个内部聊天系统来说稳定、可控、数据在手就是最大的价值。