Leisuretimedock/LTD-ManaagerBot

Fork 0

3944Realms f3af0b7134 docs: 完善文档

2026-06-09 13:31:05 +08:00

12 KiB

Raw Blame History

LTD-ManagerBot 模块文档

快速开始

复制 src/main/resources/ 下的示例配置到 config/
编辑 config/application.yaml — 设置数据库、API 地址、密钥
编辑 config/module.yaml — 取消注释并配置需要的模块
如需使用邀请码或白名单审计模块，将 SQL 模板放入 config/sql/
启动机器人

新模块必需的 `application.yaml` 配置

# 白名单系统 API (WhitelistAuditModule 必需)
whitelist-system:
  url: "https://whitelist.your-server.top"
  encrypted-token: "your-api-token-here"

基础设施模块

GroupMessagePollingModule (群消息轮询模块)

按固定间隔轮询 QQ 群消息历史，通过 SharedFlow<List<MsgHistorySpecificMsg>> 向其他模块分发消息。

- name: "talkGroup"
  type: "GROUP_MESSAGE_POLLING_MODULE"
  enabled: true
  config:
    target-group-id: 538751386       # 目标群号
    poll-interval-millis: 5000       # 轮询间隔(毫秒)，可选，默认5000
    msg-history-check: 15            # 每次检查的历史消息数，可选，默认15

MailModule (邮件模块)

通过 SMTP 发送邮件。InvitationCodesModule 和 WhitelistAuditModule 会使用此模块。

- name: "talkGroup"
  type: "MAIL_MODULE"
  enabled: true

SMTP 设置在 application.yaml → mail: 段配置。

新模块

RCON 命令模块

类型: RCON_COMMAND_MODULE

允许指定用户在 QQ 群中执行 Minecraft RCON 命令。通过黑名单机制阻止危险操作，非授权用户无法执行。

执行流程

QQ群: "rcon list"
    │
    ├── 用户不在 admin-ids 中 → 回复: "你没有权限执行 RCON 命令"
    ├── 命令匹配 command-blocklist → 回复: "命令已被阻止"
    └── 通过 RCON 二进制执行 → 回复执行结果

配置示例

- name: "talkGroup"
  type: "RCON_COMMAND_MODULE"
  enabled: true
  dependencies:
    - name: "talkGroup"
      type: "GROUP_MESSAGE_POLLING_MODULE"
  config:
    self-id: 3327379836
    self-nick-name: "Bot"
    command-prefix: "rcon"                     # QQ群触发前缀
    admin-ids: [2561098830]                    # 允许执行RCON的QQ号
    rcon-timeout-sec: 5                        # RCON超时(秒)
    command-blocklist:                         # 危险命令黑名单(前缀匹配)
      - "stop"
      - "restart"
      - "op"
      - "deop"
      - "whitelist"
      - "ban"
      - "ban-ip"
      - "kick"
      - "debug"
      - "execute"

配置项

字段	类型	必填	默认值	说明
`self-id`	long	是	—	机器人 QQ 号
`self-nick-name`	string	是	—	机器人昵称
`command-prefix`	string	是	—	QQ 群触发前缀
`admin-ids`	long[]	是	—	允许执行 RCON 的 QQ 号列表
`command-blocklist`	string[]	是	—	危险命令黑名单(不区分大小写，自动去除 `/` 前缀)
`rcon-timeout-sec`	long	否	`5`	RCON 超时时间(秒)

RCON 二进制路径和配置文件路径从 application.yaml → tools.rcon 读取。

黑名单匹配规则

黑名单使用前缀匹配，自动去除前置 /：

"stop" 阻止: stop, stop 10s, /stop, /minecraft:stop
"ban" 阻止: ban Steve, ban-ip, /ban 等

Gitea Webhook 模块

类型: GITEA_WEBHOOK_MODULE

启动嵌入式 HTTP 服务器，接收 Gitea Webhook 事件，格式化后推送通知到 QQ 群。

支持的事件类型

