签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/core/captcha.md

@@ -0,0 +1,69 @@
+# 5.3 验证码机制
+
+:::tip 概述
+图形验证码由 utility/captcha 生成：6 位字符（排除易混淆字符）、PNG 渲染（TTF 字体 + 干扰线/噪点）、Redis 缓存 300 秒、一次性校验。字体缺失自动降级 SVG 渲染。
+:::
+
+## 生成流程（GET /api/captcha）
+
+```text
+1) 生成随机码：captcha.length 位（默认 6，范围 4~8），
+   字符集 captcha.chars（默认排除 0O、1lI 等易混淆字符）
+2) 生成 uuid 作为缓存键
+3) 缓存：easygoadmin:captcha:{uuid} = 验证码值，TTL captcha.expire（300s）
+4) 渲染 PNG：TTF 字体（resource/static/fonts/Vera.ttf）+ 干扰线（默认 8 条）
+   + 噪点（默认 500 个）；字体缺失降级 SVG
+5) 返回 {"key": uuid, "captcha": "data:image/png;base64,..."}（前端直接展示）
+```
+
+## 校验流程（captcha.Verify）
+
+```text
+Verify(ctx, key, code)：
+  1) GET easygoadmin:captcha:{uuid}（命中即删除——一次性校验）
+  2) 未命中 → 校验失败（过期或已用过）
+  3) 命中 → 与提交值比对（大小写不敏感处理）
+  4) 配置 captcha.bypassCode 且提交值相等 → 免校验直接通过
+     （仅开发调试使用，生产环境必须留空）
+```
+
+## 配置项（manifest/config/config.yaml）
+
+```yaml
+captcha:
+  expire: 300                 # 有效期（秒）
+  bypassCode: "618618"        # 万能验证码：携带该值免校验，仅开发调试使用，生产留空
+  length: 6                   # 字符数，取值范围 4 到 8
+  chars: "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"  # 字符集，已排除易混淆字符
+  fontPath: "resource/static/fonts/Vera.ttf" # TTF 字体路径，缺失降级 SVG
+  imageWidth: 160             # 图片宽度（字符放不下时自动加宽防裁剪）
+  imageHeight: 50             # 图片高度
+  fontSize: 40                # 字体大小
+  noiseLines: 8               # 干扰线数量（越多越难识别）
+  noiseDots: 500              # 噪点数量
+```
+
+## 使用场景
+
+| 场景 | 行为 |
+|------|------|
+| 登录 | 提供 key 时**强制**校验（auth Login 第 1 步） |
+| 令牌兑换 | 认证入口，与登录同享 authLimit 严阈值 |
+| 开发调试 | code 填 bypassCode（默认 618618）免校验 |
+| 生产 | bypassCode 必须留空（发布检查清单项） |
+
+## 安全要点
+
++ **一次性**：命中即删，防重放（同一验证码不能二次使用）
++ **短 TTL**：300 秒过期，防拖库后长期有效
++ **独立限流**：/api/captcha 属认证入口，受 authLimit=10/分钟/IP 约束（防刷图）
++ **缓存层**：经 utility/cache（Redis 优先、内存降级）——内存降级时验证码单实例内有效
+
+## 常见问题
+
+| 症状 | 原因与处理 |
+|------|-----------|
+| 验证码图片不显示 | 后端未启动 / /api/captcha 被限流；字体缺失不影响（降级 SVG） |
+| 填对了也报验证码错误 | 已用过（一次性）或超 300s；重新获取 |
+| 前端一直验证码错误但后端日志正常 | 检查 key 是否与图片配套（每次生成 key 不同） |
+| 生产环境想跳过验证码 | 禁止配置 bypassCode；调试可在测试环境进行 |