From 3038cd038729579332792a47b035bb1930e0216b Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 26 Aug 2026 17:51:35 +0800
Subject: [PATCH] =?UTF-8?q?fix(security):=20CORS=20=E6=8B=86=E5=88=86?=
 =?UTF-8?q?=E4=B8=BA=20SDK=20=E5=BC=80=E6=94=BE=E4=B8=8E=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=E7=99=BD=E5=90=8D=E5=8D=95=E5=8F=8C=E8=BD=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修复 9338fcb 收紧 CORS 白名单后引发的线上 403 回归：
将 corsConfigurationSource 与 addCorsMappings 拆分为两套配置——SDK 第三方接入接口
（/ai/**、/category/tree、/category/list、/feedback、/attachment/upload）开放 allowedOriginPatterns("*")，
管理后台接口保持 allowed-origins 白名单防 CSRF；并在 application-prod.yml 白名单补上线上域名
https://aidoc.dgscdw.com:11300，同时记录 CORS 双轨制踩坑规范。
---
 CLAUDE.md                                     | 15 ++++++++++
 .../com/wok/supportbot/config/CorsConfig.java | 14 +++++++--
 .../supportbot/security/SecurityConfig.java   | 30 ++++++++++++++-----
 src/main/resources/application-prod.yml       |  2 +-
 4 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 68ad9c4..5e961eb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -201,6 +201,21 @@ catch (e) { toast('操作失败', 'error') }
 
 **反面案例**: commit `527d9e7` 创建的流程图展示了 RAG 子图中 `VECTOR → RRF | KEYWORD → RRF | HYBRID → RRF → Reranker` 的三模式检索流程，但实际 `RagPipeline.similaritySearch()` 仅做纯向量检索，`HybridSearchService`/`RrfFusion`/`RerankerService` 尚未接入主对话流程，导致图表与代码事实不符。
 
+### 后端：CORS 双轨制（SDK 接口开放 / 管理接口白名单）
+
+**规则**: CORS 配置分两套，**不可整体收紧为单一白名单**（系统可用性第一）：
+
+| 路径 | CORS 策略 | 原因 |
+|------|----------|------|
+| SDK 第三方接入接口：`/ai/**`、`/category/tree`、`/category/list`、`/feedback`、`/attachment/upload` | `allowedOriginPatterns("*")` 开放跨域 | 第三方域名动态未知，用 Bearer Token 鉴权，不依赖来源白名单 |
+| 管理后台接口：其余 `/**` | `allowed-origins` 白名单 | 用 httpOnly refresh cookie，需白名单防跨域 CSRF |
+
+配置有两处，**必须同步修改**：`SecurityConfig.corsConfigurationSource()`（Security 链 CorsFilter）与 `CorsConfig.addCorsMappings()`（Spring MVC 层 CorsInterceptor）。两者均按注册顺序匹配，**先注册精确的 SDK 路径，再注册兜底的 `/**`**。
+
+**反面案例**: commit `9338fcb` 为配合 refresh token 迁移 httpOnly Cookie，把 CORS 从 `allowedOriginPatterns("*")` 整体收紧为白名单，引发两个回归：(1) 同源静态资源 `<script crossorigin>`/`<link crossorigin>` 带 `Origin` 头、白名单缺线上域名 → 首页空白 + assets 403；(2) SDK 第三方跨域、第三方域名不在白名单 → 接口 403。教训：改 CORS 必须同时考虑「同源静态资源的 crossorigin 属性」和「SDK 第三方跨域」两个场景。
+
+**部署提醒**: 更换前端域名/端口时，必须同步把新域名加入 `application-prod.yml` 的 `app.cors.allowed-origins`，否则同源静态资源会 403。
+
 ## API 路由约定
 
 - AI 对话: `/ai/*`（`AiController`）
diff --git a/src/main/java/com/wok/supportbot/config/CorsConfig.java b/src/main/java/com/wok/supportbot/config/CorsConfig.java
index 250a57e..527ae4e 100644
--- a/src/main/java/com/wok/supportbot/config/CorsConfig.java
+++ b/src/main/java/com/wok/supportbot/config/CorsConfig.java
@@ -27,11 +27,19 @@ public class CorsConfig implements WebMvcConfigurer {
 
     @Override
     public void addCorsMappings(CorsRegistry registry) {
-        // 覆盖所有请求
+        // SDK 第三方接入接口：开放跨域（第三方域名动态未知，使用 Bearer Token 鉴权，无 refresh cookie 暴露风险）
+        for (String path : new String[]{"/ai/**", "/category/tree", "/category/list", "/feedback", "/attachment/upload"}) {
+            registry.addMapping(path)
+                    .allowCredentials(true)
+                    .allowedOriginPatterns("*")
+                    .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
+                    .allowedHeaders("*")
+                    .exposedHeaders("*");
+        }
+
+        // 管理后台接口：来源白名单（保护 httpOnly refresh cookie，防跨域 CSRF）
         registry.addMapping("/**")
-                // 允许发送 Cookie（refresh token 需要）
                 .allowCredentials(true)
-                // 放行白名单域名，禁止 * + allowCredentials 组合
                 .allowedOriginPatterns(allowedOrigins.toArray(new String[0]))
                 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                 .allowedHeaders("*")
diff --git a/src/main/java/com/wok/supportbot/security/SecurityConfig.java b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
index eb018cb..27d12db 100644
--- a/src/main/java/com/wok/supportbot/security/SecurityConfig.java
+++ b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
@@ -128,14 +128,30 @@ public class SecurityConfig {
      */
     @Bean
     public CorsConfigurationSource corsConfigurationSource() {
-        CorsConfiguration config = new CorsConfiguration();
-        config.setAllowedOriginPatterns(allowedOrigins);
-        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
-        config.setAllowedHeaders(List.of("*"));
-        config.setExposedHeaders(List.of("*"));
-        config.setAllowCredentials(true);
+        // SDK 第三方接入接口：开放跨域（第三方域名动态未知，使用 Bearer Token 鉴权，无 refresh cookie 暴露风险）
+        CorsConfiguration sdkConfig = new CorsConfiguration();
+        sdkConfig.setAllowedOriginPatterns(List.of("*"));
+        sdkConfig.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+        sdkConfig.setAllowedHeaders(List.of("*"));
+        sdkConfig.setExposedHeaders(List.of("*"));
+        sdkConfig.setAllowCredentials(true);
+
+        // 管理后台接口：来源白名单（保护 httpOnly refresh cookie，防跨域 CSRF）
+        CorsConfiguration adminConfig = new CorsConfiguration();
+        adminConfig.setAllowedOriginPatterns(allowedOrigins);
+        adminConfig.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+        adminConfig.setAllowedHeaders(List.of("*"));
+        adminConfig.setExposedHeaders(List.of("*"));
+        adminConfig.setAllowCredentials(true);
+
         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
-        source.registerCorsConfiguration("/**", config);
+        // 先注册精确的 SDK 路径，再注册兜底的 /**，保证 SDK 接口优先命中开放配置
+        source.registerCorsConfiguration("/ai/**", sdkConfig);
+        source.registerCorsConfiguration("/category/tree", sdkConfig);
+        source.registerCorsConfiguration("/category/list", sdkConfig);
+        source.registerCorsConfiguration("/feedback", sdkConfig);
+        source.registerCorsConfiguration("/attachment/upload", sdkConfig);
+        source.registerCorsConfiguration("/**", adminConfig);
         return source;
     }
 }
diff --git a/src/main/resources/application-prod.yml b/src/main/resources/application-prod.yml
index 7ae1ea5..310f80d 100644
--- a/src/main/resources/application-prod.yml
+++ b/src/main/resources/application-prod.yml
@@ -36,7 +36,7 @@ jwt:
 # ==================== CORS 白名单（生产替换为真实域名） ====================
 app:
   cors:
-    allowed-origins: https://docfilepath.dgscdw.com:8804
+    allowed-origins: https://docfilepath.dgscdw.com:8804,https://aidoc.dgscdw.com:11300
 
 # ==================== 文件存储路径 ====================
 knowledge: