三步搞定 mirai-login-solver-sakura 安装配置：QQ机器人登录验证码处理完整教程

【免费下载链接】mirai-login-solver-sakura项目地址: https://gitcode.com/gh_mirrors/mi/mirai-login-solver-sakura

mirai-login-solver-sakura（以下简称 MLSS）是面向 mirai 生态的一套登录验证处理工具，专门帮你解决 QQ 机器人登录时遇到的滑块验证、短信验证、设备锁验证、图片验证码等"拦路虎"。本教程面向新手，从核心原理到安装配置，一步步带你跑通这款免费的验证码处理工具，并附上高频避坑指南。

1. 项目速览：它到底解决了什么问题？

用过 mirai 的开发者都知道，QQ 机器人登录最大的痛点不是写代码，而是登录验证：新设备登录要滑块验证、异常登录要短信验证、登录地点异常还要设备锁验证。这些验证码交互繁琐，尤其在服务器（无桌面环境）上几乎无法完成。

mirai-login-solver-sakura 就是为这个问题而生的：它把 mirai 登录时产生的各种验证请求，通过二维码"搬运"到你的手机上，由配套的 Android App 完成验证，再把结果回传给服务端。一句话总结：

它不负责"破解"验证码，只负责把验证过程简化——用手机扫码代替在服务器上瞎折腾。

项目前身是 TxCaptchaHelper，目前已支持 GUI 图形界面下的短信验证、设备锁验证、滑块验证、Pic 4code 验证，并兼容 mirai-core 2.13.0 及以上版本（最新 dev 版本要求 2.15.0+）。

2. 核心原理：像"外卖跑腿"一样传递验证

很多人第一次接触会困惑：为什么验证码要传两遍？其实用"外卖跑腿"来比喻就很好懂了：

• 餐厅（服务器）：运行着 mirai 的服务器遇到了登录验证，就像餐厅出了道难题。
• 跑腿平台（MLSS 后端守护进程 SakuraTransmitDaemon）：服务器内置了一个轻量级 HTTP 服务，把验证请求打包成一个 JSON，并生成一张二维码。
• 骑手（配套 Android App）：你用手机 App 扫这张二维码，验证任务就"接单"了。
• 送餐（回调）：你在手机上完成滑块或短信验证后，App 把结果 POST 回服务器，登录流程继续。

整个过程中，MLSS 只负责数据的中转传递，核心逻辑在mirai-login-solver-sakura/src/main/kotlin/下的slovbroadcast/SakuraTransmitDaemon.kt（通信层）和resolver/SakuraLoginSolver.kt（界面层）中。更贴心的是，它还内建了一个可选的 SOCKS 隧道，让手机上的验证页面可以通过服务器转发流量，实现"手机扫一扫、服务器内网转发"的闭环。

3. 快速上手：三步完成安装与首次验证

Step 1：准备环境

先在服务器上获取项目源码：

git clone https://gitcode.com/gh_mirrors/mi/mirai-login-solver-sakura

Step 2：获取并安装产物

有两种方式拿到构建产物：

1. 官方 Releases 下载：下载mirai-login-solver-sakura-XXX.mirai2.jar（mirai-console 插件）和apk-release.apk（安卓应用）。
2. 从最新 CI 构建下载：直接下载 GitHub Actions 的 Artifacts 压缩包，里面包含全部最新构建成果，下图为 CI 构建成功界面。

把.mirai2.jar放入 mirai-console 的plugins目录，重启控制台，插件会自动注册为登录验证器（核心逻辑见console/ConsolePluginMain.kt）。

Step 3：扫码完成验证

当机器人登录遇到滑块验证时，桌面端会弹出窗口显示二维码（如上文首图），手机打开配套 App 扫描：

1. 确保手机与服务器处于同一局域网（同一个 Wi-Fi）。
2. 用 App 扫码，手机端自动打开验证页面。
3. 完成滑块/短信/设备锁验证后，点击提交，服务器端自动继续登录。

如果是在无桌面的云服务器上使用，则需要添加 JVM 参数-Dmirai.no-desktop=true启用命令行模式，配合JLineLoginSolver在终端中完成交互。

4. 核心模块拆解：三个模块各司其职

4.1 SakuraLoginSolver —— 桌面端的"验证管家"

文件位于resolver/SakuraLoginSolver.kt，继承自 mirai 的LoginSolver，负责把 mirai 抛出的各种验证请求翻译成用户可操作的窗口：滑块验证弹窗、图片验证码输入框、设备验证选择界面（短信/设备锁二选一）等。它是整个工具与 mirai 对接的门面。

4.2 SakuraTransmitDaemon —— 数据交换的"通信枢纽"

文件位于slovbroadcast/SakuraTransmitDaemon.kt，基于 Netty 实现，负责两件事：

• 请求分发：把验证请求打包成 JSON，通过GET /request/request/$id暴露给 App 拉取。
• 结果回收：App 通过POST /request/complete/$id回传验证结果，服务端据此继续登录。

它还内置了 SOCKS 隧道（默认开启，仅限连接qq.com域名的安全策略），这是它比普通验证工具更"省心"的地方。

4.3 ConsolePluginMain —— 模式切换的"总调度"

文件位于console/ConsolePluginMain.kt，是 mirai-console 插件的入口。它启动守护进程，然后根据运行环境自动选择验证器：有桌面环境用 GUI 版SakuraLoginSolver，无桌面环境则回退到JLineLoginSolver命令行版。开发者对接时也主要看这个类如何装配。

5. 配置指南：三个 JVM 参数就够用

MLSS 的配置极简，全部通过 JVM 系统属性指定，无需修改配置文件：

使用方式示例（mirai-console 启动参数）：

-Dmlss.no-tunnel=false -Dmlss.port=22333

选择端口的小技巧：云服务器上为22333单独放行防火墙后，就能避免每次重启换端口、反复改安全组的麻烦。

6. 常见问题与避坑技巧

Q1：扫码后 App 崩溃怎么办？

通常是 Android 系统 WebView 版本过低导致，更新 Android WebView 组件即可（可在应用商店搜索"Android System WebView"升级），这是最高频的问题。

Q2：提示 "No any server availalbe" 怎么排查？

说明手机连不上服务器，按顺序检查：

1. 云服务器：确认防火墙/安全组放行了22333（或随机端口）。
2. 局域网 Wi-Fi：检查路由器是否开启了AP 隔离，它会让设备间互相不可见。
3. 可以试着在服务器上ping自身 IP，刷新路由表后重试。

Q3：滑块验证反复失败？

尽量保证手机与服务器同一网络，且验证时不要切换 Wi-Fi。如果服务器开启了隧道限制，确认没有手动修改mlss.tunnel.limited=false后又放开代理，导致异常流量被服务端拒绝。

7. 结语与延伸

mirai-login-solver-sakura 用"扫码接力"的思路，把原本只能在桌面端完成的登录验证搬到手机上，让无桌面的云服务器也能轻松跑通 QQ 机器人登录，是 mirai 生态中少见的"配置量小、上手快"的验证处理方案。

想深入了解，建议阅读以下源码入口：

• 验证器实现：resolver/SakuraLoginSolver.kt
• 通信守护进程：slovbroadcast/SakuraTransmitDaemon.kt
• 插件主入口：console/ConsolePluginMain.kt

如果你需要自己对接 MLSS 做二次开发，README 中的数据交换章节还给出了二维码 JSON 格式、/request/request/$id与/request/complete/$id的完整协议说明，照葫芦画瓢即可写出自己的客户端。希望这份教程能帮你少走弯路，三分钟跑通整套验证流程！

【免费下载链接】mirai-login-solver-sakura项目地址: https://gitcode.com/gh_mirrors/mi/mirai-login-solver-sakura