【办公平台】在 Ubuntu 上部署 Synapse Matrix 服务器（本地网络版）
一、项目目标与环境
- 目标：在本地网络中为团队搭建 Matrix 通信服务器，优先满足文件传输需求。
- 服务器：Ubuntu 桌面版（带有图形界面）。
- 存储：一块已格式化但需改为 Ext4 文件系统的旧硬盘（1TB），用于永久保存服务器数据。
- 网络：直接使用本地 IP 地址访问，避免域名解析的复杂性。
- 警告：以下格式化操作将永久清除硬盘上所有数据。请再次确认硬盘内没有重要文件。
二、重新格式化并挂载 1TB 数据盘
我们将使用图形界面工具将硬盘重新格式化为 Ext4 格式并挂载。
1. 打开磁盘管理工具
- 在 Ubuntu 桌面左侧的 Dock 栏中，点击 “显示应用程序” 图标（9个点的图标）。
- 在搜索框中输入 “磁盘”。
- 点击打开 “磁盘” 应用（GNOME Disks）。
2. 识别目标硬盘
- 在“磁盘”应用的左侧窗格中，非常仔细地找到你的 1TB 硬盘。
- 识别依据：根据容量（约 1.0 TB）、品牌或型号，切勿选错。
- 数据安全：再次确认此硬盘内无需要保留的数据。
- 点击选中该硬盘。在右侧窗格中，你可以看到其当前的分区表和文件系统格式。
3. 删除现有分区（清除旧格式）
- 在右侧分区图形下方，点击 “—” 按钮（删除所选分区）。
- 系统会弹出警告，提示此操作将删除所有数据。确认无误后，点击 “删除”。
- 操作后，硬盘空间将显示为“空闲”。
4. 创建新分区并格式化为 Ext4
- 在“空闲”空间上，点击 “+” 按钮（创建新分区）。
- 在弹出的窗口中：
- 大小：使用默认的完整大小（约 1TB）。
- 类型：选择“Ext4”。
- 名称：可以填写一个易于识别的卷标，例如
MatrixData。
- 点击 “下一步”，然后点击 “创建”。系统会再次警告数据丢失，确认后开始格式化。
5. 挂载新格式化的硬盘
- 格式化完成后，点击新创建分区下方的 三角形播放按钮 或 “挂载” 按钮。
- 系统会要求输入密码。挂载成功后，记下 “内容” 下方显示的 挂载点路径。通常为
/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. 设置开机自动挂载（图形界面操作）
- 回到 “磁盘” 应用。
- 点击新分区下方的 “挂载选项”（齿轮图标 ⚙️菜单选项）。
- 在弹出窗口中：
- 关闭 “用户会话默认值” 的开关。
- 勾选 “系统启动时挂载”。
- 在 “显示身份” 下拉菜单中，确保选择的是你的用户名。
- 挂载点：可以保持默认（自动生成），或为了固定路径，手动设置为
/media/你的用户名/Data。
- 点击 “确定” 并输入密码。
- （可选）创建一个系统级的软链接，方便在配置中引用：
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
关键步骤：
- 命令中
YOUR_LOCAL_IP需替换，例如-e SYNAPSE_SERVER_NAME=192.168.31.100。 - 命令执行后，终端会显示一个
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. 测试服务器
- 在 Ubuntu 本机的浏览器中访问：
http://YOUR_LOCAL_IP:8008。 - 如果看到包含 “Synapse is running” 字样的页面，说明核心服务正常。
3. 客户端登录（以 Element 为例）
- 在团队成员的电脑或手机上下载安装 Element 客户端（可从 element.io 下载）。
- 打开 Element，在登录页面，点击 “Edit” 或 “更改”。
- 在 “Home server” 字段中，直接输入
http://YOUR_LOCAL_IP:8008。 - 然后使用上面创建的账户（格式为
@admin:YOUR_LOCAL_IP）和密码登录。
六、维护与故障排查要点
- 数据位置：所有数据（数据库、上传的文件）均保存在
/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目录即可。
部署完成。现在可以创建房间，邀请团队成员加入，开始使用文件传输和团队聊天功能。
