1. 项目概述
最近在帮朋友搭建一个本地办公协作平台，选择了Synapse Matrix这套开源解决方案。不同于常见的Slack或Teams，Matrix协议最大的特点就是去中心化——你可以完全掌控自己的数据，而且能和其他Matrix服务器互通。这次我们要实现的是纯内网部署，适合对数据安全性要求高的企业环境。
Ubuntu Server 20.04 LTS作为基础系统，不仅长期支持稳定，而且对Python环境（Synapse是用Python写的）支持友好。整个部署过程涉及几个关键组件：Synapse主服务、PostgreSQL数据库、Nginx反向代理，以及可选的Element Web客户端。
注意：虽然官方推荐使用PostgreSQL，但在资源受限的测试环境中，SQLite也能跑起来。不过生产环境务必用PostgreSQL，我们实测SQLite在超过10个活跃用户时就会出现性能问题。
2. 环境准备与依赖安装
2.1 系统基础配置
首先确保你的Ubuntu系统是最新状态：
bash复制sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget gnupg2 apt-transport-https
设置时区很重要，否则日志时间会对不上：
bash复制sudo timedatectl set-timezone Asia/Shanghai
2.2 安装必备组件
Synapse需要Python 3.6+环境，建议直接用Ubuntu自带的：
bash复制sudo apt install -y python3-pip python3-venv libpq-dev
数据库选择PostgreSQL 12+版本：
bash复制sudo apt install -y postgresql postgresql-client
3. 数据库配置
3.1 PostgreSQL初始化
创建专属数据库用户（记得替换your_password）：
bash复制sudo -u postgres psql -c "CREATE USER synapse WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0 OWNER synapse;"
调整pg_hba.conf增加连接权限：
bash复制sudo nano /etc/postgresql/12/main/pg_hba.conf
在文件末尾添加：
code复制host synapse synapse 127.0.0.1/32 md5
3.2 性能调优建议
根据我们运维经验，PostgreSQL这些参数对Synapse性能影响最大：
bash复制sudo nano /etc/postgresql/12/main/postgresql.conf
关键修改项：
code复制shared_buffers = 1GB # 25% of total RAM
work_mem = 16MB # 每个查询可用内存
maintenance_work_mem = 256MB # 维护操作内存
random_page_cost = 1.1 # SSD存储建议值
effective_cache_size = 3GB # 50-75% of total RAM
4. Synapse安装与配置
4.1 安装主程序
官方推荐用pip安装到虚拟环境：
bash复制python3 -m venv ~/synapse/env
source ~/synapse/env/bin/activate
pip install --upgrade pip wheel
pip install matrix-synapse[postgres]
生成配置文件（替换your.domain）：
bash复制python -m synapse.app.homeserver \
--server-name your.domain \
--config-path ~/synapse/homeserver.yaml \
--generate-config \
--report-stats=no
4.2 关键配置详解
编辑生成的homeserver.yaml：
bash复制nano ~/synapse/homeserver.yaml
必须修改的核心参数：
yaml复制server_name: "your.domain"
listeners:
- port: 8008
tls: false
type: http
x_forwarded: true
resources:
- names: [client, federation]
compress: false
database:
name: psycopg2
args:
user: synapse
password: "your_password"
database: synapse
host: localhost
cp_min: 5
cp_max: 10
踩坑提醒：如果部署在内网，务必设置
enable_registration: true才能本地注册用户。但记得配置合适的注册策略防止滥用。
5. 服务化与反向代理
5.1 创建Systemd服务
创建服务文件：
bash复制sudo nano /etc/systemd/system/synapse.service
内容示例：
code复制[Unit]
Description=Synapse Matrix Homeserver
After=network.target postgresql.service
[Service]
User=synapse
Group=synapse
WorkingDirectory=/home/synapse
ExecStart=/home/synapse/env/bin/python -m synapse.app.homeserver --config-path=/home/synapse/homeserver.yaml
Restart=always
[Install]
WantedBy=multi-user.target
5.2 Nginx配置
安装Nginx并配置SSL（内网可用自签名证书）：
bash复制sudo apt install -y nginx
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/nginx-selfsigned.key \
-out /etc/ssl/certs/nginx-selfsigned.crt
Nginx站点配置参考：
nginx复制server {
listen 443 ssl;
server_name your.domain;
ssl_certificate /etc/ssl/certs/nginx-selfsigned.crt;
ssl_certificate_key /etc/ssl/private/nginx-selfsigned.key;
location /_matrix {
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
}
location /.well-known/matrix/server {
return 200 '{"m.server": "your.domain:443"}';
default_type application/json;
}
}
6. 客户端部署建议
6.1 Element Web配置
下载Element Web最新版：
bash复制wget https://github.com/vector-im/element-web/releases/download/v1.11.8/element-v1.11.8.tar.gz
tar xzf element-v1.11.8.tar.gz
sudo mv element-v1.11.8 /var/www/html/element
修改config.json：
json复制{
"default_server_config": {
"m.homeserver": {
"base_url": "https://your.domain",
"server_name": "your.domain"
}
}
}
6.2 移动端配置技巧
Android/iOS客户端使用时：
- 首次打开app时选择"自定义服务器"
- 输入https://your.domain
- 忽略SSL警告（内网环境）
7. 运维与监控
7.1 日常维护命令
查看服务状态：
bash复制sudo systemctl status synapse
查看数据库连接数：
bash复制sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname='synapse';"
7.2 日志分析技巧
关键日志路径：
- Synapse日志：/home/synapse/homeserver.log
- Nginx日志：/var/log/nginx/access.log 和 error.log
常用grep命令：
bash复制# 查找注册失败记录
grep "Registration request" /home/synapse/homeserver.log
# 统计API调用频率
awk '{print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -nr
8. 性能优化实战
8.1 Synapse调参经验
修改homeserver.yaml这些参数可提升性能：
yaml复制rc_message:
per_second: 10
burst_count: 50
federation_rc_window_size: 1000
federation_rc_sleep_limit: 50
federation_rc_reject_limit: 100
8.2 数据库维护脚本
每月执行的维护脚本：
bash复制#!/bin/bash
# 清理旧消息
psql -U synapse -d synapse -c "DELETE FROM events WHERE stream_ordering < (SELECT max(stream_ordering) - 1000000 FROM events);"
# 重新索引
psql -U synapse -d synapse -c "REINDEX DATABASE synapse;"
# 清理缓存
psql -U synapse -d synapse -c "VACUUM FULL ANALYZE;"
9. 常见问题排查
9.1 连接问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 502 Bad Gateway | Nginx到Synapse连接失败 | 检查systemctl status synapse |
| 无法注册用户 | enable_registration=false | 修改homeserver.yaml |
| 客户端卡顿 | 数据库性能问题 | 检查PostgreSQL连接数 |
9.2 资源监控方案
安装基础监控工具：
bash复制sudo apt install -y htop iotop iftop
推荐监控指标：
- 内存：确保至少2GB空闲
- CPU：Sy进程不应持续>70%
- 磁盘IO：await应<10ms
- 网络：Matrix流量通常<1Mbps/用户
10. 安全加固措施
10.1 防火墙配置
只开放必要端口：
bash复制sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
10.2 定期备份方案
数据库备份脚本：
bash复制#!/bin/bash
DATE=$(date +%Y%m%d)
pg_dump -U synapse -F c -b -f /backups/synapse_db_$DATE.dump synapse
tar czf /backups/synapse_config_$DATE.tar.gz /home/synapse/homeserver.yaml /etc/nginx
设置cron每周自动运行：
bash复制0 3 * * 0 /path/to/backup_script.sh
经过一周的实测，这个内网部署方案在20人左右的团队中运行稳定，平均延迟<200ms。最大的收获是发现PostgreSQL的连接池配置对性能影响极大——最初使用默认设置时，高峰期经常出现数据库连接耗尽的情况。后来调整为cp_min=5, cp_max=10后，系统负载明显下降。