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

一、项目目标与环境

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

---

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

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

1. 打开磁盘管理工具

1. 在 Ubuntu 桌面左侧的 Dock 栏中，点击 "显示应用程序" 图标（9个点的图标）。
2. 在搜索框中输入 "磁盘"。
3. 点击打开 "磁盘" 应用（GNOME Disks）。

2. 识别目标硬盘

1. 在"磁盘"应用的左侧窗格中，非常仔细地 找到你的 1TB 硬盘 。
   • 识别依据 ：根据容量（约 1.0 TB）、品牌或型号，切勿选错。
   • 数据安全：再次确认此硬盘内无需要保留的数据。
2. 点击选中该硬盘。在右侧窗格中，你可以看到其当前的分区表和文件系统格式。

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

1. 在右侧分区图形下方，点击 "---" 按钮（删除所选分区）。
2. 系统会弹出警告，提示此操作将删除所有数据。确认无误后，点击 "删除"。
3. 操作后，硬盘空间将显示为"空闲"。

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

1. 在"空闲"空间上，点击 "+" 按钮（创建新分区）。
2. 在弹出的窗口中：
   • 大小：使用默认的完整大小（约 1TB）。
   • 类型：选择"Ext4"。
   • 名称 ：可以填写一个易于识别的卷标，例如 MatrixData。
3. 点击 "下一步" ，然后点击 "创建"。系统会再次警告数据丢失，确认后开始格式化。

5. 挂载新格式化的硬盘

1. 格式化完成后，点击新创建分区下方的 三角形播放按钮 或 "挂载" 按钮。
2. 系统会要求输入密码。挂载成功后，记下 "内容" 下方显示的 挂载点路径 。通常为 /media/你的用户名/Data 的格式。

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. 设置开机自动挂载（图形界面操作）

1. 回到 "磁盘" 应用。
2. 点击新分区下方的 "挂载选项"（齿轮图标 ⚙️菜单选项）。
3. 在弹出窗口中：
   • 关闭 "用户会话默认值" 的开关。
   • 勾选 "系统启动时挂载"。
   • 在 "显示身份" 下拉菜单中，确保选择的是你的用户名。
   • 挂载点 ：可以保持默认（自动生成），或为了固定路径，手动设置为 /media/你的用户名/Data。
4. 点击 "确定" 并输入密码。
5. （可选）创建一个系统级的软链接，方便在配置中引用：

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

关键步骤：

1. 命令中 YOUR_LOCAL_IP 需替换，例如 -e SYNAPSE_SERVER_NAME=192.168.31.100。
2. 命令执行后，终端会显示一个 Registration shared secret （一串很长的随机字符）。请务必将其复制并保存到安全的地方，它是创建管理员账户的唯一凭证。

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. 测试服务器

1. 在 Ubuntu 本机的浏览器中访问：http://YOUR_LOCAL_IP:8008。
2. 如果看到包含 "Synapse is running" 字样的页面，说明核心服务正常。

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

1. 在团队成员的电脑或手机上下载安装 Element 客户端（可从 element.io 下载）。
2. 打开 Element，在登录页面，点击 "Edit" 或 "更改"。
3. 在 "Home server" 字段中，直接输入 http://YOUR_LOCAL_IP:8008。
4. 然后使用上面创建的账户（格式为 @admin:YOUR_LOCAL_IP）和密码登录。

---

六、维护与故障排查要点

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

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