ln-773-cors-configurator

ln-773-cors-configurator

**类型：**L3 Worker **类别：**7XX 项目引导

以安全为先配置跨域资源共享（CORS）策略。

---

概述

方面	详情
输入	来自 ln-770 的上下文存储
输出	包含环境特定策略的 CORS 配置
技术栈	.NET（ASP.NET Core CORS）、Python（FastAPI CORSMiddleware）

---

阶段 1：接收上下文

接收协调器提供的上下文存储。

必需上下文：

• STACK：.NET 或 Python
• PROJECT_ROOT：项目目录路径
• ENVIRONMENT：Development 或 Production

幂等性检查：

• .NET：搜索 AddCors 或 UseCors
• Python：搜索 CORSMiddleware
• 如果已找到：返回 { "status": "skipped" }

---

阶段 2：分析项目结构

确定前端配置。

检测步骤：

1. 检查同一仓库中是否有前端（/frontend、/client、/web）
2. 从 .env 或 appsettings.json 读取 CORS_ORIGINS
3. 识别常见前端端口（3000、5173、4200）

检测到的前端源：

框架	默认端口	源
React（CRA）	3000	http://localhost:3000
Vite	5173	http://localhost:5173
Angular	4200	http://localhost:4200
Next.js	3000	http://localhost:3000

---

阶段 3：决策点

Q1：允许的源

环境	策略
Development	允许 localhost 源（可配置）
Production	仅使用环境变量中明确指定的源

**安全警告：**使用凭据时，绝不能使用 *（通配符）。

Q2：允许的方法

方法	默认值	说明
GET	✓ 是	读取操作
POST	✓ 是	创建操作
PUT	✓ 是	更新操作
DELETE	✓ 是	删除操作
PATCH	可选	部分更新
OPTIONS	✓ 是	预检请求（自动）

Q3：凭据支持

场景	AllowCredentials	说明
基于 Cookie 的身份验证	✓ 是	Cookie 所必需
请求头中的 JWT	✗ 否	不需要
OAuth2	视情况而定	查阅文档

**警告：**AllowCredentials = true 时，禁止使用 * 源。

Q4：预检缓存时长

环境	MaxAge	原因
Development	0	立即应用配置更改
Production	86400（24h）	减少预检请求

---

阶段 4：生成配置

.NET 输出文件

文件	用途
Extensions/CorsExtensions.cs	CORS 服务注册
appsettings.json（更新）	源配置
appsettings.Development.json（更新）	开发环境源

生成流程：

1. 使用 MCP ref 查询最新的 ASP.NET Core CORS API
2. 生成 CorsExtensions，包含：
   • Development 策略（宽松）
   • Production 策略（严格）
   • 基于环境选择策略
3. 使用 CORS:Origins 更新 appsettings

注册代码：

builder.Services.AddCorsPolicy(builder.Configuration);
// ...
app.UseCors(builder.Environment.IsDevelopment() ? "Development" : "Production");

Python 输出文件

文件	用途
middleware/cors_config.py	CORS 中间件配置
.env（更新）	CORS_ORIGINS 变量

生成流程：

1. 使用 MCP ref 查询 FastAPI CORSMiddleware
2. 生成 cors_config.py，包含：
   • 从环境变量解析源
   • 方法和请求头配置
   • 凭据处理
3. 使用 CORS_ORIGINS 更新 .env

注册代码：

from middleware.cors_config import configure_cors
configure_cors(app)

---

阶段 5：验证

验证步骤：

1. 语法检查：

   • .NET：dotnet build --no-restore
   • Python：python -m py_compile middleware/cors_config.py

2. CORS 测试：

   # Test preflight request
   curl -X OPTIONS http://localhost:5000/api/test \
     -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: POST" \
     -v
   

3. 验证请求头：

   • Access-Control-Allow-Origin：应与请求源匹配
   • Access-Control-Allow-Methods：应列出允许的方法
   • Access-Control-Allow-Credentials：启用时为 true
   • Access-Control-Max-Age：缓存时长

---

安全检查清单

完成前，请确认：

• 生产环境中没有使用通配符 * 来源
• 明确指定允许的方法（生产环境中不使用 AllowAnyMethod）
• 仅在需要时启用凭据
• 生产环境中的来源从环境变量读取
• 生产环境中已启用预检请求缓存

---

返回协调器

{
  "status": "success",
  "files_created": [
    "Extensions/CorsExtensions.cs"
  ],
  "packages_added": [],
  "registration_code": "builder.Services.AddCorsPolicy(configuration);",
  "message": "Configured CORS with Development and Production policies"
}

---

参考链接

• ASP.NET Core CORS
• FastAPI CORS
• MDN CORS

---

关键规则

• 绝不要在启用凭据时使用通配符 * 来源——这违反了 CORS 规范
• 生产环境中的来源只能从环境变量读取——代码中不得硬编码 URL
• 为开发和生产环境分别设置策略——本地配置宽松，生产环境配置严格
• 保持幂等——如果已存在 AddCors/UseCors 或 CORSMiddleware，则返回 status: "skipped"
• 在生产环境中启用预检请求缓存——将 MaxAge 设为 86400（24 小时），以减少 OPTIONS 请求

完成标准

• 已接收上下文存储（技术栈、项目根目录、环境）
• 已检测前端来源（自动检测端口/框架）
• 已收集用户决策（来源、方法、凭据、缓存时长）
• 已生成按环境区分策略的 CORS 配置
• 已通过安全检查清单验证（无通配符与凭据组合、明确指定方法、来源基于环境变量）
• 已验证语法（dotnet build 或 py_compile）
• 已向 ln-770 协调器返回结构化 JSON 响应

---

版本： 2.0.0 最后更新： 2026-01-10