221 lines
4.9 KiB
Markdown
221 lines
4.9 KiB
Markdown
# 真实身份认证服务部署指南
|
||
|
||
## 概述
|
||
|
||
本文档说明如何配置和部署真实的阿里云身份认证服务，实现生产环境的身份证二要素验证功能。
|
||
|
||
## 前置条件
|
||
|
||
### 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）*
|