matrixdotorg/mjolnir

Mjolnir

概述

Mjolnir是一款针对Matrix协议的综合审核工具，旨在保护Matrix服务器和社区免受***行为侵扰。它不仅提供服务器级别的保护，还能帮助社区在不使用个人账号的情况下有效管理房间，同时支持作为Synapse模块将审核规则应用于整个家庭服务器（homeserver）。

核心功能和特性

• 全方位审核保护：作为一体化审核工具，可防御***邀请、垃圾消息及其他不良内容，提供服务器级和社区级双重保护。
• 丰富审核能力：默认支持多种审核操作，包括用户封禁、消息删除、反垃圾信息、服务器访问控制列表（ACL）管理、房间目录变更、房间别名转移、账号停用、房间关闭等。
• Synapse模块集成：提供Synapse模块，可将机器人使用的审核规则集应用于整个家庭服务器，实现全服务器范围的规则统一。

使用场景和适用范围

• Matrix服务器管理员需要保护服务器免受***注册用户、垃圾消息侵扰。
• 社区管理员希望集中管理多个房间的审核规则，无需使用个人账号进行审核操作。
• 需要保护加密房间的社区，通过Pantalaimon实现加密管理房间的审核。
• 希望将统一审核规则应用于整个家庭服务器的场景，通过Synapse模块实现全服务器规则同步。

使用方法和配置说明

机器人配置

前置要求

• 推荐使用Pantalaimon：若需加密管理房间或审核加密房间，建议部署https://github.com/matrix-org/pantalaimon%E4%BB%A5%E6%94%AF%E6%8C%81%E5%8A%A0%E5%AF%86%E9%80%9A%E4%BF%A1%E3%80%82
• 访问令牌获取（非加密场景）：
  1. 在隐身/私密窗口打开Riot，以机器人账号登录。
  2. 进入设置中的“帮助与支持”选项卡，复制访问令牌。
  3. 重要：复制后直接关闭窗口，不要登出（登出会使令牌失效）。

注意事项

• 避免速率限制：Mjolnir需要不受速率限制，配置方法参考https://github.com/matrix-org/synapse/issues/6286%E3%80%82
• 管理员权限：执行账号停用、别名转移、房间关闭等操作时，Mjolnir需拥有服务器管理员权限。

Docker安装（推荐）

Mjolnir已发布至Docker Hub：https://hub.docker.com/r/matrixdotorg/mjolnir%EF%BC%8C%E4%B9%9F%E5%8F%AF%E8%87%AA%E8%A1%8C%E6%9E%84%E5%BB%BA%E9%95%9C%E5%83%8F%E3%80%82

安装步骤

bash
# 克隆仓库
git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir

# 创建并编辑配置文件（不建议修改数据路径）
mkdir -p /etc/mjolnir/config
cp config/default.yaml /etc/mjolnir/config/production.yaml
nano /etc/mjolnir/config/production.yaml  # 编辑配置

# 启动容器
docker run --rm -it -v /etc/mjolnir:/data matrixdotorg/mjolnir:latest

手动构建（替代安装方式）

需依赖yarn和Node 14。

bash
# 克隆仓库
git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir

# 安装依赖并构建
yarn install
yarn build

# 创建并编辑配置文件（建议修改数据路径）
cp config/default.yaml config/development.yaml
nano config/development.yaml  # 编辑配置

# 启动
node lib/index.js

快速入门指南

机器人启动后，执行以下命令完成初始设置：

1. 创建封禁列表：!mjolnir list create COC code-of-conduct-ban-list
   （创建短代码为COC、别名为#code-of-conduct-ban-list:example.org的封禁列表，自动邀请您加入管理房间）
2. 设置默认封禁列表：!mjolnir default COC
   （将刚创建的列表设为默认，简化后续封禁命令）
3. 查阅https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md%E4%BA%86%E8%A7%A3%E8%AF%A6%E7%BB%86%E6%93%8D%E4%BD%9C%E3%80%82
4. 输入!mjolnir help查看所有可用命令。

Synapse模块配置

要求：Synapse 1.53.0及以上版本。

该模块可将Mjolnir的审核规则应用于整个家庭服务器，主要用于阻止来自不受信任家庭服务器/用户的邀请，需手动配置。

安装步骤

1. 安装模块：
   将模块安装到Synapse的Python环境中：

   bash
   pip install -e "git+https://github.com/matrix-org/mjolnir.git#egg=mjolnir&subdirectory=synapse_antispam"
   

2. 配置homeserver.yaml：
   在配置文件中添加模块配置，示例如下：

   yaml
   modules:
     - module: mjolnir.Module
       config:
         # 阻止封禁列表中的服务器/用户发送邀请（默认true）
         block_invites: true
         # 将封禁列表中的服务器/用户发送的消息标记为垃圾信息（默认false，标记后消息显示为空）
         block_messages: false
         # 通过过滤用户ID和显示名称，从用户目录搜索中移除封禁列表中的用户（默认false）
         block_usernames: false
         # 需遵循的封禁列表房间ID（仅支持房间ID，不支持别名或永久链接；服务器需已加入这些房间）
         ban_lists:
            - "!roomid:example.org"
         # 消息长度限制（可选）
         message_max_length:
            # 限制消息体字符数（默认无限制，超出Synapse规范的事件大小限制除外）
            # threshold: 510  # 示例：限制为510字符
            
            # 指定仅在某些房间应用长度限制（默认所有房间）
            # rooms:
            #   - "!vMvyOCeCxHsggkmALd:localhost:9999"
            
            # 对来自远程服务器的消息也应用长度限制（默认仅限制本服务器消息）
            # remote_servers: true
   

3. 重启Synapse：
   修改配置后需重启Synapse使模块生效。

注意事项

• 服务器需已加入ban_lists中指定的房间，模块不会自动加入房间。
• 该模块虽被描述为“垃圾信息检查器”，但功能不限于反垃圾信息。

启用可读滥用报告

Mjolnir 1.2及以上版本支持将滥用报告替换为房间内可读格式，无需通过管理员API获取数据，需以下两步配置：

1. 配置Mjolnir：
   在Mjolnir配置文件（通常为/etc/mjolnir/config/production.yaml）中，复制default.yaml中的web部分（1.20版本新增），并启用web和abuseReporting：

   yaml
   web:
     enabled: true
     port: 9000  # 配置端口
     host: 0.0.0.0  # 建议设为localhost仅允许反向代理访问
     abuseReporting:
       enabled: true
   

2. 设置反向代理：
   将请求重定向至Mjolnir的API端点。以Nginx为例，配置如下（参考test/nginx.conf）：

   nginx
   location ~ ^/_matrix/client/r0/rooms/([^/]*)/report/(.*)$ {
       proxy_pass http://host:port/api/1/report/$1/$2;  # host为Mjolnir主机，port为配置的web端口
   }
   

安全注意事项

• 该功能仅能提取未加密房间的信息，且需满足：请求者为房间成员、曾见证事件、事件未加密且未被删除/编辑。
• 为确保安全，建议将web服务器配置为仅接收来自反向代理的请求（如host: localhost）。若对安全性有顾虑，可禁用此功能。