lth/1818web-hoduan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e3e6f1f29d8fd3c86add671ab6197ec650d594df
1818web-hoduan/docs/real-identity-verification-deployment.md
Claude Workbench 0f7bc05697 [Claude Workbench] Initial commit - preserving existing code
2025-11-14 17:41:15 +08:00

4.9 KiB
Raw Blame History

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

概述

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

前置条件

1. 阿里云账号配置

1.1 开通CloudAuth服务

  1. 登录阿里云控制台
  2. 开通"实人认证"服务
  3. 确认计费方式和额度

1.2 创建AccessKey

  1. 进入 RAM 控制台
  2. 创建专用的RAM用户
  3. 生成AccessKey ID和Secret
  4. 分配CloudAuth相关权限

2. 必需权限

确保AccessKey具有以下权限之一：

  • AliyunCloudAuthFullAccess (完整权限)
  • 或自定义权限策略，包含： 
    {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudauth:VerifyMaterial"
      ],
      "Resource": "*"
    }
  ]
}

配置步骤

1. 环境变量配置（推荐）

创建 .env 文件或设置系统环境变量：

# 阿里云身份认证服务配置
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 已配置支持环境变量：

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测试

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. 预期响应

成功响应：

{
  "code": 200,
  "message": "实名认证成功",
  "data": {
    "passed": true,
    "resultStatus": "VERIFY_SUCCESS",
    "bizId": "SUCCESS_1234567890",
    "verifyTime": "2024-09-01 15:30:45"
  }
}

失败响应：

{
  "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）