事件	QQ 消息格式
`push`	推送者、分支、提交数、前5条提交摘要、对比链接
`issues`	操作(已创建/已关闭/已重新打开)、标题、内容预览、链接
`pull_request`	操作、分支流转(head → base)、状态、链接
`create`	创建的分支/标签、创建者
`delete`	删除的分支/标签、操作者
`release`	标签名、版本名、内容预览、草稿/预发布标记
`repository`	仓库操作(已创建/已删除/已转移)
`fork`	源仓库 → Fork 仓库

配置示例

- name: "talkGroup"
  type: "GITEA_WEBHOOK_MODULE"
  enabled: true
  config:
    webhook-port: 8080                         # 监听端口
    webhook-path: "/gitea-webhook"             # Webhook 路径
    webhook-secret: "your-webhook-secret"      # HMAC-SHA256 密钥
    target-group-id: 538751386                 # 推送 QQ 群号
    events:                                    # 监听事件列表(空=全部)
      - "push"
      - "issues"
      - "pull_request"
      - "create"
      - "delete"
      - "release"

配置项

字段	类型	必填	默认值	说明
`webhook-port`	int	是	—	HTTP 服务器监听端口
`webhook-path`	string	否	`/gitea-webhook`	Webhook 端点路径
`webhook-secret`	string	否	`""`	HMAC-SHA256 签名验证密钥，为空则跳过验证
`target-group-id`	long	是	—	推送通知的目标 QQ 群号
`events`	string[]	否	全部	监听的事件类型列表

Gitea 端设置

在 Gitea 仓库 → 设置 → Webhooks → 添加 Webhook → Gitea：

目标 URL: http://<服务器IP>:8080/gitea-webhook
密钥: 与 webhook-secret 一致
触发条件: 勾选需要的事件

安全性

签名验证: 通过 HMAC-SHA256 验证 X-Gitea-Signature 请求头
生产环境建议务必设置 webhook-secret

白名单审计模块

类型: WHITELIST_AUDIT_MODULE

定期检查白名单群成员与白名单 API 的一致性。自动拒绝已离开白名单群的用户，设置宽限期供用户通过主群关键词重新激活。支持管理员手动触发审计。

生命周期状态

在白名单群中 ───────────────────────────────► 正常(无操作)
    │
    └── 用户退出群 ──► 检测到离群 ──► 已被拒绝(宽限期开始)
                            │
                            ├── 主群发关键词 ──► 已重新激活
                            ├── 进入警告窗口 ──► 发送邮件/群通知
                            └── 宽限期过 ──► 永久删除

双触发器系统

触发器	群	谁可使用	操作
关键词 (如"重新激活")	主群	任何待处理用户	重新激活白名单
审计命令 (如"审计")	白名单群	仅 `audit-allowed-ids`	立即执行审计 + 输出结果

配置示例

- name: "talkGroup"
  type: "WHITELIST_AUDIT_MODULE"
  enabled: true
  dependencies:
    - name: "talkGroup"                        # 主群轮询 (重新激活关键词)
      type: "GROUP_MESSAGE_POLLING_MODULE"
    - name: "whitelistGroup"                   # 白名单群轮询 (审计命令)
      type: "GROUP_MESSAGE_POLLING_MODULE"
    - name: "talkGroup"                        # 邮件模块 (enable-email:true 时)
      type: "MAIL_MODULE"
  config:
    self-id: 3327379836
    # ---- 权限控制 ----
    filter-qq-list: [2561098830, 3327379836]   # 永不自动拒绝的保护列表
    audit-allowed-ids: [2561098830]            # 可执行手动审计的管理员QQ
    # ---- 白名单群手动审计 ----
    whitelist-group-polling-dep-name: "whitelistGroup"
    audit-command-prefix: "审计"               # 白名单群触发关键词
    # ---- 重新激活 ----
    re-activation-keywords:                    # 主群重新激活关键词
      - "重新激活"
      - "激活白名单"
      - "reactivate"
    # ---- 时间参数 ----
    grace-period-days: 7                       # 宽限期(天)
    expiry-warning-days: 2                     # 到期前N天发警告
    poll-interval-minutes: 60                  # 自动审计间隔(分钟)
    # ---- 邮件通知 ----
    enable-email: false                        # 是否启用邮件通知

