【办公平台】在 Ubuntu 上部署 Synapse Matrix 服务器（本地网络版）

一、项目目标与环境

• 目标：在本地网络中为团队搭建 Matrix 通信服务器，优先满足文件传输需求。
• 服务器：Ubuntu 桌面版（带有图形界面）。
• 存储：一块已格式化但需改为 Ext4 文件系统的旧硬盘（1TB），用于永久保存服务器数据。
• 网络：直接使用本地 IP 地址访问，避免域名解析的复杂性。
• 警告：以下格式化操作将永久清除硬盘上所有数据。请再次确认硬盘内没有重要文件。

二、重新格式化并挂载 1TB 数据盘

我们将使用图形界面工具将硬盘重新格式化为 Ext4 格式并挂载。

1. 打开磁盘管理工具

2. 识别目标硬盘

3. 删除现有分区（清除旧格式）

4. 创建新分区并格式化为 Ext4

5. 挂载新格式化的硬盘

6. 创建专用数据目录并设置权限

打开终端（Ctrl+Alt+T），执行以下命令（请将 /media/你的用户名/Data 替换为你实际的挂载点）：

# 1. 在挂载的硬盘上，创建一个名为 “matrix-synapse” 的专属目录。
sudo mkdir -p /media/你的用户名/Data/matrix-synapse

# 2. 将该目录的所有权更改为当前用户，方便操作。
sudo chown -R $USER:$USER /media/你的用户名/Data/matrix-synapse

# 3. 检查目录是否创建成功并确认权限。
ls -ld /media/你的用户名/MatrixData/matrix-synapse

预期输出：应显示目录信息，且所有者为你的用户名。

7. 设置开机自动挂载（图形界面操作）

sudo ln -s /media/你的用户名/Data/matrix-synapse /matrix-data

现在，你的硬盘已准备就绪。数据将最终存储在 /media/你的用户名/Data/matrix-synapse 目录中。

三、安装 Docker 与 Docker Compose

这是运行 Synapse 容器的基础环境。

# 1. 更新系统包列表
sudo apt update && sudo apt upgrade -y
# 2. 安装 Docker
sudo apt install docker.io -y
# 3. 安装 Docker Compose 插件
sudo apt install docker-compose -y
# 4. 将当前用户添加到 docker 组，以便无需 sudo 运行（需重新登录生效）
sudo usermod -aG docker $USER
# 5. 设置 Docker 开机自启
sudo systemctl enable –now docker

重要提示：用户组更改在当前登录会话中不会立即生效。请执行以下操作之一：

• 最简单的方法：完全注销 Ubuntu 桌面，然后重新登录。
• 或者，在终端输入 newgrp docker，但这只对当前终端窗口有效。

四、部署与配置 Synapse

1. 创建项目工作目录

我们在用户主目录下创建用于管理配置的文件夹，并连接到数据盘。

# 1. 在主目录创建 synapse 配置目录
mkdir -p ~/synapse
# 2. 进入工作目录
cd ~/synapse

2. Docker Compose 配置文件

# 下载官方提供的 docker-compose 示例文件
wget -O docker-compose.yml https://raw.githubusercontent.com/matrix-org/synapse/develop/docker/contrib/docker-compose.yml

或

cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
synapse:
image: matrixdotorg/synapse:latest
container_name: synapse
restart: unless-stopped
ports:
– "8008:8008"
volumes:
– /media/ubuntu/MatrixData/matrix-synapse:/data
environment:
– SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
– SYNAPSE_CONFIG_DIR=/data
– UID=1000
– GID=1000
user: "1000:1000"
EOF

3. 生成 Synapse 主配置文件

我们需要生成一个配置文件。请将 YOUR_LOCAL_IP 替换为你 Ubuntu 电脑的本地 IP 地址（可通过在终端输入 hostname -I 命令查询，通常第一个地址就是）。

# 生成配置。注意：-v 参数将容器的 /data 目录映射到了我们硬盘上的目录。
docker run -it –rm \\
-v /media/ubuntu/MatrixData/matrix-synapse:/data \\
-e SYNAPSE_SERVER_NAME=YOUR_LOCAL_IP \\
-e SYNAPSE_REPORT_STATS=no \\
matrixdotorg/synapse:latest generate

关键步骤：

4. 修改配置文件以适应本地 IP 访问

编辑生成的配置文件 /media/ubuntu/MatrixData/matrix-synapse/homeserver.yaml（路径请根据你的实际挂载点调整）。

# 使用文本编辑器打开配置文件（例如使用 nano）
sudo nano /media/ubuntu/MatrixData/matrix-synapse/homeserver.yaml

找到并修改/确认以下三处关键配置（可使用 Ctrl+W 进行搜索）：

• server_name：应已是你设置的 IP 地址，核对即可。
• public_baseurl：取消注释（删除行首的 #），并将其值设置为 http://YOUR_LOCAL_IP:8008。
• max_upload_size：取消注释，将其值修改为例如 "1024M"（即1GB），以支持大文件上传。
  按 Ctrl+X，然后按 Y 和 回车 保存退出。

5. 修改 Docker Compose 文件以固定数据路径

编辑 ~/synapse/docker-compose.yml，确保数据卷映射正确指向硬盘目录。

nano ~/synapse/docker-compose.yml

找到 volumes: 部分，将其修改为（路径请根据你的实际挂载点调整）：

volumes:
– /media/ubuntu/MatrixData/matrix–synapse:/data

保存并退出。

6. 启动 Synapse 服务器

# 确保在 ~/synapse 目录下执行
cd ~/synapse
docker compose up -d
# 查看容器运行状态，应为 “running”
docker compose ps

五、创建管理员账户并测试

1. 创建管理员用户

在 ~/synapse 目录下执行：

docker compose exec synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml

• 根据提示输入用户名（如 admin）、密码。
• 当询问 “Make admin?” 时，必须输入 yes。

2. 测试服务器

3. 客户端登录（以 Element 为例）

六、维护与故障排查要点

• 数据位置：所有数据（数据库、上传的文件）均保存在 /media/你的用户名/MatrixData/matrix-synapse 目录下。
• 服务管理：
  • 停止：docker compose down
  • 重启：docker compose restart
  • 查看实时日志：docker compose logs -f synapse
• 文件上传失败：
• 检查 homeserver.yaml 中 max_upload_size 和 public_baseurl 的设置。
• 检查客户端输入的服务器地址是否与 public_baseurl 完全一致（IP和端口）。
• 备份：定期备份整个 /media/你的用户名/MatrixData/matrix-synapse 目录即可。

部署完成。现在可以创建房间，邀请团队成员加入，开始使用文件传输和团队聊天功能。