配置 Synapse-Admin 管理面板

有了 Matrix Server，没有个图形化管理界面总觉得缺点什么。虽然命令行能解决所有问题，但管理用户、清空远程缓存、查看活跃房间，还是有个面板更直观。

Tip

延续之前的风格，依旧 Nginx 托管静态资源。

什么是 Synapse-Admin

synapse-admin 是一个基于 React 的纯前端项目。它不存储任何数据，只是通过调用你的 Synapse 管理员 API 来实现管理功能。所以：

你可以把它部署在任何地方（甚至是本地）。
它必须通过 HTTPS 访问（除非是 localhost），否则浏览器会拦截敏感请求。

1. 准备工作

已参考[[自建Matrix服务器]]搭建好 Synapse。
拥有一个管理员账号（如果你还没建，看前文第 8 节）。
一个二级域名（例如 admin.example.com），并已做好 A 记录指向服务器。

2. 下载并部署静态文件

由于是纯前端项目，我们直接拿官方编译好的 Release 版本最省事。

# 创建目录
sudo mkdir -p /var/www/synapse-admin
cd /tmp

# 获取最新版本链接（建议去 GitHub Release 确认最新版）
wget https://github.com/Awesome-Technologies/synapse-admin/releases/latest/download/synapse-admin.tar.gz

# 解压到 Web 目录
sudo tar -zxf synapse-admin.tar.gz -C /var/www/synapse-admin
sudo chown -R www-data:www-data /var/www/synapse-admin

3. 配置 Nginx 反向代理

新建一个虚拟主机配置：

sudo nano /etc/nginx/sites-available/synapse-admin

写入以下内容：

server {
    listen 80;
    server_name admin.example.com; # 换成你的管理域名

    root /var/www/synapse-admin;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

启用并申请证书：

sudo ln -s /etc/nginx/sites-available/synapse-admin /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# 申请 SSL 证书（必须，否则 API 调用会报错）
sudo certbot --nginx -d admin.example.com

4. 关键：解决跨域 (CORS) 限制

这是最容易卡住的一步。因为你的 admin.example.com 试图请求 matrix.example.com 的 API，如果没开跨域，浏览器会直接报错。

编辑 Synapse 的 homeserver.yaml：

sudo nano /etc/matrix-synapse/homeserver.yaml

找到 additional_resources 附近或者手动添加：

# 允许 Synapse-Admin 跨域访问 API
additional_resources:
  - names: ["_matrix/client/v3/admin"]
    compress: true

或者在 Nginx 的 Matrix 主配置（matrix.example.com 那套）里直接加 Header（这是最通用的办法）：

# 在 matrix.example.com 的 location / 块里
location / {
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE';
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';
        return 204;
    }
    add_header 'Access-Control-Allow-Origin' '*' always;
    
    proxy_pass http://127.0.0.1:8008;
    # ... 其他 proxy 配置 ...
}

修改完重启 Synapse 和 Nginx：

sudo systemctl restart matrix-synapse
sudo systemctl reload nginx

5. 登录使用

访问 https://admin.example.com，你会看到登录框：

Homeserver: https://matrix.example.com (注意带上 https)
Username: 你的管理员 ID (如 @admin:example.com)
Password: 管理员密码

登录后，你就能看到服务器的运行状态、用户列表、房间列表等。

6. 进阶玩法：清理远程媒体缓存

Matrix 跑久了，media_store 目录会迅速膨胀。在 Synapse-Admin 的 Media 模块里，你可以直观地清理那些很久之前的远程缓存，节省磁盘空间。

7. 常见坑点

Mixed Content Error: 如果你的管理面板没开 HTTPS，但 Matrix Server 开了，浏览器会禁止请求。
Access Token 报错: 确保你的账号确实有管理员权限。
跨域失败: 检查 Nginx 是否正确返回了 CORS 相关的 Header。

相关阅读：