配置项

字段	类型	必填	默认值	说明
`self-id`	long	是	—	机器人 QQ 号
`filter-qq-list`	long[]	是	—	保护列表，模块不会自动拒绝这些 QQ 的白名单
`audit-allowed-ids`	long[]	是	—	允许在白名单群执行手动审计的 QQ
`whitelist-group-polling-dep-name`	string	是	—	白名单群轮询模块的依赖名
`audit-command-prefix`	string	否	`"审计"`	白名单群触发手动审计的命令
`re-activation-keywords`	string[]	是	—	主群中触发重新激活的关键词列表
`grace-period-days`	int	是	—	被拒绝后允许重新激活的天数
`expiry-warning-days`	int	是	—	宽限期到期前多少天发送警告
`poll-interval-minutes`	long	否	`60`	自动审计间隔(分钟)
`enable-email`	boolean	否	`false`	是否发送邮件通知(需 MailModule 依赖)

手动审计输出示例

审计完成
────────────────
白名单总数: 42
在群正常: 35 人
新发现不在群(已拒绝): 2 人
宽限期中: Steve(剩5天), Alex(剩2天)
已过期删除: 1 人
过滤列表跳过: 3 人

状态持久化

审计状态保存在 data/whitelist_audit_state.json，附自动备份。机器人重启不会丢失待处理记录。

依赖关系

依赖模块	类型	是否必需	用途
主群轮询	`GROUP_MESSAGE_POLLING_MODULE`	是	监听主群重新激活关键词
白名单群轮询	`GROUP_MESSAGE_POLLING_MODULE`	是	监听审计命令 + 获取群成员列表
邮件模块	`MAIL_MODULE`	`enable-email: true` 时	发送邮件通知

白名单 API 配置

API 地址和密钥在 application.yaml 的 whitelist-system: 段配置(启动后自动加密):

whitelist-system:
  url: "https://whitelist.your-server.top"
  encrypted-token: "your-api-token-here"

邮件通知时机

触发条件	邮件主题
首次检测离群 → 被拒绝	`LTD白名单审计通知` — 告知已被拒，宽限期 N 天
重新激活后再离群 → 再次拒绝	`LTD白名单审计通知` — 告知再次被拒
进入警告窗口	`LTD白名单即将过期` — 剩余 N 天
宽限期过 → 永久删除	`LTD白名单已删除` — 已永久删除
关键词重新激活成功	`LTD白名单已重新激活` — 提醒加群

配置参考

SQL 模板

部分模块(InvitationCodesModule、GroupRequestHandlerModule)使用 config/sql/ 下的 SQL 模板文件。模板使用 ${placeholder} 语法：

-- config/sql/invitation/query_qualification.sql
SELECT q.player_id, q.effective, q.is_used, q.qq, q.status
FROM ltd_manager_bot.qualified_user_info q
WHERE q.qq IN (${placeholders})

代码中使用：

val sql = SqlTemplate.fromFile("invitation/query_qualification.sql")
val result = sql.bind("placeholders" to "?, ?, ?")

消息过滤管道

所有消息驱动的模块使用统一的 TriggerMessageFilter 管道：

IgnoreSelfFilter → NewMessageFilter → KeywordFilter → [CooldownFilter] → handler

管道确保：机器人自己的消息被忽略、只处理新消息、只有匹配关键词的消息才会到达业务处理器。

12 KiB Raw Blame History Unescape Escape

LTD-ManagerBot 模块文档

目录

快速开始

新模块必需的 application.yaml 配置

基础设施模块

GroupMessagePollingModule (群消息轮询模块)

MailModule (邮件模块)

新模块

RCON 命令模块

执行流程

配置示例

配置项

黑名单匹配规则

Gitea Webhook 模块

支持的事件类型

配置示例

配置项

Gitea 端设置

安全性

白名单审计模块

生命周期状态

双触发器系统

配置示例

配置项

手动审计输出示例

状态持久化

依赖关系

白名单 API 配置

邮件通知时机

配置参考

SQL 模板

消息过滤管道

12 KiB

Raw Blame History

新模块必需的 `application.yaml` 配置