# 真实身份认证服务部署指南

## 概述

本文档说明如何配置和部署真实的阿里云身份认证服务，实现生产环境的身份证二要素验证功能。

## 前置条件

### 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）*