迁移到 API 专用地址

早期的集成在 Sursa 的主地址（即用户在浏览器中打开的地址）上调用 API，例如 https://app.sursa.com/v1/…。现在 API 还有了自己的专用地址：在云中是 https://api.sursa.com，在您的部署中是 https://api.<your domain>。该地址专为集成而建：它在负载均衡器后横向扩展，并且只提供 API。

迁移不是必需的。主地址会继续为现有集成提供 /v1，没有截止日期，也不会重定向。可以在合适的时候迁移，以获得 API 专用地址的好处；所有新集成都请使用 API 专用地址。

保持不变的内容

路径、参数、字段、错误码和事件：GET /v1/cards 在两个地址上是同一个请求。
API 密钥。同样的 kb_ 和 kbsrc_ 密钥在两个地址上都有效，角色、权限范围和数据权限档案都相同。
幂等键、速率限制和配额。两个地址上的请求计入组织的同一组配额。
Webhook。投递、签名和签名密钥与您调用的地址无关。
响应中的链接。无论调用哪个地址，错误的 doc_url 都指向本门户，列表页面的 Link 头都指向 API 专用地址。

API 专用地址上的不同之处

在主地址上	在 API 专用地址上
Web 应用的所有接口，包括内部接口	只有公共 API 参考中的接口。其他任何路径都返回 `404`，错误码为 `api.not_found`。
密钥放在 `X-API-Key` 或 `Authorization` 中，或者使用浏览器会话 Cookie	使用密钥或 OAuth 访问令牌，最好放在 `Authorization: Bearer` 中。Cookie 会被忽略。
`GET /auth/me`	`GET /v1/me`。不提供 `/auth/` 下的路径。
通过 Cookie 使用“View as”模式（以他人身份查看）	使用 `X-View-As` 头，适用于具有 `admin` 角色的密钥。
一台服务器，或固定的一组服务器	负载均衡器后的多台服务器。

最后一行只在一种情况下有影响：POST /v1/chat 的流式回答。中断的流只有在生成该回答的服务器上才能从 Last-Event-ID 继续。如果集成会恢复流，请为每个问题指定 request_id，这样在另一台服务器上重试时会收到已保存的回答，而不是第二个回答。参见恢复中断的流。

迁移之前

确认每个调用都是公共接口。列出集成调用的路径，逐个在 API 参考中查找，或者与新地址的规范进行比较：

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

公共参考中没有的路径属于 Web 应用。它在主地址上仍然可用，但 API 专用地址不提供它，其结构也不是公开承诺的一部分。请换用公共接口；或者把集成的这一部分留在主地址上，并告诉您在 Sursa 的对接人您需要什么。

确认身份验证方式。如果集成用用户的密码和会话 Cookie 登录，请先改用 API 密钥。如果集成发送 X-API-Key，建议改用 Authorization: Bearer，但这不是必需的。

确认网络设置。在防火墙和代理中放行到新主机名的出站 HTTPS 连接。

分步迁移

把基础 URL 设为集成的配置项（如果还不是的话）。

用一个读取请求试用新地址：

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

针对新地址运行集成的测试套件，使用测试密钥和测试合集。
切换一部分流量，例如一个工作进程或一个环境，并在日志中留意 404 api.not_found、401 和 5xx。每个响应都带有 X-Request-Id；请把它和日志一起保存。
切换其余流量。在配置中暂时保留旧的基础 URL，以便在几秒内切换回去。

迁移后要检查的事项

新地址上的 GET /v1/health 返回的 version 与旧地址相同。
响应中带有 RateLimit 头。如果集成根据 X-RateLimit-* 自行限速，可以继续这样做：两组响应头都会发送。参见速率限制与配额。
如果集成在浏览器中运行，就不再需要自建代理来处理 CORS：API 专用地址允许来自任何源的请求，不使用 Cookie。