登录验证码处理辅助工具如何上手：mirai-login-solver-sakura 目录、入口与配置全解析

登录验证码处理辅助工具如何上手：mirai-login-solver-sakura 目录、入口与配置全解析

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

mirai-login-solver-sakura 是一套面向 mirai 机器人框架的登录验证码处理辅助工具，它的核心价值是：把滑块验证、短信验证、设备锁验证等麻烦的登录流程，从"卡死在终端"变成"弹个窗口点几下"，甚至交给手机 App 扫码完成。本文不按传统教程平铺，而是从"它到底怎么帮你"讲起，逆向带你拆懂它的代码结构、启动入口和配置开关。

一、先看它解决了什么痛点

用 mirai 登录 QQ 机器人账号时，腾讯会不定期抛各种安全验证：滑块验证码、图片验证码、短信验证、设备锁。这些验证码大多要"人肉"处理，默认终端模式下很难操作。mirai-login-solver-sakura 的思路是——它只负责验证过程中的数据传递，把验证请求转成可视化窗口或二维码，让人方便地完成验证，再把结果交还给 mirai。

它的能力矩阵在 README 里写得很清楚：

跑起来之后，你会看到这样的处理界面——滑块验证会弹出窗口，提示你用配套 App 扫码：

遇到设备锁/安全认证时，则会列出"短信验证""设备锁验证"等选项，你选一个即可：

一句话总结它的运行形态：桌面端（mirai-console 插件）负责把验证转成二维码/窗口，手机端（配套 Android App）负责扫码和操作，两端通过内网 HTTP + Socks 隧道互通。

二、逆向拆解：从运行形态反推目录结构

理解了"双端协作"的形态，再看目录就豁然开朗。仓库根目录下只躺着两个真正的源码模块：

settings.gradle ← 模块注册表 gradle.properties ← 版本号等公共属性 mirai-login-solver-sakura/ ← 核心模块：桌面端逻辑（Kotlin） android/ ← 配套 App 模块（Android/Kotlin） ci-helper/ ← 构建辅助工具（Java，一般不用动）

2.1 核心模块内的"分工地图"

真正需要重点关注的，是mirai-login-solver-sakura/src/main/kotlin/下的几个包，它们按职责清晰分层：

其中SakuraTransmitDaemon是全项目的"神经中枢"——它启动了用于数据交换的 HTTP 服务器，把验证请求包装成二维码里的 JSON，App 扫码后通过内网 IP 回传验证结果。协议细节在 README 的"数据交换"一节有完整 JSON 示例，对接自己客户端的开发者可以从这里入手。

2.2 两个模块怎么被组装起来

settings.gradle只做了一件事：声明模块存在。

rootProject.name = 'mirai-login-solver-sakura' include ':mirai-login-solver-sakura' include ':ci-helper'

也就是说，android/目录在 Gradle 根工程里其实没有注册，它由 CI 流程单独构建出apk-release.apk。想要本地只跑核心模块，执行核心模块下的构建任务即可；想完整构建两端的产物，则按 CI 的流程分别处理。

三、手把手看懂启动入口：从一行 Kotlin 到弹出窗口

整个程序真正被 mirai-console 加载的地方只有一个：console/ConsolePluginMain.kt中的ConsolePluginMain对象。它是标准 mirai-console 插件的写法，关键逻辑浓缩在onLoad()里，三步走：

// 1. 启动数据中转服务器（HTTP + Socks 隧道） val server = SakuraTransmitDaemon(...) server.bootServer() // 2. 判断当前是否有图形桌面环境 val noDesktop = System.getProperty("mirai.no-desktop") != null || GraphicsEnvironment.isHeadless() // 3. 按环境挑选不同的验证处理器 val solver = if (noDesktop) { JLineLoginSolver(server) // 服务器/无桌面 → 命令行交互 } else { SakuraLoginSolver(server) // 有桌面 → 弹窗交互 }

这段代码揭示了两个关键设计：

• 自动降级：云服务器没有图形界面，程序会自动切到JLineLoginSolver或CommonTerminalLoginSolver，靠终端输入完成验证，不需要改代码。
• 挂钩时机：通过contributeBotConfigurationAlterer把选中的solver塞进每个 Bot 的登录配置里，mirai 登录遇到验证时就会回调这个对象。

再看桌面端的主角resolver/SakuraLoginSolver.kt。它继承 mirai 的LoginSolver，核心是重写几个回调方法：

override suspend fun onSolveSliderCaptcha(bot: Bot, url: String): String? { // 弹出滑块验证窗口，可选“内嵌旧版 Helper”或“生成二维码给 App 扫” } override suspend fun onSolveDeviceVerification(bot, requests): DeviceVerificationResult { // 弹出“短信验证 / 设备锁验证”选择窗口 } override fun createQRCodeLoginListener(bot: Bot): QRCodeLoginListener { // 弹出二维码登录窗口，监听扫码状态 }

每种验证类型对应一个openWindowCommon弹窗，窗口内通过daemon.newRequest(...)创建验证请求，再把请求渲染成二维码，等待 App 回传结果。整条链路：mirai 报验证 → Solver 弹窗 → 生成二维码 → App 扫码 → 服务器回传结果 → 登录继续。

四、一键读懂配置文件：所有开关都是 JVM 参数

这个项目没有传统意义的配置文件，所有行为都由JVM 启动参数控制，集中读取逻辑在slovbroadcast/DefaultSettings.kt：

internal val noTunnel: Boolean by lazy { sysProp("mlss.no-tunnel", false) } internal val serverPort: Int by lazy { sysProp("mlss.port", 0) } internal val tunnelLimited: Boolean by lazy { sysProp("mlss.tunnel.limited", true) }

DefaultSettings就像"配置中心"，它从System.getProperty里取值，SakuraTransmitDaemon在启动时引用这些值。完整的参数表如下，改动后重启插件即生效：

端口有个贴心设计：mlss.port设为0（默认）时，程序会先尝试绑定 22333 端口，被占用才改用随机端口。这样云服务器只要放行一次 22333 就行，避免每次随机端口都要改防火墙——源码里bootServer()那段ServerSocket().use { socket -> socket.bind(...) }就是干这件事的。

此外版本信息藏在两处：根目录gradle.properties里proj.projver=0.0.12是核心模块版本号，extres/.../metadata.properties是构建期元数据。改版本号时这两个地方要一起留意。

五、常见坑点提醒

围绕这个项目，读者最常踩的三个坑，提前给你排雷：

1. 扫码后崩溃：大概率是 Android WebView 版本过旧，去系统里更新 WebView 即可。
2. 服务器报 "No any server availalbe"：云服务器多半是防火墙没放行 22333 端口；局域网环境则检查路由器的 AP 隔离，可以先在本机 ping 自己的 IP 刷新路由表。
3. 手机和电脑不在同一内网：二维码里的server字段是内网 IP 列表，App 扫码后靠内网直连回传结果，所以手机必须与桌面端连同一个网络。

六、下一步建议

想深入源码的读者，建议按这条线阅读：先读console/ConsolePluginMain.kt搞清启动流程 → 再读resolver/SakuraLoginSolver.kt看各验证类型怎么弹窗 → 最后啃slovbroadcast/SakuraTransmitDaemon.kt理解二维码里的 JSON 协议与隧道机制。想对接自己的客户端，README"数据交换"一节就是你的接口文档。克隆仓库后直接跑核心模块的 Gradle 任务，配合-Dmirai.no-desktop=true在无桌面环境也能快速验证效果。

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