[Claude Workbench] Initial commit - preserving existing code

docs/cloudauth-permission-troubleshooting.md

@@ -0,0 +1,167 @@
+# 阿里云CloudAuth权限问题排查指南
+
+## 问题现象
+
+调用阿里云身份认证API时出现权限错误：
+```
+API响应Code: 440
+接口调用失败 - Code: 440, Message: 无权限调用
+```
+
+## 问题原因分析
+
+### 1. 区域配置问题 ✅ 已修复
+**问题**：原配置使用 `ap-southeast-1`，与官方案例不一致
+**修复**：已更改为 `cn-hangzhou`（与官方案例一致）
+
+### 2. 权限配置问题 ⚠️ 需要检查
+可能的权限问题：
+- AccessKey没有CloudAuth服务权限
+- 账号未开通实人认证服务
+- RAM权限策略配置不正确
+
+## 解决方案
+
+### 步骤1：检查服务开通状态
+
+1. **登录阿里云控制台**
+2. **搜索"实人认证"服务**
+3. **确认服务已开通**
+   - 如果未开通，需要先开通服务
+   - 确认计费方式和配额
+
+### 步骤2：检查AccessKey权限
+
+#### 方案A：使用预设权限策略（推荐）
+为RAM用户添加以下权限策略：
+- `AliyunCloudAuthFullAccess` - 实人认证完整权限
+
+#### 方案B：自定义权限策略
+创建自定义策略，包含以下权限：
+```json
+{
+  "Version": "1",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "cloudauth:Id2MetaStandardVerify",
+        "cloudauth:DescribeVerifyResult"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+### 步骤3：验证AccessKey配置
+
+#### 当前配置检查
+```yaml
+aliyun:
+  cloudauth:
+    region: cn-hangzhou  # ✅ 已修复为正确区域
+    endpoint: cloudauth.aliyuncs.com
+    access-key-id: LTAI5t68do3qVXx5Rufugt3X  # 检查是否正确
+    access-key-secret: 2vD9ToIff49Vph4JQXsn0Cy8nXQfzA  # 检查是否正确
+```
+
+#### 安全建议
+```yaml
+# 推荐使用环境变量
+access-key-id: ${ALIBABA_CLOUD_ACCESS_KEY_ID:}
+access-key-secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET:}
+```
+
+### 步骤4：测试权限
+
+#### 方法1：使用阿里云CLI测试
+```bash
+# 安装阿里云CLI
+# 配置凭证
+aliyun configure set --profile default --mode AK --region cn-hangzhou --access-key-id YOUR_KEY --access-key-secret YOUR_SECRET
+
+# 测试权限
+aliyun cloudauth DescribeVerifyResult --region cn-hangzhou
+```
+
+#### 方法2：检查控制台访问
+1. 使用当前AccessKey登录阿里云控制台
+2. 尝试访问"实人认证"服务页面
+3. 确认可以查看服务状态和配置
+
+## 常见错误码说明
+
+| 错误码 | 说明 | 解决方案 |
+|--------|------|----------|
+| 440 | 无权限调用 | 检查RAM权限和服务开通状态 |
+| 400 | 参数错误 | 检查请求参数格式和必需字段 |
+| 403 | 访问被拒绝 | 检查IP白名单和安全组设置 |
+| 500 | 服务器内部错误 | 稍后重试或联系技术支持 |
+
+## RAM权限配置步骤
+
+### 1. 创建RAM用户（如果没有）
+```
+阿里云控制台 → 访问控制(RAM) → 用户 → 创建用户
+✅ 勾选"编程访问"
+✅ 记录AccessKey ID和Secret
+```
+
+### 2. 添加权限策略
+```
+用户管理 → 选择用户 → 权限管理 → 添加权限
+选择权限策略：AliyunCloudAuthFullAccess
+```
+
+### 3. 验证权限
+```
+权限管理 → 查看权限 → 确认包含CloudAuth相关权限
+```
+
+## 网络和安全配置
+
+### 1. IP白名单
+某些企业账号可能需要配置IP白名单：
+```
+阿里云控制台 → 实人认证 → 安全设置 → IP白名单
+添加服务器公网IP
+```
+
+### 2. 防火墙设置
+确保服务器可以访问：
+- `cloudauth.aliyuncs.com:443`
+- 阿里云API网关地址
+
+## 监控和日志
+
+### 增强的错误日志
+修复后的系统会输出详细的诊断信息：
+```
+❌ 权限错误：请检查以下配置：
+   1. AccessKey是否具有CloudAuth服务权限
+   2. 账号是否已开通实人认证服务
+   3. 区域配置是否正确（当前：cn-hangzhou）
+   4. 建议在阿里云控制台检查RAM权限和服务开通状态
+```
+
+### API调用监控
+建议在阿里云控制台监控：
+- API调用次数和成功率
+- 错误分布和原因
+- 费用消耗情况
+
+## 快速验证清单
+
+- [ ] 实人认证服务已开通
+- [ ] AccessKey具有CloudAuth权限
+- [ ] 区域配置为cn-hangzhou
+- [ ] 网络连接正常
+- [ ] IP白名单配置（如需要）
+- [ ] 测试API调用成功
+
+---
+
+*文档更新时间：2024年9月1日*  
+*问题状态：🔧 权限配置修复中*  
+*关键修复：区域配置已从 ap-southeast-1 更改为 cn-hangzhou*