#API 请求来源与许可证校验

Data Agent API 除了身份认证和数据权限外，还会校验请求来源是否符合许可证授权范围。调用 /api/ 下的 Data Agent 接口时，请确保请求携带有效的 Origin 或 Referer。

#校验规则

服务端按以下顺序确定请求来源：

1. 优先读取 Origin 请求头。
2. 请求没有 Origin 时读取 Referer 请求头。
3. 从请求头中提取域名和端口，与许可证登记的域名列表匹配。

满足以下任一条件即可提供来源信息：

• 浏览器请求自动携带 Origin，且该来源与许可证登记域名匹配。
• 非浏览器客户端显式携带 Referer，且该地址的域名和端口与许可证登记信息匹配。

例如许可证登记了 data-agent.example.com，服务端可以接受：

Origin: https://data-agent.example.com

或者：

Referer: https://data-agent.example.com/admin

校验时会提取来源的 hostname:port。协议和 URL 路径不参与最终域名匹配；如果使用非默认端口，许可证中必须包含该端口。

如果请求同时携带 Origin 和 Referer，服务端优先使用 Origin。因此不能用一个不匹配的 Origin 搭配一个匹配的 Referer 绕过校验。

#curl 和服务端调用

curl、定时任务和后端服务通常不会自动发送来源头，需要显式添加 Referer：

curl 'https://data-agent.example.com/api/auth:check' \
  -H 'Authorization: Bearer <token>' \
  -H 'Referer: https://data-agent.example.com/' \
  -H 'x-spaces: default'

Referer 应使用许可证登记的 Data Agent 访问地址。不要照搬示例中的域名。

服务端程序也可以发送 Origin，但一般建议非浏览器客户端统一发送 Referer，便于和浏览器的真实跨域来源区分。

#浏览器跨域调用

浏览器会自动设置 Origin，前端 JavaScript 不能手工覆盖该请求头。当前端与 Data Agent 不同源时，需要同时满足两层规则：

1. 许可证域名校验：浏览器的 Origin 必须与许可证登记域名匹配。
2. CORS 校验：浏览器的 Origin 必须包含在服务端环境变量 CORS_ORIGIN_WHITELIST 中。

例如前端运行在 https://app.example.com，应申请将 app.example.com 加入许可证域名，并配置：

CORS_ORIGIN_WHITELIST=https://app.example.com

多个跨域来源使用英文逗号分隔：

CORS_ORIGIN_WHITELIST=https://app.example.com,https://admin.example.com

修改环境变量后需要重启 Data Agent。完整的 CORS 配置说明请参考 CORS 跨域白名单配置。

CORS_ORIGIN_WHITELIST 和许可证域名列表不是同一项配置。前者决定浏览器是否允许读取跨域响应，后者决定许可证是否允许该来源调用 Data Agent API。

#反向代理统一补充 Referer

如果多个可信服务通过同一个反向代理访问 Data Agent，也可以由代理统一补充 Referer：

location /api {
    proxy_pass http://localhost:13000;
    proxy_set_header Host $host;
    proxy_set_header Referer "https://data-agent.example.com/";
}

该地址必须与许可证登记域名匹配。只应对可信调用链使用此配置，不要把可由外部任意访问的代理配置成固定来源，否则会失去来源校验的隔离作用。

如果需要保留浏览器的真实跨域来源，不应覆盖其 Origin。由于服务端优先校验 Origin，即使代理补充了 Referer，不匹配的浏览器 Origin 仍会校验失败。

#常见错误

#许可证域名不匹配

错误信息通常包含：

许可证域名与当前域名不匹配（origin="..."，referer="..."）

依次检查：

1. 请求是否携带 Origin 或 Referer。
2. 同时存在两个请求头时，Origin 是否正确。
3. 来源域名和端口是否已登记到当前实例的许可证。
4. 请求经过网关或反向代理后，来源头是否仍被正确转发。

#浏览器提示 CORS 错误

先确认来源已加入 CORS_ORIGIN_WHITELIST，再确认同一来源也已登记到许可证。只配置其中一项仍可能失败。

#Postman 或 curl 可以调用，浏览器不能调用

通常是 curl 显式传入的 Referer 可以通过许可证校验，但浏览器的真实 Origin 没有同时通过许可证或 CORS 白名单。以浏览器开发者工具中实际发送的 Origin 为准检查配置。