yatori-go-console登录验证码自动识别原理:图形验证码OCR+短信弹窗输入是怎么实现的

原创2026-11-16 21:39:201,398 阅读

yatori-go-console登录验证码自动识别原理:图形验证码OCR+短信弹窗输入是怎么实现的

用 yatori-go-console 课程助手登录学习通时,风控随时可能弹出图形或短信验证码。本文完整拆解它的验证码自动识别实现:本地 OCR 如何自动识别图形验证码、短信验证码又如何通过"挂起—轮询—弹窗提交"机制完成人工输入,一次讲透这套设计。

yatori-go-console课程助手登录验证码自动识别项目插画

一、为什么课程助手需要验证码识别

yatori-go-console 支持学习通、英华、仓辉、CQIE 等十余个平台。以学习通 App 登录模式为例,登录链路在风控触发时会要求短信验证码,部分平台还会抛出图形验证码。

问题在于:刷课任务是后台长时间运行的。如果验证码只能靠终端手动输入,Web 模式下就完全卡死——任务超时失败,前面排好的账号全部白等。因此项目给出了两套互补方案:

  • 图形验证码:本地 OCR 自动识别,用户全程无感(对应 README 中"AI自动识别跳过验证码"特性)
  • 短信验证码:前端弹窗等待人工输入,实现"无人值守 + 关键时刻人工兜底"

二、整体流程一图看懂

登录请求 → 平台触发风控 → core SDK 回调 LoginCodeProvider
 ├─ 图形验证码:onnxruntime 本地 OCR 识别 → 结果直接回传,登录继续
 └─ 短信验证码:logincode.Wait 挂起挑战
        → 前端每 3 秒轮询状态
        → 弹窗展示手机号 + 验证码图片
        → 用户输入并提交
        → logincode.Submit 通过 channel 唤醒等待的登录协程
        → 登录继续,挂起状态自动清理

核心思路一句话:图形验证码交给"机器静默处理",短信验证码交给"人弹窗处理",两者共用同一条回调通道。

三、图形验证码 OCR 是怎么实现的

OCR 引擎内置于 yatori-go-core v3 SDK。从 go.mod 的依赖可以看到,项目间接引入了 ddddocr-go(开源图形验证码识别库 ddddocr 的 Go 实现)和 onnxruntime_go——也就是用本地深度学习模型做推理,验证码图片不会上传到任何第三方服务,识别速度快且离线可用。

这里有一个容易踩的坑:onnxruntime 只能初始化一次,而 core 内部 YatoriCoreInit 与 driverutil.EnsureOCR 各持有一个 sync.Once,第二次初始化会直接 panic。console 对此有专门防护:

  • logic/runner/runner.go 中的 callWithOCRRecover 捕获 panic,识别出 "onnxruntime already been initialized" 后转成可识别的错误 errOCRConflict
  • logic/runner/runner.go 检测到该错误后自动重试登录(此时初始化状态实际已完成,重试即成功)
  • 对应测试见 logic/runner/ocr_test.go,验证了"panic 转错误、其它错误原样放行"的行为

对使用者来说,图形验证码从出现到通过全程自动,屏幕都不用看。

四、短信验证码弹窗输入是怎么实现的

这条链路横跨四层:挂起状态机 → 后端接口 → 前端轮询 → 弹窗 UI。

4.1 挂起挑战:logincode 状态机

核心代码在 utils/logincode/logincode.go,整个包就是一个线程安全的"验证码信箱":

函数 作用
Wait 挂起挑战,等待前端提交 / 上下文取消 / 3 分钟超时,三选一返回
Submit 把用户输入的验证码放进缓冲 channel,唤醒等待中的登录协程
SendSMS 透传 core 的回调,触发平台发送短信
Pending 返回只读快照(提示语、手机号、base64 验证码图片),供前端轮询
Clear 停止任务时清理,避免状态残留

状态以 平台:账号 为 key 隔离(utils/logincode/logincode.go),所以多账号并发登录互不干扰;Wait 内部用 select 同时监听 channel、context 和定时器(utils/logincode/logincode.go),这是典型的 Go channel 协作模式。

4.2 后端三个接口

web/router.go 注册了三个验证码接口,实现见 web/service/UserService.go:

接口 说明
GET /api/v1/accountLoginCode/:uid 查询是否有待输入的验证码
POST /api/v1/accountLoginCode/:uid 提交用户输入的验证码
POST /api/v1/accountLoginCode/:uid/send 触发平台发送短信验证码

4.3 前端 3 秒轮询 + 弹窗输入

frontend/components/account-detail.tsx 在账号详情页打开后就启动 3 秒间隔轮询,一旦发现 pending: true 立即弹出对话框(frontend/components/account-detail.tsx),弹窗内容包含:

  • 验证提示语(prompt)与手机号
  • 图形验证码图片(base64 直接渲染,短信场景下没有图片时自动隐藏)
  • "发送验证码"按钮(仅当 canSendSms 为 true 时显示)
  • 输入框 + "确定"按钮,支持回车直接提交

提交后验证码经 frontend/api/accountApi.ts 打到后端 Submit 接口,等待中的 Wait 立刻拿到码并返回,登录流程无缝继续;下一轮轮询查不到挂起状态,弹窗自动消失。

4.4 登录时如何把两条路接起来

关键接线在 logic/runner/runner.go:构建登录选项时,Web 模式会把 Options.LoginCodeProvider 设为调用 logincode.Wait(超时 3 分钟);CLI 模式则改用 promptLoginCode——把图形验证码图片存到 assets/captcha_*.png 并在终端提示手动输入(logic/runner/runner.go)。同一个验证码流程,两种使用形态下呈现完全不同的交互方式,这就是"无终端交互验证码"的设计含义。

五、使用中的常见问题

  1. "等待验证码超时,请重试":Wait 默认 3 分钟超时未收到输入会返回该错误(utils/logincode/logincode.go),重新发起登录即可。
  2. 看到 OCR 相关报错:callWithOCRRecover 已自动识别并触发重试,正常情况下不需要任何手动操作,相关行为有 logic/runner/ocr_test.go 测试保障。
  3. 多账号同时登录触发验证码:每个账号按 平台:账号 独立挂起,各自的弹窗互不串扰。
  4. 停止任务后弹窗还在:停止时会调用 logincode.Clear 清理挂起状态,若仍有残留可刷新页面重新轮询。

六、小结

yatori-go-console 的验证码处理可以概括为一句话:

  • 图形验证码:本地 ddddocr + onnxruntime 深度学习推理,SDK 内静默完成,OCR 重复初始化 panic 也有自动重试兜底;
  • 短信验证码:core 通过 LoginCodeProvider 回调挂起挑战,后端用 channel 状态机(Wait/Submit/Pending)桥接,前端 3 秒轮询驱动弹窗,用户在弹窗里输入提交后登录立刻恢复。

两套机制分工明确、状态隔离,既保证无人值守能自动跑,又保留了风控关键时刻的人工兜底,是"AI 自动识别 + 弹窗人工协作"的一个完整落地案例。

附:核心文件速查

模块 路径
验证码挂起/提交状态机 utils/logincode/logincode.go
登录接线与 OCR panic 防护 logic/runner/runner.go
OCR 重试行为测试 logic/runner/ocr_test.go
验证码接口路由 web/router.go
验证码接口服务层 web/service/UserService.go
前端轮询与弹窗 UI frontend/components/account-detail.tsx
前端验证码 API 封装 frontend/api/accountApi.ts
登录后查看全文
yatori-go-console