🌏 cloak接入

一、认证方式

多数需要鉴权的接口采用 userId + apiKey 校验，由 CloakService.validateUserAndApiKey(userId, apiKey) 或 UserService.findByUserIdAndApiKey(userId, apiKey) 完成。

API Key 获取途径：

注册接口返回
登录接口返回
通过 GET /api/cloak/api-key/{userId}?apiKey=xxx 查询（需已知当前 apiKey）

二、验证相关接口

1. Cloak 访问验证（userId + apiKey）

接口： POST /api/cloak/validate-client-ip

请求体：

{
  "userId": 1,
  "apiKey": "your-api-key",
  "clientIP": "1.2.3.4",
  "userAgent": "Mozilla/5.0...",
  "language": "zh-CN",
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "spring",
  "requestUrl": "https://xxx.com/page",
  "referer": "https://google.com"
}

说明： 使用该 userId 对应的 Cloak 配置，根据 IP、语言、UTM 等规则判断是否允许访问。

2. Session 登录验证（userId + apiKey）

接口： POST /api/auth/login-with-apikey

请求体：

{
  "userId": 1,
  "apiKey": "your-api-key"
}

说明： 校验通过后写入 session，后续可调用 GET /api/auth/current-user 获取当前用户。

三、配置获取与修改

1. 获取 Cloak 配置（无需 apiKey）

方法	路径	说明
GET	`/api/cloak/config/{userId}`	获取用户 Cloak 配置

若用户无配置则自动创建默认配置。

2. 更新 Cloak 配置（无需 apiKey）

方法	路径	说明
POST	`/api/cloak/config/{userId}`	更新 Cloak 配置

请求体参数（CloakConfigRequest）：

参数	类型	必填	说明
language	string	否	允许的语言，如 zh-CN、en-US
utmSource	string	否	UTM 来源
utmMedium	string	否	UTM 媒介
utmCampaign	string	否	UTM 活动
whiteCountries	array	否	白名单国家代码，如 ["US","GB"]，映射到 allowedCountries
blackCountries	array	否	黑名单国家代码，如 ["CN","RU"]，映射到 blockedCountries
allowMobile	boolean	否	是否允许移动端
allowDesktop	boolean	否	是否允许桌面端
forceValidation	boolean	否	强制校验模式
normalValidation	boolean	否	普通校验模式
enableWhitelist	boolean	否	是否启用白名单（true=白名单，false=黑名单）
redirectUrl	string	否	拒绝跳转 URL，格式为 xxx.myshoplaza.com（存于 store_proxy_configs）
validationRules	string	否	校验规则，JSON 字符串
customHeaders	string	否	自定义请求头
enableProxy	boolean	否	是否启用代理检测
proxyRules	string	否	代理规则，JSON 字符串
enableIpInfo	boolean	否	是否启用 IPinfo 代理检测

请求示例：

{
  "language": "zh-CN,en-US",
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "spring",
  "whiteCountries": ["US", "GB", "CA"],
  "blackCountries": ["CN", "RU"],
  "allowMobile": true,
  "allowDesktop": true,
  "forceValidation": false,
  "normalValidation": true,
  "enableWhitelist": false,
  "redirectUrl": "puhuo001.myshoplaza.com",
  "enableProxy": true,
  "enableIpInfo": true
}

四、日志与统计

方法	路径	认证	说明
GET	`/api/cloak/logs/{userId}`	无	访问日志，支持分页与筛选
GET	`/api/cloak/stats/{userId}`	apiKey 查询参数	访问统计数据
GET	`/api/cloak/analysis/{userId}`	无	流量分析（支持 startDate/endDate）
GET	`/api/cloak/utm-details/{userId}`	无	UTM 详细日志

示例：

GET /api/cloak/stats/1?apiKey=key_xxx
GET /api/cloak/analysis/1?startDate=2025-03-01&endDate=2025-03-02

五、API Key 管理

方法	路径	说明
GET	`/api/cloak/api-key/{userId}?apiKey=xxx`	获取当前 apiKey
POST	`/api/cloak/api-key/{userId}/regenerate?apiKey=xxx`	重新生成 apiKey

需使用当前有效 apiKey 作为查询参数完成校验。

六、错误响应

HTTP	说明
400	参数错误或格式不正确
401	未登录或 userId/apiKey 校验失败
404	用户不存在

搜索结果