ruoyi-java/doc/WPS365回调地址配置说明.md

WPS365 回调地址配置说明

错误信息

如果遇到以下错误：

{
  "code": 40000001,
  "msg": "invalid_request",
  "debug": {
    "desc": "The 'redirect_uri' parameter does not match any of the OAuth 2.0 Client's pre-registered redirect urls."
  }
}

原因：redirect_uri 参数与WPS365开放平台配置的回调地址不一致。

解决方案

1. 检查当前配置的回调地址

查看 application.yml 中的配置：

wps365:
  redirect-uri: https://jarvis.van333.cn/wps365-callback

2. 在WPS365开放平台配置回调地址

1. 登录WPS365开放平台

   • 访问：https://open.wps.cn/
   • 进入你的应用管理页面

2. 找到"安全设置"或"回调配置"

   • 通常在"开发配置" > "安全设置" 或 "事件与回调" 中

3. 配置授权回调地址

   • 回调地址必须与配置文件中的 redirect-uri 完全一致
   • 包括：
     • ✅ 协议：https://（不能是 http://）
     • ✅ 域名：jarvis.van333.cn（不能有 www 或其他前缀）
     • ✅ 路径：/wps365-callback（不能有多余的斜杠）
     • ✅ 端口：如果使用默认端口443，不需要写端口号

4. 正确的配置示例

   https://jarvis.van333.cn/wps365-callback
   

5. 错误的配置示例（会导致错误）

   ❌ http://jarvis.van333.cn/wps365-callback          (协议错误)
   ❌ https://www.jarvis.van333.cn/wps365-callback      (域名不一致)
   ❌ https://jarvis.van333.cn/wps365-callback/         (末尾多斜杠)
   ❌ https://jarvis.van333.cn:443/wps365-callback      (端口号多余)
   ❌ https://jarvis.van333.cn/jarvis/wps365/oauth/callback  (路径不一致)
   

3. 验证回调地址

配置完成后，WPS365平台会发送一个challenge验证请求到你的回调地址。确保：

• ✅ 回调接口支持GET和POST请求
• ✅ 能正确处理challenge参数并返回
• ✅ 接口可以正常访问（不被防火墙拦截）

4. 常见问题排查

问题1：配置了但验证失败

• 检查回调接口是否支持POST请求
• 检查是否能正确处理challenge参数
• 查看后端日志，确认是否收到challenge请求

问题2：授权时提示redirect_uri不匹配

• 检查WPS365平台配置的回调地址
• 检查配置文件中的redirect-uri
• 确保两者完全一致（包括大小写、斜杠等）

问题3：回调地址访问失败

• 检查nginx配置是否正确代理
• 检查前端白名单是否已配置
• 检查域名DNS解析是否正常

5. 调试步骤

1. 查看后端日志

   生成授权URL: https://openapi.wps.cn/oauth2/auth?client_id=xxx&redirect_uri=...
   使用回调地址: https://jarvis.van333.cn/wps365-callback
   

2. 复制日志中的回调地址

   • 确保WPS365平台配置的地址与日志中的地址完全一致

3. 测试回调地址

   • 直接在浏览器访问：https://jarvis.van333.cn/wps365-callback
   • 应该能看到授权页面或提示信息

4. 重新授权

   • 修改配置后，重新点击"立即授权"
   • 如果还是失败，检查WPS365平台的配置

配置检查清单

• WPS365开放平台已配置回调地址
• 回调地址与配置文件中的redirect-uri完全一致
• 回调接口支持GET和POST请求
• 回调接口能正确处理challenge验证
• 前端白名单已配置 /wps365-callback
• nginx已配置 /wps365-callback 路由
• 域名DNS解析正常
• SSL证书有效

注意事项

1. 回调地址必须使用HTTPS（生产环境）
2. 路径不能有末尾斜杠（除非是根路径）
3. 域名必须完全匹配（不能有www前缀等）
4. 配置后需要等待几分钟生效（WPS365平台可能有缓存）