企业官网建设流程全解析

前几天刚把办公室的消息系统整体切到了 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；聊天功能之外的内容协作、审批流程之类的办公能力基本没有。但如果你只想要一套“干净、安全、同步体验好”的 IM，Matrix 很合适。办公诉求要提前想明白，不然容易被“功能不够全”误导。

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 Compose，Synapse 跑在容器里，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 Compose

Synapse 官方提供三种主流安装方式：

• 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 端口、域名与本地解析规划

办公内网版不需要复杂网络规划，但有三个端口要记清楚：

我建议用内网域名替代 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 a+r /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 组，避免每次都要 sudo：

sudo usermod -aG docker $USER

然后退出重登，验证：

docker --version docker compose version

Compose 是独立的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_NAME=matrix.lan \ -e SYNAPSE_REPORT_STATS=no \ 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.yaml：

vim /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，改成 PostgreSQL：

database: 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-secret"

registration_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_secret：

curl -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 端口做反向代理与本机 TLS

Synapse 默认监听 8008 是明文 HTTP。内网办公可以接受，但只要有跨部门网络隔离或审计要求，建议用 Nginx 做反向代理，把外部访问统一收敛到 80/443，同时启用 TLS。

新建/etc/nginx/conf.d/matrix.conf：

server { 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 name=postgres) 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 name=postgres) 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 默认可能开着 ufw：

sudo ufw status

如果启用了，放行 8008 和 8080：

sudo ufw allow 8008/tcp sudo ufw allow 8080/tcp

第三步是从客户端本机测试网络连通性，例如用 telnet：

telnet 10.10.8.149 8008

telnet 不通，就要排查交换机 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

检查通过后重启，能把配置错误挡在启动之前。这个命令我每次都用，建议你也养成习惯。