前几天刚把办公室的消息系统整体切到了 Matrix 协议上服务器跑在一台旧 Ubuntu 机器上客户端统一用 Element。团队用了两周反馈很稳定我发现这套“办公平台本地网络版 Synapse Matrix 服务器”并没有想象中复杂但坑还是有的。如果你正考虑在内网自建一套即时通讯服务或者已经装了 Synapse 但没跑通这篇文章应该能帮你省不少时间。先说清楚这东西是什么Synapse 是 Matrix 协议的官方服务器实现Matrix 本身是一套开放、去中心化的实时通信协议支持端到端加密、历史记录同步、多端消息一致。办公场景下最常见的做法是把它部署在内网客户端装 Element Web 或 Element Desktop员工通过局域网 IP 或内网域名访问消息和文件完全留存在自己服务器上。适合对数据敏感、不想把办公聊天交给第三方平台的团队也适合想学习自建通讯服务的人。下面我会从方案选型、环境准备、实际部署、客户端接入、安全加固到问题排查把我在 Ubuntu 上跑通这套服务的整个链条完整写出来。每个关键步骤我都会说为什么这么做以及哪些地方容易踩坑。1. 为什么办公平台要自建 Matrix/Synapse先理清真实需求1.1 自建通讯不只是“不想用外部软件”办公场景的自建 IM首先要回答一个问题你图的是什么如果只是图“私有化”其实不一定要上 Matrix很多开源方案也能做。但真实的办公需求往往更具体员工聊天记录需要留存在公司内部不能放在第三方云上。需要支持大体量的历史消息、多端同步不能登出手机就丢聊天记录。需要群组和私聊分开权限能落实到用户角色。最好有端到端加密防止网络链路被监听。部署和维护成本不能太高小团队也要跑得动。Matrix 协议在这几点上天然合适。Synapse 作为参考服务器Python 写的部署文档完善生态里有 Element、FluffyChat 等一批成熟客户端。而且它不像某些“开源版”藏着商业限制协议本身就是开放的以后就算不想用 Synapse也能迁移到 Conduit 或者 Dendrite 等其他实现。当然也要说清楚短板。Synapse 比同类的 Rocket.Chat、Mattermost 要“瘦”一些默认没有营销级的管理界面用户管理、房间管理很多操作要走命令行或 API聊天功能之外的内容协作、审批流程之类的办公能力基本没有。但如果你只想要一套“干净、安全、同步体验好”的 IMMatrix 很合适。办公诉求要提前想明白不然容易被“功能不够全”误导。1.2 Matrix 协议和 Synapse 服务器的优势与代价先说优势。历史同步机制是 Matrix 的亮点。不管用哪个客户端登录同一个账号后历史消息、已读位置、设备信息都能同步不像某些老式 IRC 服务切设备就丢上下文。端到端加密E2EE在 Matrix 里是协议级支持不是后期打补丁。会议室里如果有设备未验证会明示提示适合办公保密沟通。联邦能力Federation是 Matrix 的默认能力两个服务器之间可以互通类似邮件跨域沟通。办公内网版可以选择关闭联邦确保消息不流出服务器。客户端生态丰富。官方维护的 Element Web 可以直接部署成网页版Element Desktop 支持 Windows/macOS/Linux移动端也有 Element 原生应用。再说代价。Synapse 是 Python/Twisted 写的默认配置下内存占用不算低小内存机器会紧张。默认 SQLite 只适合测试正式办公必须用 PostgreSQL多一个服务要维护。初期配置并不难但后续升级、备份、证书更新都需要自己维护不像 SaaS 那样点一下就能完事。1.3 办公场景的典型拓扑我这次部署的拓扑很典型一台 Ubuntu 服务器放在办公机房的局域网内固定 IP 10.10.8.x。服务器上装了 Docker Engine 和 Docker ComposeSynapse 跑在容器里PostgreSQL 也跑在容器里。客户端设备包括 Windows 电脑、macOS 电脑和手机全部通过局域网访问 Element Web或者安装桌面/移动客户端连接服务器地址。没有对外暴露任何端口联邦默认关闭消息只在本机内部流转。这个拓扑的好处是不需要公网 IP不需要域名证书只要内网 DNS 或 hosts 解析做好即可达到“聊天记录全在自己手里”的效果。如果你的办公网里已有域名服务和反向代理过渡到正式环境也容易。2. 部署 Synapse 之前环境准备、版本与端口规划2.1 Ubuntu 版本选择与基础配置Synapse 对 Ubuntu 版本没有强依赖20.04、22.04、24.04 我都跑过。在 2025 年的时间点建议优先选择 Ubuntu 22.04 LTS 或 24.04 LTS因为 LTS 有五年以上安全更新和 Docker 仓库兼容好。已经很旧的 18.04 就不建议了Python 和 OpenSSL 版本太老容易遇到依赖问题。基础配置里我建议先做三件事把主机名设为有意义的名称比如matrix或office-msg后面客户端连接时会用到。配置静态 IP避免 DHCP 变动导致客户端找不到服务器。更新系统包安装常用工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git vim net-tools办公环境如果规模不大2核 CPU、2GB 内存、40GB 磁盘的机器就能跑。团队上百人再考虑提升资源。我实际测过2GB 内存机器跑 Synapse PostgreSQL Element Web三个容器同时运行内存会到 1.6GB 左右仍有余量。2.2 Docker Compose 还是裸装我为什么选 Docker ComposeSynapse 官方提供三种主流安装方式apt 源直接安装用 Python venv 手工安装Docker 容器运行如果只是个人测试venv 没问题。但办公环境我会直接选 Docker Compose理由很现实组件不止 Synapse 一个还有 PostgreSQL、Element Web、反向代理用 Compose 能把它们写进一个文件重启和更新都统一。Synapse 升级频繁Docker 镜像更新后只需要docker compose pull docker compose up -d比 apt 升级干净。配置文件和数据目录都放在宿主机固定路径重装系统也不会丢数据。需要额外说的是Docker 容器不会降低性能官方镜像本身就是生产环境推荐方式之一。如果你对 Docker 不熟也不用担心后面我会给完整配置。2.3 内存、CPU 与数据库选型Synapse 默认使用 SQLite确实“开箱即用”。但我强烈建议办公场景第一天就改成 PostgreSQL。为什么因为 SQLite 的锁机制在多人并发写时容易碰壁尤其是历史消息量上来之后会出现“database is locked”错误。PostgreSQL 的并发和事务能力明显更强而且 Synapse 官方性能优化都是针对 Postgres 的。我的 Compose 文件里配置如下postgres: image: postgres:16 environment: POSTGRES_USER: synapse POSTGRES_PASSWORD: change-me POSTGRES_DB: synapse volumes: - ./postgres:/var/lib/postgresql/data内存方面PostgreSQL 和 Synapse 两个容器加一起建议宿主机至少 1.5GB 可用内存。缓存默认值可以不改等团队规模扩大再去调caches.global_factor。2.4 端口、域名与本地解析规划办公内网版不需要复杂网络规划但有三个端口要记清楚端口用途说明8008Client-Server API客户端连接 Synapse 的默认端口8448Federation API联邦通信端口本地办公可不开443/80反向代理访问端口如果给 Element Web 和 Synapse 做代理用我建议用内网域名替代 IP例如matrix.lan。这样以后服务器 IP 变了只需要改 DNS不用让所有客户端重新改配置。如果公司内有 DNS 服务器在 DNS 里加一条 A 记录指向 Synapse 服务器的局域网 IP。没有 DNS 也可以在各客户端 hosts 文件里手工添加不过维护成本会高一些。3. 一步步在 Ubuntu 上部署 Synapse 核心服务3.1 安装 Docker Engine 与 Compose 插件先装 Docker。2025 年的官方推荐是用清华或阿里镜像源配置 Docker 官方 apt 源但我这里直接给最稳妥的命令sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin注意不同 Ubuntu 版本的代号不一样命令会自动读取。装完以后把当前用户加入 docker 组避免每次都要 sudosudo usermod -aG docker $USER然后退出重登验证docker --version docker compose versionCompose 是独立的docker compose命令注意不要写错成有横杠的docker-compose新版插件命令格式有区分。3.2 初始化 Synapse 配置文件Synapse 的配置文件需要先生成再手工修改。我不建议直接手写完整的homeserver.yaml因为它的键非常多手写容易漏。初始化方法是用官方镜像的generate子命令。先建好目录mkdir -p /opt/matrix/synapse/data cd /opt/matrix然后运行docker run --rm -it \ -v /opt/matrix/synapse/data:/data \ -e SYNAPSE_SERVER_NAMEmatrix.lan \ -e SYNAPSE_REPORT_STATSno \ matrixdotorg/synapse:latest generate其中SYNAPSE_SERVER_NAME是服务器名我填了matrix.lan这决定了用户 ID 的格式比如zhangsan:matrix.lan。这里有个隐蔽的坑server_name不一定非得是域名但一旦生成之后很难改改动等于换服务器。所以开始就要规划好。生成结果会在/opt/matrix/synapse/data下出现homeserver.yaml和一个matrix.lan.signing.key。签名密钥是服务器身份的证明一定别删。建议把它额外备份一份到 U 盘或网盘。3.3 修改 homeserver.yaml 的关键参数这一步是整个部署里最需要耐心的地方。打开homeserver.yamlvim /opt/matrix/synapse/data/homeserver.yaml我修改时主要关注六个部分。第一个是服务器监听地址。默认配置是这样的listeners: - port: 8008 tls: false bind_addresses: [::1, 0.0.0.0] type: http x_forwarded: false resources: - names: [client, federation] compress: false如果你的服务器不承担联邦功能可以只保留client不保留federation。不过保留联邦配置也行因为后面关闭联邦并不依赖这个。bind_addresses要确保有0.0.0.0否则客户端从局域网访问不到。第二个是数据库配置。注释掉默认的database: sqlite改成 PostgreSQLdatabase: name: psycopg2 args: user: synapse password: change-me-strong database: synapse host: postgres port: 5432 cp_min: 5 cp_max: 10注意host写的是 Compose 服务名postgres因为 Synapse 容器和数据库容器同处一个 Docker 网络可以用服务名互相访问。第三个是注册和登录配置。办公内网版我建议先关闭开放注册用管理员账号创建用户enable_registration: false registration_shared_secret: your-very-long-random-secretregistration_shared_secret是管理员注册 API 的密钥这个密钥可以让你在命令行创建账号后面会用到。第四个是媒体存储路径配置media_store_path: /data/media_store这条保持默认就行但要注意宿主机挂载的/data是否空间充足。聊天图片和文件都会存这里建议单独给个大分区。第五个是缓存和性能参数caches: global_factor: 0.5服务器内存小的可以调低到0.5降低缓存占用。内存充足可以保持默认或调到1.0。第六个是联邦配置。内网办公版建议直接关闭联邦federation: enabled: false关闭后服务器不会主动连外网也不接受外部服务器连接。消息不会流出局域网这对办公平台很重要。3.4 用 docker-compose 启动并验证健康状态在/opt/matrix下创建docker-compose.yml。这个文件可以同时管理 Synapse、PostgreSQL 和 Element Web。我的示例version: 3.8 services: postgres: image: postgres:16 restart: unless-stopped environment: POSTGRES_USER: synapse POSTGRES_PASSWORD: change-me-strong POSTGRES_DB: synapse volumes: - ./postgres:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U synapse -d synapse] interval: 10s timeout: 5s retries: 5 synapse: image: matrixdotorg/synapse:latest restart: unless-stopped depends_on: postgres: condition: service_healthy ports: - 8008:8008 volumes: - ./synapse/data:/data environment: SYNAPSE_SERVER_NAME: matrix.lan SYNAPSE_REPORT_STATS: no element: image: vectorim/element-web:latest restart: unless-stopped ports: - 8080:80注意depends_on用了condition: service_healthy这样 Synapse 会等 PostgreSQL 健康检查通过后再启动避免启动顺序问题。启动命令cd /opt/matrix docker compose up -d查看日志docker compose logs -f synapse看到类似Started listener on 0.0.0.0:8008的日志就说明服务起来了。用 curl 验证curl http://localhost:8008/_matrix/client/versions正常会返回一串 JSON包含版本信息。这一步通过后Synapse 核心服务就算跑起来了。4. 接入客户端、管理员账号与办公功能配置4.1 注册账号与初始化管理员权限因为配置文件里enable_registration是false普通用户无法自助注册。办公场景一般由管理员先创建账号再发给员工。创建账号有两种方式。第一种是直接用容器内的注册 API需要用到之前配置的registration_shared_secretcurl -X POST http://localhost:8008/_matrix/client/r0/register \ -H Content-Type: application/json \ -d { username: zhangsan, password: StrongPassword123, auth: { type: m.login.registration_shared_secret, secret: your-very-long-random-secret } }返回 JSON 中会包含access_token说明账号建好了。注意官方 API 版本路径可能在 v3 上略有差异如果返回 404可以试/v3/register。第二种更简单直接使用官方提供的新版管理命令。启动一个一次性容器执行docker run --rm -it \ -v /opt/matrix/synapse/data:/data \ matrixdotorg/synapse:latest \ python -m synapse.app.admin_register \ -c /data/homeserver.yaml \ -u lisi -p StrongPassword456用这种方式建的账号会自动拥有管理员权限吗不一定。要给账号提升管理员权限可以执行docker exec -it synapse-container \ python -m synapse.app.admin_cmd \ --config /data/homeserver.yaml \ --user lisi:matrix.lan \ --admin或者直接操作数据库docker exec -it postgres-container psql -U synapse -d synapse UPDATE users SET admin 1 WHERE name lisi:matrix.lan;操作完以后建议验证一下.well-known配置后面 Element 客户端登录时会更顺滑。4.2 部署 Element Web 客户端Element Web 是 Matrix 官方推荐的网页客户端。前面 Compose 里已经包含了 Element 容器启动后默认监听 8080 端口。直接访问http://10.10.8.149:8080首次打开会让我输入 homeserver 地址填http://10.10.8.149:8008登录即可。如果你希望打开网页后不用手动输入服务器地址可以在 Element 的配置里指定。Element 容器的默认配置文件路径在/app/config.json我通过挂载方式自定义element: image: vectorim/element-web:latest restart: unless-stopped ports: - 8080:80 volumes: - ./element/config.json:/app/config.json宿主机上新建./element/config.json{ default_server_config: { m.homeserver: { base_url: http://10.10.8.149:8008, server_name: matrix.lan } } }这样网页打开就直接进入登录界面不需要员工自己敲服务器地址体验会好很多。顺手说一句Element 本身只是个静态页面它默认也是通过浏览器连 8008 端口。如果担心浏览器明文访问有风险后面可以做反向代理加 TLS。4.3 团队成员从局域网设备接入现在团队成员可以从不同设备接入。Windows 用户直接用浏览器打开http://10.10.8.149:8080或者在 Element Desktop 里设置服务器地址为http://10.10.8.149:8008。macOS 用户一样Element Desktop 官方支持 Apple Silicon。手机用户安装 Element Android/iOS 应用设置里填入同样的 homeserver 地址。登录时有一件很重要的事首次登录后建议开启“会话验证”也就是交叉签名。办公网络安全环境下端到端加密的密钥管理如果不做验证会出现“其他设备已加入加密房间但无法解密历史消息”的问题。让团队成员在第一次登录时点“验证此浏览器/设备”扫二维码或者输入安全密钥能避免很多后续问题。员工端如果遇到“服务器不支持”或“无法连接”大部分是地址写错或者端口没放通。这个在下文排查章节专门讲。4.4 开启常用办公功能历史记录、文件上传与消息保留办公场景里历史消息是资产不能随便丢。Matrix 默认会保留历史消息但要确认房间设置。管理员或者房间创建者可以在 Element 的“房间设置——权限与安全”里勾选“任何人都能读取历史消息”或按需调整。对部门群来说我一般设置成“加入后可见全部历史”这样新加入的同事能看到之前的讨论。文件上传默认是打开的存储在media_store_path。企业可以限制上传大小。在homeserver.yaml里添加max_upload_size: 20M建议根据公司网络和磁盘容量调整我办公环境设了 50M能支持大部分图片和文档。消息保留策略方面Matrix 没有内置自动删除历史消息的机制需要管理员通过 API 或配置实现。如果办公规范需要保留 180 天可以借助 Synapse 的 retention 功能。在homeserver.yaml中retention: enabled: true default_policy: min_lifetime: 1d max_lifetime: 180d不过这会显著增加数据库清理压力办公室小团队其实不建议开启除非有合规要求。5. 安全加固与数据备份内网也不能偷懒5.1 关闭联邦并限制注册入口办公内网版最大优势是消息不出内网但也要注意默认状态下 Synapse 可能试图查询公网联邦。为了彻底隔绝我前面已经改了federation.enabled: false。这一步建议每个人都要做别只想着“内网安全”。注册入口同样要收窄。办公场景我建议使用“共享密钥注册 管理员建号”模式不要开放互联网式注册。如果你确实想让员工自助注册可以在homeserver.yaml设置enable_registration: true enable_registration_without_verification: true但这样会允许任何人创建账号内网环境风险不可控。还可以开启注册白名单registrations_require_3pid: [email]但这一步需要配置 SMTP 邮箱验证办公共用环境会增加维护成本。我更推荐的方式是管理员批量建号或者用registration_shared_secret写一个简单的注册页面让员工通过内部 OA 系统自动调用 API。5.2 为 8008 端口做反向代理与本机 TLSSynapse 默认监听 8008 是明文 HTTP。内网办公可以接受但只要有跨部门网络隔离或审计要求建议用 Nginx 做反向代理把外部访问统一收敛到 80/443同时启用 TLS。新建/etc/nginx/conf.d/matrix.confserver { listen 80; server_name matrix.lan; location / { proxy_pass http://127.0.0.1:8008; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } }如果要有 HTTPS 证书内网可以用自签证书但客户端不会自动信任比较麻烦。建议用内网 CA 并下发根证书到员工设备。这一步不是必须但如果你做务必在homeserver.yaml里对应 listener 开启x_forwarded: true否则 Synapse 无法正确识别真实 IP可能影响登录和限流。还需要留意Element Web 如果通过http://10.10.8.149:8080访问而它连的是http://10.10.8.149:8008浏览器默认会混合内容如果以后 8080 换成了 https就要求 8008 也必须 https。所以正式化部署时最好把 Element 和 Synapse 都放在同一个域名后面用路径区分。5.3 PostgreSQL 每日备份与恢复演练数据是办公平台的生命线。Synapse 的配置和媒体文件可以复制但聊天记录都在 PostgreSQL 里必须做定时备份。我写了一个简单的备份脚本放到宿主机/opt/matrix/backup.sh#!/bin/bash BACKUP_DIR/opt/matrix/backups mkdir -p $BACKUP_DIR docker exec $(docker ps -qf namepostgres) pg_dump -U synapse -d synapse | gzip $BACKUP_DIR/synapse_$(date %Y%m%d_%H%M%S).sql.gz find $BACKUP_DIR -name *.sql.gz -mtime 7 -delete用 crontab 每天凌晨执行crontab -e加入一行0 2 * * * /bin/bash /opt/matrix/backup.sh这里最好每周做一次“恢复演练”。别笑我见过很多团队只备份不恢复等到真要恢复的时候发现备份文件是坏的。恢复命令大概是gunzip -c synapsedump.sql.gz | docker exec -i $(docker ps -qf namepostgres) psql -U synapse -d synapse恢复前先停 Synapse避免写入冲突。恢复后再启动验证历史消息是否都在。演练过一次心里才有底。6. 常见问题与排查技巧实录6.1 客户端报错“Cannot reach homeserver”这是最常见的问题十有八九是网络层面。第一步在服务器上检查监听ss -lntp | grep 8008如果只有127.0.0.1:8008说明 Synapse 没监听外部地址。回到homeserver.yaml确认listeners的bind_addresses里有0.0.0.0。改完重启docker compose restart synapse第二步检查防火墙。Ubuntu 默认可能开着 ufwsudo ufw status如果启用了放行 8008 和 8080sudo ufw allow 8008/tcp sudo ufw allow 8080/tcp第三步是从客户端本机测试网络连通性例如用 telnettelnet 10.10.8.149 8008telnet 不通就要排查交换机 VLAN、ACL、客户端 hosts 解析等问题。前阵子有台 Windows 电脑怎么都打不开最后发现是公司 WiFi 启用了“AP 隔离”无线设备之间禁止互访。6.2 注册接口返回 403如果你在用registration_shared_secret调用注册 API遇到403 Forbidden常见原因是 secret 配置没生效。在homeserver.yaml里确认registration_shared_secret的值并且容器重启过。注意调用时 secret 要和配置文件里的完全一致不要多空格。还有一种情况是enable_registration: false时用共享密钥注册是不受影响的但如果配置中还带了enable_registration_without_verification: false可能会拦截注册。先把验证相关配置关掉或者做完整配置检查。6.3 服务内存持续上涨Synapse 内存占用高是历史老问题。如果你的服务器常年吃到 90% 以上先看是不是 Python 容器积累了大量缓存的媒体文件或消息事件。可以分几步调低缓存因子caches.global_factor: 0.3限制 Docker 内存在 Compose 的synapse服务里加deploy: resources: limits: memory: 1g但注意内存限制不要太小否则 Synapse 进程会被 OOM Kill。我试过最低 512MB 能跑但一有群聊活跃就崩。办公团队 20 人以下建议至少给 1GB。6.4 更新容器后的兼容性问题每次想升级 Synapse我都不建议直接docker compose pull完就启动。官方版本更新频繁有时会引入配置项变化。安全做法是先备份配置目录和数据库。pull 新镜像。docker compose up -d synapse启动后观察日志。如果日志报“config file error”或数据库字段缺失第一时间回滚到旧镜像image: matrixdotorg/synapse:v1.122.0然后在测试环境确认没问题再正式更新。升级这东西最怕“一把梭”。我在生产上吃过一次亏升级到某个中间版本后媒体图片生成为 403最后发现是配置文件里少了 thumbnail 相关参数。所以每一条日志都不能跳过。6.5 重置忘记密码的管理员账号办公久了总有人忘了密码。管理员密码重置不需要通过 web 界面。我现在最常用的方式是直接数据库更新 hash。先停掉 Synapse然后在 PostgreSQL 里生成一个新的 bcrypt 哈希。更简单的是用容器里的命令docker exec -it synapse-container \ python -m synapse.app.admin_register \ -c /data/homeserver.yaml \ -u lisi \ -p NewPassword123如果提示用户已存在可以用hash_password方式docker exec -it synapse-container python \ -c from synapse._bcrypt import bcrypt_hash_password; print(bcrypt_hash_password(NewPassword123).decode())然后把输出的哈希更新到数据库users表的password_hash字段。这个操作一定要在备份后做别问我为什么强调。7. 部署完成之后的一点经验整趟部署下来我最深的体会是Synapse 本身并不难难的是把它和办公环境真正磨合好。刚部署完的那几天我几乎每天都在改homeserver.yaml从上传大小到历史消息保留每次改动都会影响客户端体验。所以建议你把配置变更都记录在一个文档里方便排查。如果你后续想扩展可以从这几个方向入手给 Element 加自定义登录名和免密登录把 Synapse 接入公司 LDAP 或 OAuth用 Nginx 把matrix.lan统一代理到 443 端口让手机在外网也能通过公司网关访问再加一套 Prometheus Grafana 监控 Synapse 和 PostgreSQL。Matrix 协议的优势就是开放扩展路径很长这套本地网络版只是起点。最后分享一个操作小技巧每次改完homeserver.yaml记得先做配置检查再重启docker run --rm -it \ -v /opt/matrix/synapse/data:/data \ matrixdotorg/synapse:latest \ python -m synapse.app.homeserver \ --config /data/homeserver.yaml \ --check-config检查通过后重启能把配置错误挡在启动之前。这个命令我每次都用建议你也养成习惯。