[Claude Workbench] Initial commit - preserving existing code
This commit is contained in:
Claude Workbench
220
docs/real-identity-verification-deployment.md
Normal file
220
docs/real-identity-verification-deployment.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 真实身份认证服务部署指南
|
||||
|
||||
## 概述
|
||||
|
||||
本文档说明如何配置和部署真实的阿里云身份认证服务，实现生产环境的身份证二要素验证功能。
|
||||
|
||||
## 前置条件
|
||||
|
||||
### 1. 阿里云账号配置
|
||||
|
||||
#### 1.1 开通CloudAuth服务
|
||||
1. 登录阿里云控制台
|
||||
2. 开通"实人认证"服务
|
||||
3. 确认计费方式和额度
|
||||
|
||||
#### 1.2 创建AccessKey
|
||||
1. 进入 RAM 控制台
|
||||
2. 创建专用的RAM用户
|
||||
3. 生成AccessKey ID和Secret
|
||||
4. 分配CloudAuth相关权限
|
||||
|
||||
### 2. 必需权限
|
||||
|
||||
确保AccessKey具有以下权限之一：
|
||||
- `AliyunCloudAuthFullAccess` (完整权限)
|
||||
- 或自定义权限策略，包含：
|
||||
```json
|
||||
{
|
||||
"Version": "1",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"cloudauth:VerifyMaterial"
|
||||
],
|
||||
"Resource": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 环境变量配置（推荐）
|
||||
|
||||
创建 `.env` 文件或设置系统环境变量：
|
||||
|
||||
```bash
|
||||
# 阿里云身份认证服务配置
|
||||
export ALIBABA_CLOUD_ACCESS_KEY_ID=your_real_access_key_id
|
||||
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_real_access_key_secret
|
||||
export ALIBABA_CLOUD_REGION=ap-southeast-1
|
||||
```
|
||||
|
||||
### 2. 应用配置文件
|
||||
|
||||
`application.yml` 已配置支持环境变量：
|
||||
|
||||
```yaml
|
||||
aliyun:
|
||||
cloudauth:
|
||||
region: ${ALIBABA_CLOUD_REGION:ap-southeast-1}
|
||||
endpoint: cloudauth.aliyuncs.com
|
||||
access-key-id: ${ALIBABA_CLOUD_ACCESS_KEY_ID:}
|
||||
access-key-secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET:}
|
||||
connection-timeout: 10000
|
||||
response-timeout: 10000
|
||||
biz-type: ID_2META
|
||||
```
|
||||
|
||||
### 3. 验证配置
|
||||
|
||||
启动应用后，通过日志确认配置是否正确：
|
||||
|
||||
```
|
||||
✅ 【真实验证模式】执行阿里云身份认证验证
|
||||
开始调用阿里云CloudAuth身份认证API
|
||||
调用阿里云API - BizType: ID_2META, BizId: identity_verify_xxx
|
||||
阿里云API响应 - RequestId: xxx, VerifyStatus: PASS
|
||||
✅ 阿里云身份认证成功 - 姓名和身份证号码匹配
|
||||
```
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 1. API测试
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8081/user/identity/verify \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your_jwt_token" \
|
||||
-d '{
|
||||
"realName": "张三",
|
||||
"idNumber": "110101199003077777"
|
||||
}'
|
||||
```
|
||||
|
||||
### 2. 预期响应
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "实名认证成功",
|
||||
"data": {
|
||||
"passed": true,
|
||||
"resultStatus": "VERIFY_SUCCESS",
|
||||
"bizId": "SUCCESS_1234567890",
|
||||
"verifyTime": "2024-09-01 15:30:45"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应：**
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "身份证号码与姓名不匹配",
|
||||
"data": {
|
||||
"passed": false,
|
||||
"resultStatus": "FAIL_1234567890",
|
||||
"resultMessage": "身份证号码与姓名不匹配"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误排查
|
||||
|
||||
### 1. 常见错误及解决方案
|
||||
|
||||
#### AccessKeyId无效
|
||||
```
|
||||
错误：AccessKeyId无效，请检查阿里云访问凭证配置
|
||||
```
|
||||
**解决方案：**
|
||||
- 检查AccessKey ID是否正确
|
||||
- 确认AccessKey未被删除或禁用
|
||||
|
||||
#### 权限不足
|
||||
```
|
||||
错误：RAM权限不足，请确保AccessKey具有CloudAuth服务权限
|
||||
```
|
||||
**解决方案：**
|
||||
- 为RAM用户添加CloudAuth相关权限
|
||||
- 检查权限策略是否正确
|
||||
|
||||
#### 网络连接失败
|
||||
```
|
||||
调用阿里云身份认证API失败: Connect to cloudauth.aliyuncs.com:443 timed out
|
||||
```
|
||||
**解决方案：**
|
||||
- 检查服务器网络连接
|
||||
- 确认防火墙设置
|
||||
- 验证DNS解析
|
||||
|
||||
### 2. 日志监控
|
||||
|
||||
关键日志位置：
|
||||
- 认证开始：`【真实验证模式】执行阿里云身份认证验证`
|
||||
- API调用：`开始调用阿里云CloudAuth身份认证API`
|
||||
- API响应：`阿里云API响应 - RequestId: xxx`
|
||||
- 认证结果：`阿里云身份认证成功/失败`
|
||||
|
||||
## 性能和限制
|
||||
|
||||
### 1. API限制
|
||||
- 单个阿里云账号默认QPS限制：50次/秒
|
||||
- 单次查询响应时间：通常在500ms-2000ms
|
||||
|
||||
### 2. 成本考虑
|
||||
- 按调用次数计费
|
||||
- 建议设置用量监控和预警
|
||||
|
||||
### 3. 优化建议
|
||||
- 实现缓存机制（已验证用户短期内不重复验证）
|
||||
- 添加请求重试机制
|
||||
- 监控API成功率
|
||||
|
||||
## 安全建议
|
||||
|
||||
### 1. 凭证管理
|
||||
- ✅ 使用环境变量而非硬编码
|
||||
- ✅ 定期轮换AccessKey
|
||||
- ✅ 使用RAM用户而非主账号
|
||||
- ✅ 最小权限原则
|
||||
|
||||
### 2. 数据保护
|
||||
- ✅ 身份证号码脱敏存储
|
||||
- ✅ 日志中敏感信息脱敏
|
||||
- ✅ HTTPS传输加密
|
||||
|
||||
### 3. 监控告警
|
||||
- 设置API调用失败率告警
|
||||
- 监控异常认证模式
|
||||
- 记录所有认证操作审计日志
|
||||
|
||||
## 部署检查清单
|
||||
|
||||
### 部署前检查
|
||||
- [ ] 阿里云CloudAuth服务已开通
|
||||
- [ ] AccessKey已创建并具备正确权限
|
||||
- [ ] 环境变量已正确配置
|
||||
- [ ] 网络连通性已验证
|
||||
|
||||
### 部署后验证
|
||||
- [ ] 应用启动日志无错误
|
||||
- [ ] 真实身份数据测试通过
|
||||
- [ ] 错误身份数据正确拒绝
|
||||
- [ ] API响应时间在可接受范围内
|
||||
- [ ] 日志记录完整且敏感信息已脱敏
|
||||
|
||||
### 监控设置
|
||||
- [ ] API调用量监控
|
||||
- [ ] 错误率告警
|
||||
- [ ] 响应时间监控
|
||||
- [ ] 成本监控
|
||||
|
||||
---
|
||||
|
||||
*文档更新时间：2024年9月1日*
|
||||
*适用版本：v1.0+（已集成真实阿里云API）*
|
||||
Reference in New Issue
Block a user