MaimaiBot

一个用于获取舞萌 DX / 中二节奏登录二维码的 Telegram Bot，支持自动取消群组频道置顶消息。

功能特性

• 二维码获取 (/maicode)：获取舞萌 DX / 中二节奏的登录二维码

  • 支持 MaiQR 服务集成
  • 自动检测二维码复用冲突
  • 显示二维码有效期

• 群组置顶管理 (/unpin)：自动取消频道自动转发消息的置顶

  • /unpin on - 开启自动取消置顶
  • /unpin off - 关闭自动取消置顶
  • /unpin all - 取消所有历史置顶消息（仅群主）

• 权限管理：支持管理员和用户/群组白名单配置

快速开始

使用 Docker Compose（推荐）

1. 克隆仓库并进入目录：

git clone https://git.origami.pub/Bingxin/maimaibot.git
cd maimaibot

2. 复制配置文件并编辑：

cp config.example.yaml config.yaml
# 编辑 config.yaml，填入你的 Telegram Bot Token 和其他配置

3. 启动服务：

docker-compose up -d

手动编译运行

环境要求

• Go 1.23 或更高版本

编译

go mod download
go build -o maimaibot .

运行

./maimaibot config.yaml

配置说明

配置文件使用 YAML 格式，参考 config.example.yaml：

telegram:
  token: "YOUR_BOT_TOKEN_HERE"  # 从 @BotFather 获取

permission:
  admins:
    - 123456789  # 管理员用户 ID，可通过 @userinfobot 获取
  allowed_users: []  # 用户白名单，留空允许所有用户
  allowed_groups: []  # 群组白名单，留空允许所有群组

plugins:
  maicode:
    api_url: "http://127.0.0.1:5000"  # MaiQR 服务地址
    token: "maiqr"  # MaiQR 访问 token
    conflict_window_minutes: 10  # 冲突提醒窗口（分钟）
  
  unpin:
    state_file: "data/unpin.yaml"  # 状态持久化文件路径

获取 Telegram Bot Token

1. 在 Telegram 中找到 @BotFather
2. 发送 /newbot 创建新机器人
3. 按提示设置机器人名称和用户名
4. 获取 Bot Token 并填入配置文件

获取用户 ID

在 Telegram 中找到 @userinfobot，发送任意消息即可获取你的用户 ID。

MaiQR 服务配置

MaimaiBot 需要配合 MaiQR 服务使用来获取二维码。你可以：

1. 自行部署 mai-helper 服务
2. 配置 api_url 指向你的 MaiQR 服务地址
3. 设置正确的访问 token

使用说明

二维码获取

在 Telegram 中向机器人发送 /maicode 命令，机器人会返回舞萌 DX / 中二节奏的登录二维码。

注意事项：

• 二维码有时效性，请在有效期内使用
• 如果多个用户在短时间内获取二维码，会收到冲突提醒
• 冲突窗口时间可在配置文件中调整

群组置顶管理

在群组中使用 unpin 功能：

1. 将机器人添加到群组
2. 将机器人设为管理员，并开启"置顶消息"权限
3. 发送 /unpin on 开启自动取消置顶功能
4. 当频道自动转发的消息被置顶时，机器人会自动取消置顶

权限要求：

• /unpin on/off：需要群管理员权限
• /unpin all：仅群主可用

开发

项目结构

maimaibot/
├── internal/
│   ├── config/          # 配置管理
│   ├── permission/      # 权限检查
│   └── plugin/          # 插件系统
│       ├── maicode/     # 二维码获取插件
│       └── unpin/       # 置顶管理插件
├── main.go              # 程序入口
├── config.example.yaml  # 配置文件示例
├── Dockerfile           # Docker 镜像构建
└── docker-compose.yml   # Docker Compose 配置

添加新插件

1. 在 internal/plugin/ 下创建新的插件目录
2. 实现 Plugin 接口：

type Plugin interface {
    Name() string
    Commands() []string
    Handle(bot *tgbotapi.BotAPI, update tgbotapi.Update)
}

3. 在 main.go 中注册插件

构建 Docker 镜像

docker build -t maimaibot:latest .

CI/CD

项目使用 Forgejo Actions 进行自动化构建和发布：

• 自动构建多平台二进制文件（Linux/Windows，amd64/arm64）
• 自动构建并推送 Docker 镜像
• Tag 推送时自动创建 Release

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

致谢

• telegram-bot-api - Telegram Bot API Go 封装
• go-qrcode - 二维码生成库