457 lines
14 KiB
Markdown
457 lines
14 KiB
Markdown
## 阿里云滑块验证码接入说明（含加密模式）
|
||
|
||
|
||
- 前端需要做什么
|
||
- 后端需要做什么
|
||
- 非加密模式 vs 加密模式（`EncryptedSceneId`）
|
||
- 本项目修改了哪些文件，可以作为参考实现
|
||
|
||
下面所有内容以当前项目（`tyc-webview-v2` + `tyc-server-v2`）为例，按步骤说明。
|
||
|
||
---
|
||
|
||
配置项
|
||
|
||
go get github.com/alibabacloud-go/captcha-20230305/client
|
||
|
||
Captcha:
|
||
# 建议与短信相同的 AccessKey，或单独为验证码创建子账号
|
||
AccessKeyID: "LTAI5tKGB3TVJbMHSoZN3yr9"
|
||
AccessKeySecret: "OCQ30GWp4yENMjmfOAaagksE18bp65"
|
||
# 验证码服务 Endpoint，国内一般为 captcha.cn-shanghai.aliyuncs.com
|
||
EndpointURL: "captcha.cn-shanghai.aliyuncs.com"
|
||
# 阿里云控制台中该场景的 SceneId，请替换为真实值
|
||
SceneID: "wynt39to"
|
||
# 验证码控制台中的 ekey（通常为 Base64 字符串），用于生成 EncryptedSceneId
|
||
EKey: ""
|
||
|
||
index.html
|
||
<!-- 阿里云滑块验证码 -->
|
||
<script>
|
||
window.AliyunCaptchaConfig = { region: "cn", prefix: "12zxnj" };
|
||
</script>
|
||
## 一、整体流程概览
|
||
|
||
### 1.1 场景说明
|
||
|
||
我们使用的是 **阿里云验证码 2.0 / V3 架构** 的滑块验证码，前后端配合流程如下：
|
||
|
||
1. 前端在「获取短信验证码」/「查询前无短信码的产品」时，先弹出阿里云滑块验证码。
|
||
2. 用户拖动成功后，前端拿到 `captchaVerifyParam`，携带到后端业务接口。
|
||
3. 后端使用阿里云官方 Go SDK（`captcha-20230305`）+ 我们的封装，对 `captchaVerifyParam` 做服务端校验：
|
||
- 校验通过：继续后续业务逻辑（发短信、查询等）。
|
||
- 校验失败：直接返回业务错误，例如「图形验证码校验失败」。
|
||
4. 对于 **加密模式** 场景，前端还需要在初始化时传入 `EncryptedSceneId`，而 `EncryptedSceneId` 由后端用控制台的 `ekey` 生成。
|
||
|
||
### 1.2 使用场景（当前项目）
|
||
|
||
- 登录页：
|
||
- **获取短信验证码**：必须先通过滑块验证。
|
||
- **提交登录**：只校验短信验证码，不再做滑块。
|
||
- Inquire 查询页：
|
||
- 有「短信验证码」字段的产品：点击「获取验证码」前滑块；点击「查询」时不需要再次滑块。
|
||
- 无「短信验证码」的产品：点击「查询」前滑块。
|
||
|
||
---
|
||
|
||
## 二、前端接入说明（以 Vue 3 / Vite 为例）
|
||
|
||
### 2.1 全局基础集成（`index.html`）
|
||
|
||
在入口 HTML 中引入阿里云验证码脚本，并预留一个容器：
|
||
|
||
- 文件：`tyc-webview-v2/index.html`
|
||
|
||
关键片段：
|
||
|
||
```html
|
||
<script>
|
||
window.AliyunCaptchaConfig = { region: "cn", prefix: "你的前缀" };
|
||
</script>
|
||
<script
|
||
type="text/javascript"
|
||
src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
|
||
></script>
|
||
...
|
||
<body>
|
||
<div id="app"></div>
|
||
<div id="captcha-element"></div>
|
||
</body>
|
||
```
|
||
|
||
注意：
|
||
|
||
- `#captcha-element` 是验证码挂载容器，必须存在。
|
||
- `AliyunCaptcha.js` 必须在前端业务代码（`/src/main.js`）之前加载。
|
||
|
||
### 2.2 通用封装：`useAliyunCaptcha`
|
||
|
||
- 文件：`tyc-webview-v2/src/composables/useAliyunCaptcha.js`
|
||
|
||
该 composable 封装了：
|
||
|
||
- **初始化阿里云验证码实例**（含加密 / 非加密模式）；
|
||
- 提供一个通用方法 `runWithCaptcha(bizVerify, onSuccess)`：
|
||
- `bizVerify(captchaVerifyParam)`：前端回调，内部调用后端业务接口（发短信、查询等），返回 `{ data, error }`（`useApiFetch` 结果）。
|
||
- `onSuccess(res)`：当业务 `code === 200` 时调用，`res` 为后端返回的数据。
|
||
|
||
使用方式示例：
|
||
|
||
```js
|
||
import { useAliyunCaptcha } from "@/composables/useAliyunCaptcha";
|
||
|
||
const { runWithCaptcha } = useAliyunCaptcha();
|
||
|
||
function sendLoginSms() {
|
||
if (!isPhoneValid.value) return;
|
||
|
||
runWithCaptcha(
|
||
(captchaVerifyParam) =>
|
||
useApiFetch("auth/sendSms")
|
||
.post({
|
||
mobile: phoneNumber.value,
|
||
actionType: "login",
|
||
captchaVerifyParam,
|
||
})
|
||
.json(),
|
||
(res) => {
|
||
if (res.code === 200) {
|
||
// 成功：toast + 开始倒计时 + 聚焦输入框
|
||
} else {
|
||
// 失败：toast 提示
|
||
}
|
||
},
|
||
);
|
||
}
|
||
```
|
||
|
||
### 2.3 加密模式开关（前端）
|
||
|
||
在 `useAliyunCaptcha.js` 顶部：
|
||
|
||
```js
|
||
// 是否启用加密模式（通过环境变量控制）
|
||
const ENABLE_ENCRYPTED =
|
||
import.meta.env.VITE_ALIYUN_CAPTCHA_ENCRYPTED === "true";
|
||
```
|
||
|
||
在 `ensureCaptchaInit()` 中：
|
||
|
||
- **非加密模式**（`ENABLE_ENCRYPTED === false`）：
|
||
|
||
```js
|
||
if (!ENABLE_ENCRYPTED) {
|
||
window.initAliyunCaptcha({
|
||
SceneId: ALIYUN_CAPTCHA_SCENE_ID,
|
||
mode: "popup",
|
||
element: "#captcha-element",
|
||
getInstance(instance) { window.captcha = instance; ... },
|
||
captchaVerifyCallback(param) { ... },
|
||
onBizResultCallback(bizResult) { ... },
|
||
slideStyle: { width: 360, height: 40 },
|
||
language: "cn",
|
||
});
|
||
return;
|
||
}
|
||
```
|
||
|
||
前端不会请求后端获取 `EncryptedSceneId`，只用 `SceneId` 初始化。
|
||
|
||
- **加密模式**（`ENABLE_ENCRYPTED === true`）：
|
||
|
||
```js
|
||
const { data, error } = await useApiFetch("/captcha/encryptedSceneId")
|
||
.post()
|
||
.json();
|
||
const resp = data?.value;
|
||
const encryptedSceneId = resp?.data?.encryptedSceneId;
|
||
if (error?.value || !encryptedSceneId) {
|
||
showToast({ message: "获取验证码参数失败，请稍后重试" });
|
||
// 重置状态
|
||
captchaInitialised = false;
|
||
captchaReadyPromise = null;
|
||
captchaReadyResolve = null;
|
||
return;
|
||
}
|
||
|
||
window.initAliyunCaptcha({
|
||
SceneId: ALIYUN_CAPTCHA_SCENE_ID,
|
||
EncryptedSceneId: encryptedSceneId,
|
||
mode: "popup",
|
||
element: "#captcha-element",
|
||
...
|
||
});
|
||
```
|
||
|
||
> 在其它前端平台（React、原生 H5 等），可以复用同样的思路：
|
||
> - 抽一个 `runWithCaptcha` 工具；
|
||
> - 初始化逻辑中根据配置决定是否去后端拿 `EncryptedSceneId`，有则带上。
|
||
|
||
### 2.4 用户体验：加载提示
|
||
|
||
在 `runWithCaptcha` 中增加全局 Loading：
|
||
|
||
```js
|
||
const loading = showLoadingToast({
|
||
message: "安全验证加载中...",
|
||
forbidClick: true,
|
||
duration: 0,
|
||
loadingType: "spinner",
|
||
});
|
||
|
||
try {
|
||
// 设置 __captchaVerifyCallback / __onBizResultCallback
|
||
// await ensureCaptchaInit()
|
||
// await captchaReadyPromise
|
||
// window.captcha.show()
|
||
} finally {
|
||
closeToast();
|
||
}
|
||
```
|
||
|
||
这样用户点击按钮后能看到“安全验证加载中”，避免误以为没反应。
|
||
|
||
---
|
||
|
||
## 三、后端接入说明（Go / go-zero）
|
||
|
||
### 3.1 基本配置（`config.go` + `main.yaml`）
|
||
|
||
- 文件：`app/main/api/internal/config/config.go`
|
||
|
||
```go
|
||
type CaptchaConfig struct {
|
||
AccessKeyID string
|
||
AccessKeySecret string
|
||
EndpointURL string
|
||
SceneID string
|
||
EKey string // 加密模式用的 ekey（Base64）
|
||
}
|
||
```
|
||
|
||
- 文件：`app/main/api/etc/main.yaml` / `main.dev.yaml`
|
||
|
||
```yaml
|
||
Captcha:
|
||
AccessKeyID: "你的AccessKeyId"
|
||
AccessKeySecret: "你的AccessKeySecret"
|
||
EndpointURL: "captcha.cn-shanghai.aliyuncs.com"
|
||
SceneID: "控制台场景ID"
|
||
EKey: "控制台上看到的 ekey（Base64 字符串）"
|
||
```
|
||
|
||
> 其它平台（Java/Spring、.NET 等）也需要同样的配置：
|
||
> - 一个 Captcha 配置块，包含 AK/SK、Endpoint、SceneId、EKey。
|
||
|
||
### 3.2 EncryptedSceneId 生成接口（加密模式）
|
||
|
||
#### 3.2.1 生成函数
|
||
|
||
- 文件：`pkg/captcha/encrypt_scene.go`
|
||
|
||
```go
|
||
package captcha
|
||
|
||
import (
|
||
"encoding/base64"
|
||
"fmt"
|
||
"time"
|
||
|
||
lzcrypto "tyc-server/pkg/lzkit/crypto"
|
||
)
|
||
|
||
// GenerateEncryptedSceneID: sceneId×tamp&expireTime -> AES-256-CBC + PKCS7 -> Base64(IV + ciphertext)
|
||
func GenerateEncryptedSceneID(sceneId, ekey string, expireSeconds int) (string, error) {
|
||
if expireSeconds <= 0 || expireSeconds > 86400 {
|
||
expireSeconds = 3600
|
||
}
|
||
|
||
ts := time.Now().Unix()
|
||
plaintext := fmt.Sprintf("%s&%d&%d", sceneId, ts, expireSeconds)
|
||
|
||
keyBytes, err := base64.StdEncoding.DecodeString(ekey)
|
||
if err != nil {
|
||
return "", fmt.Errorf("decode ekey error: %w", err)
|
||
}
|
||
if len(keyBytes) != 32 {
|
||
return "", fmt.Errorf("invalid ekey length, need 32 bytes after base64 decode, got %d", len(keyBytes))
|
||
}
|
||
|
||
return lzcrypto.AesEncrypt([]byte(plaintext), keyBytes)
|
||
}
|
||
```
|
||
|
||
> 在其它语言上，只要完全按文档实现同样的算法即可。
|
||
|
||
#### 3.2.2 API 声明
|
||
|
||
- 文件：`app/main/api/desc/front/user.api`
|
||
|
||
```go
|
||
@server (
|
||
prefix: api/v1
|
||
group: captcha
|
||
)
|
||
service main {
|
||
@doc "get encrypted scene id for aliyun captcha"
|
||
@handler getEncryptedSceneId
|
||
post /captcha/encryptedSceneId returns (GetEncryptedSceneIdResp)
|
||
}
|
||
|
||
type (
|
||
GetEncryptedSceneIdResp {
|
||
EncryptedSceneId string `json:"encryptedSceneId"`
|
||
}
|
||
)
|
||
```
|
||
|
||
#### 3.2.3 逻辑实现
|
||
|
||
- 文件：`app/main/api/internal/logic/captcha/getencryptedsceneidlogic.go`
|
||
|
||
```go
|
||
func (l *GetEncryptedSceneIdLogic) GetEncryptedSceneId() (*types.GetEncryptedSceneIdResp, error) {
|
||
cfg := l.svcCtx.Config.Captcha
|
||
encrypted, err := captcha.GenerateEncryptedSceneID(cfg.SceneID, cfg.EKey, 3600)
|
||
if err != nil {
|
||
l.Errorf("generate encrypted scene id error: %+v", err)
|
||
return nil, err
|
||
}
|
||
return &types.GetEncryptedSceneIdResp{
|
||
EncryptedSceneId: encrypted,
|
||
}, nil
|
||
}
|
||
```
|
||
|
||
> 其它平台只需要提供一个类似的 HTTP 接口即可：
|
||
> `POST /captcha/encryptedSceneId -> { encryptedSceneId: "xxx" }`
|
||
|
||
### 3.3 验证 `captchaVerifyParam`（服务端验签）
|
||
|
||
- 文件：`pkg/captcha/aliyun.go`
|
||
|
||
使用阿里云官方 Go SDK 验证：
|
||
|
||
```go
|
||
func Verify(cfg Config, captchaVerifyParam string) error {
|
||
if os.Getenv("ENV") == "development" {
|
||
return nil
|
||
}
|
||
if captchaVerifyParam == "" {
|
||
return errors.Wrapf(xerr.NewErrMsg("图形验证码校验失败"), "empty captchaVerifyParam")
|
||
}
|
||
|
||
clientCfg := &openapi.Config{
|
||
AccessKeyId: tea.String(cfg.AccessKeyID),
|
||
AccessKeySecret: tea.String(cfg.AccessKeySecret),
|
||
}
|
||
clientCfg.Endpoint = tea.String(cfg.EndpointURL)
|
||
client, err := captcha20230305.NewClient(clientCfg)
|
||
...
|
||
|
||
req := &captcha20230305.VerifyIntelligentCaptchaRequest{
|
||
SceneId: tea.String(cfg.SceneID),
|
||
CaptchaVerifyParam: tea.String(captchaVerifyParam),
|
||
}
|
||
resp, err := client.VerifyIntelligentCaptcha(req)
|
||
...
|
||
if tea.BoolValue(resp.Body.Result.VerifyResult) {
|
||
return nil
|
||
}
|
||
// 否则返回 "图形验证码校验失败"
|
||
}
|
||
```
|
||
|
||
在需要滑块的业务逻辑里（发送短信、查询），调用：
|
||
|
||
```go
|
||
cfg := l.svcCtx.Config.Captcha
|
||
if err := captcha.Verify(captcha.Config{
|
||
AccessKeyID: cfg.AccessKeyID,
|
||
AccessKeySecret: cfg.AccessKeySecret,
|
||
EndpointURL: cfg.EndpointURL,
|
||
SceneID: cfg.SceneID,
|
||
}, req.CaptchaVerifyParam); err != nil {
|
||
return nil, err
|
||
}
|
||
```
|
||
|
||
> 其它语言平台（Java、Node.js 等）可以用对应的阿里云 SDK 实现相同的服务端校验。
|
||
|
||
### 3.4 sendSms 接口示例
|
||
|
||
- 文件：`app/main/api/internal/logic/auth/sendsmslogic.go`
|
||
|
||
```go
|
||
func (l *SendSmsLogic) SendSms(req *types.SendSmsReq) error {
|
||
// 1. 图形验证码校验
|
||
cfg := l.svcCtx.Config.Captcha
|
||
if err := captcha.Verify(captcha.Config{...}, req.CaptchaVerifyParam); err != nil {
|
||
return err
|
||
}
|
||
|
||
// 2. 原来的手机号加密、频率限制、阿里短信发送、Redis 存验证码等逻辑
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、关键文件清单
|
||
|
||
- 前端：
|
||
- `tyc-webview-v2/index.html`：引入 `AliyunCaptcha.js`、提供 `#captcha-element`。
|
||
- `tyc-webview-v2/src/composables/useAliyunCaptcha.js`：通用封装，支持加密/非加密模式 + Loading 提示。
|
||
- `tyc-webview-v2/src/views/Login.vue`：获取短信前通过 `runWithCaptcha` 调用 `/auth/sendSms`。
|
||
- `tyc-webview-v2/src/components/InquireForm.vue`：查询前根据是否有短信验证码字段决定是否通过 `runWithCaptcha`。
|
||
|
||
- 后端：
|
||
- `app/main/api/internal/config/config.go`：`CaptchaConfig` 增加 `EKey`。
|
||
- `app/main/api/etc/main.yaml` / `main.dev.yaml`：补充 `Captcha` 配置（SceneID + EKey）。
|
||
- `app/main/api/desc/front/user.api`：声明 `/captcha/encryptedSceneId` 接口。
|
||
- `app/main/api/internal/logic/captcha/getencryptedsceneidlogic.go`：生成 `EncryptedSceneId`。
|
||
- `pkg/captcha/encrypt_scene.go`：`GenerateEncryptedSceneID` 实现。
|
||
- `pkg/captcha/aliyun.go`：`Verify` 实现（调用阿里云 SDK）。
|
||
- `app/main/api/internal/logic/auth/sendsmslogic.go`：发送短信前调用 `captcha.Verify`。
|
||
- `app/main/api/internal/logic/query/queryservicelogic.go`：对无短信验证码的产品，在查询前调用 `captcha.Verify`。
|
||
|
||
---
|
||
|
||
## 五、接入其它平台时的注意事项
|
||
|
||
1. **SceneId / ekey 必须一一对应**
|
||
- 控制台“场景管理”里的 SceneId 和 ekey 必须和配置里完全一致。
|
||
- 多个场景要分别管理 SceneId / ekey。
|
||
|
||
2. **时间同步**
|
||
- 加密模式依赖 `timestamp` 和 `expireTime`，服务器时间要尽量准确（建议 NTP 同步）。
|
||
|
||
3. **前后端模式一致**
|
||
- 如果控制台开启了加密模式，前端必须**带上 `EncryptedSceneId`**；
|
||
- 如果前端只传 `SceneId`，在加密模式下会被阿里云直接拒绝（出现类似 F022 错误码）。
|
||
|
||
4. **错误处理**
|
||
- 服务端 `Verify` 出错（网络、阿里云故障）时，我们当前策略是**记录日志但视为通过**，防止影响业务可用性——这一点可根据各平台风险偏好调整。
|
||
|
||
5. **复用策略**
|
||
- 不同前端技术栈（Vue/React/小程序等），只要能做到：
|
||
1. 初始化时根据配置决定是否从后端拿 `EncryptedSceneId`；
|
||
2. 在业务请求前通过验证码拿到 `captchaVerifyParam` 并传给后端；
|
||
- 后端则统一在与风控相关的接口上调用相同的 `Verify` 封装即可。
|
||
|
||
---
|
||
|
||
## 六、推荐的接入步骤
|
||
|
||
1. 在阿里云验证码控制台创建场景，记下 **SceneId** 和 **ekey**，并根据需要打开「加密模式」。
|
||
2. 在你自己的后端项目里：
|
||
- 增加 Captcha 配置块（AccessKeyID、AccessKeySecret、EndpointURL、SceneID、EKey）；
|
||
- 实现 EncryptedSceneId 生成接口 `/captcha/encryptedSceneId`（可参考本项目的 `GenerateEncryptedSceneID`）；
|
||
- 在需要滑块的业务接口（发短信、查询）前调用阿里云 SDK 做 `captchaVerifyParam` 校验。
|
||
3. 在你自己的前端项目里：
|
||
- 页面引入 `AliyunCaptcha.js` 并预留验证码容器；
|
||
- 抽一个类似 `runWithCaptcha(bizVerify, onSuccess)` 的封装；
|
||
- 业务按钮点击时，不直接调接口，而是先触发 `runWithCaptcha`：
|
||
- 前端拉取 `EncryptedSceneId`（若启用加密模式）；
|
||
- 初始化 `initAliyunCaptcha` 并弹出滑块；
|
||
- 滑块通过后才真正调用后端业务接口。
|