yatori-go-console登录验证码自动识别原理:图形验证码OCR+短信弹窗输入是怎么实现的
yatori-go-console登录验证码自动识别原理:图形验证码OCR+短信弹窗输入是怎么实现的
用 yatori-go-console 课程助手登录学习通时,风控随时可能弹出图形或短信验证码。本文完整拆解它的验证码自动识别实现:本地 OCR 如何自动识别图形验证码、短信验证码又如何通过"挂起—轮询—弹窗提交"机制完成人工输入,一次讲透这套设计。
一、为什么课程助手需要验证码识别
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)。同一个验证码流程,两种使用形态下呈现完全不同的交互方式,这就是"无终端交互验证码"的设计含义。
五、使用中的常见问题
- "等待验证码超时,请重试":
Wait默认 3 分钟超时未收到输入会返回该错误(utils/logincode/logincode.go),重新发起登录即可。 - 看到 OCR 相关报错:
callWithOCRRecover已自动识别并触发重试,正常情况下不需要任何手动操作,相关行为有 logic/runner/ocr_test.go 测试保障。 - 多账号同时登录触发验证码:每个账号按
平台:账号独立挂起,各自的弹窗互不串扰。 - 停止任务后弹窗还在:停止时会调用
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 |
