CORS 配置指南

🚀 快速开始 (5分钟配置)

步骤 0: 了解当前行为

⚠️ 重要: 如果项目未配置 cors 字段，系统会允许任何 origin 的请求（向后兼容但不安全）。

要修复 CORS 漏洞，必须显式配置 cors 对象来启用白名单验证。

步骤 1: 确定你的域名

假设你的项目域名是 https://chatbi-test.example.com

步骤 2: 配置CORS

选项 A: 只允许主域名访问 (最安全)

在"系统参数配置"菜单栏下，打开专家模式，在json编辑器里面加入cors字段：

{
  "cors": {
    "allowedOrigins": []  // 空数组，只允许主域名
  }
}

这样会:

• ✅ 允许 https://chatbi-test.example.com
• ✅ 允许 http://chatbi-test.example.com
• ❌ 拒绝其他所有域名

选项 B: 允许额外的域名 (推荐)

{
  "cors": {
    "allowedOrigins": [
      "https://app.example.com",
      "https://mobile.example.com"
    ]
  }
}

步骤 3: 保存配置并重启

1. 点击"保存"按钮保存配置
2. 重启ChatBI服务容器：

# 重启Docker容器
docker restart yiask

步骤 4: 验证

# 测试合法域名
curl -i -H "Origin: https://app.example.com" \
     https://chatbi-test.example.com/

# 查看响应头，应该包含:
# Access-Control-Allow-Origin: https://app.example.com

---

📋 常见场景配置

场景 1: 单页应用 + API 服务器

如果前端和后端在不同域名：

{
  "cors": {
    "allowedOrigins": [
      "https://app.example.com"  // 前端域名
    ]
  }
}

场景 2: 多个前端应用

如果有 Web、移动端、管理后台多个前端：

{
  "cors": {
    "allowedOrigins": [
      "https://web.example.com",
      "https://mobile.example.com",
      "https://admin.example.com"
    ]
  }
}

场景 3: 测试环境 + 生产环境

{
  "cors": {
    "allowedOrigins": [
      "https://chatbi-test.example.com",  // 测试
      "https://chatbi-dev.example.com",   // 开发
      "https://chatbi.example.com"        // 生产
    ]
  }
}

场景 4: 允许所有子域名

如果有很多子域名 (app1, app2, app3...)：

{
  "cors": {
    "allowedOrigins": [
      "https://example.com"  // 主域名
    ],
    "allowSubdomains": true  // ⚠️ 慎用
  }
}

---

⚡ 配置示例

完整配置示例

{
  "cache": true,
  "production": true,
  "jwtsecret": "your-jwt-secret",
  "frontend": {
    "primaryColor": "#1972C6",
    "brand": "ChatBI",
    "logo": "/logo.svg"
  },
  "cors": {
    "allowedOrigins": [
      "https://app.example.com",
      "https://mobile.example.com"
    ],
    "allowSubdomains": false,
    "allowCredentials": true,
    "maxAge": 86400
  }
}

配置字段说明

字段名	类型	默认值	说明
allowedOrigins	Array	[]	允许的域名列表，空数组表示只允许主域名
allowSubdomains	Boolean	false	是否允许所有子域名
allowCredentials	Boolean	true	是否允许发送Cookie等凭证
maxAge	Number	86400	预检请求缓存时间（秒）

---

🔧 故障排查

问题: 配置后还是被拦截

解决方案:

1. 检查域名拼写 (注意协议和端口):

   ✅ "https://app.example.com"
   ❌ "app.example.com"  // 缺少协议
   ❌ "https://app.example.com/"  // 多了斜杠

2. 确认已重启服务器容器:

   docker restart yiask

3. 查看实际的 Origin:

   • 打开浏览器开发者工具 → Network
   • 查看请求头中的 Origin 字段
   • 确保配置的域名与实际 Origin 完全一致

4. 检查配置是否生效:

   • 重新打开"系统参数配置"页面
   • 确认cors配置已保存

问题: 子域名配置不生效

解决方案:

确保：

1. allowSubdomains 设为 true
2. allowedOrigins 中包含主域名
3. 子域名格式正确

// ✅ 正确
{
  "cors": {
    "allowedOrigins": ["https://example.com"],  // 主域名
    "allowSubdomains": true
  }
}

// ❌ 错误
{
  "cors": {
    "allowedOrigins": ["https://app.example.com"],  // 子域名
    "allowSubdomains": true
  }
}

---

📚 配置优先级

项目 MongoDB 配置 > 项目文件配置 > 全局配置

示例:

// 1. 项目 MongoDB settings (最高优先级)
{ "cors": { "allowedOrigins": ["https://mongodb.com"] } }

// 2. projects/<project>/settings.js
export default {
  cors: { allowedOrigins: ["https://file.com"] }
}

// 3. src/globalConfig.js (最低优先级)
export default {
  cors: { allowedOrigins: ["https://global.com"] }
}

// 结果: 只允许 https://mongodb.com

---

⚠️ 安全警告

❌ 不要这样做:

// 1. 不要允许所有域名
"cors": {
  "allowedOrigins": ["*"]  // ❌ 不支持且不安全
}

// 2. 不要在生产环境启用子域名匹配 (除非确实需要)
"cors": {
  "allowSubdomains": true  // ⚠️ 可能允许不受信任的子域名
}

// 3. 不要关闭 CORS
"closeCORS": true  // ❌ 非常危险

✅ 应该这样做:

// 1. 明确列出允许的域名
"cors": {
  "allowedOrigins": [
    "https://app.example.com",
    "https://mobile.example.com"
  ]
}

// 2. 使用 HTTPS
"cors": {
  "allowedOrigins": [
    "https://app.example.com"  // ✅ HTTPS
  ]
}

// 3. 定期审查配置
// 移除不再使用的域名

---

🎯 测试命令

基础测试

# 测试合法域名 (应该返回 Access-Control-Allow-Origin)
curl -i -H "Origin: https://allowed-domain.com" \
     https://your-server.com/

# 测试非法域名 (应该不返回 Access-Control-Allow-Origin)
curl -i -H "Origin: https://evil.com" \
     https://your-server.com/

预检请求测试

# 测试 OPTIONS 请求
curl -i -X OPTIONS \
     -H "Origin: https://app.example.com" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Content-Type" \
     https://your-server.com/api/v1/data

---

🔍 调试技巧

1. 查看服务器日志:

   tail -f projects/<project>/apacheLogs/access.log

2. 浏览器开发者工具:

   • 查看Console中的CORS错误信息
   • 查看Network标签中的请求头和响应头

3. 使用Postman测试:

   • 在Headers中添加 Origin: https://your-domain.com
   • 查看响应头中的CORS相关字段

---

📞 需要帮助？

1. 查看服务器日志: tail -f projects/<project>/apacheLogs/access.log
2. 检查系统参数配置: 确认cors配置已正确保存
3. 联系技术支持: 提供具体的错误信息和配置截图

注意: 所有CORS配置都需要在"系统参数配置"菜单栏下，打开专家模式，在json编辑器里面进行配置。