安全与生产

先把安全边界和上线要求看完，再接生产。

接口调通不等于可上线。先确认令牌、转发、隔离和日志。

查看计费指南查看排错手册

API 文档/安全与生产

令牌管理

令牌同时是权限边界和计费边界。

令牌同时决定权限、审计、限流和计费。

不要把生产令牌直接发到浏览器

终端应用应优先走你自己的服务端接口，再由服务端转发到对应供应商原生路由。

每个环境一把独立 Key

开发、测试、预发、生产至少拆开，避免测试流量和权限污染生产。

每条业务线分开治理

按团队或业务用途拆分令牌，更利于审计、封禁和异常成本隔离。

服务端中转

默认推荐由你自己的服务端转发。

这样更容易统一鉴权、限流和日志，也能避免暴露完整 Key。

服务端中转是默认推荐方案

统一处理鉴权、日志、限流和模型白名单。
客户端不需要知道你的真实令牌以及计费细节。

浏览器端只拿业务态，不拿完整 Key

即使是自家前端，也不要把高权限令牌直接塞进静态代码或 localStorage。
如果必须前端直连，也应该用权限更窄、生命周期更短的专用令牌。

Next.js 服务端中转示例

// app/api/chat/route.ts
import { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  const payload = await request.json();

  const response = await fetch("https://api.ciyuan.com/v1/messages", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.TOKENAI_API_KEY}`,
    },
    body: JSON.stringify(payload),
  });

  return new Response(response.body, {
    status: response.status,
    headers: { "Content-Type": response.headers.get("Content-Type") ?? "application/json" },
  });
}

环境隔离

环境隔离要先做对。

别让 staging 和 production 共用同一套配置。

环境变量不要混用

生产环境应使用独立 `TOKENAI_API_KEY`、独立域名和独立日志保留策略。
不要为了省事让 staging 和 production 共用同一个网关令牌。

高风险模型单独隔离

高成本或高风险能力最好做单独白名单，不要默认暴露给所有客户端。
出现异常时先切断高风险路由，比事后查账更有效。

环境隔离示例

# Production
TOKENAI_BASE_URL=https://api.ciyuan.com
TOKENAI_API_KEY=tk_prod_xxx

# Staging
TOKENAI_BASE_URL=https://token-staging.bytrabbit.com
TOKENAI_API_KEY=tk_stage_xxx

审计与限流

日志、审计和限流应该一起设计。

关键不是能响应，而是异常时能快速定位和收口。

日志不只是排错，也用于审计

至少保留请求时间、令牌、模型、usage、响应状态和渠道信息。
异常高 usage、频繁 401/429、短时间高并发都应该进入运营告警视图。

限流既是风控也是安全护栏

分钟和小时级限流可以阻断意外失控流量。
收到 `429` 后要求客户端退避重试，而不是继续无间隔压测。

上线清单

上线前逐项确认这张清单。

上线前按这张表逐项核对即可。

生产令牌不直接出现在浏览器端、客户端仓库或公开文档示例里。
开发、测试、生产环境分别使用独立 Key 和独立充值余额。
高成本模型有单独白名单，不作为默认模型直接暴露。
服务端保留 usage、模型、状态码和调用时间，便于审计与对账。
客户端处理好 401 / 429 / SSE 解析失败，不会无间隔死循环重试。
上线前用真实令牌跑通一次最小链路，并确认钱包余额、限流和日志都工作正常。

安全与生产

先把安全边界和上线要求看完，再接生产。

接口调通不等于可上线。先确认令牌、转发、隔离和日志。

查看计费指南查看排错手册

API 文档/安全与生产

令牌管理

令牌同时是权限边界和计费边界。

令牌同时决定权限、审计、限流和计费。

不要把生产令牌直接发到浏览器

终端应用应优先走你自己的服务端接口，再由服务端转发到对应供应商原生路由。

每个环境一把独立 Key

开发、测试、预发、生产至少拆开，避免测试流量和权限污染生产。

每条业务线分开治理

按团队或业务用途拆分令牌，更利于审计、封禁和异常成本隔离。

服务端中转

默认推荐由你自己的服务端转发。

这样更容易统一鉴权、限流和日志，也能避免暴露完整 Key。

服务端中转是默认推荐方案

统一处理鉴权、日志、限流和模型白名单。
客户端不需要知道你的真实令牌以及计费细节。

浏览器端只拿业务态，不拿完整 Key

即使是自家前端，也不要把高权限令牌直接塞进静态代码或 localStorage。
如果必须前端直连，也应该用权限更窄、生命周期更短的专用令牌。

Next.js 服务端中转示例

// app/api/chat/route.ts
import { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  const payload = await request.json();

  const response = await fetch("https://api.ciyuan.com/v1/messages", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.TOKENAI_API_KEY}`,
    },
    body: JSON.stringify(payload),
  });

  return new Response(response.body, {
    status: response.status,
    headers: { "Content-Type": response.headers.get("Content-Type") ?? "application/json" },
  });
}

环境隔离

环境隔离要先做对。

别让 staging 和 production 共用同一套配置。

环境变量不要混用

生产环境应使用独立 `TOKENAI_API_KEY`、独立域名和独立日志保留策略。
不要为了省事让 staging 和 production 共用同一个网关令牌。

高风险模型单独隔离

高成本或高风险能力最好做单独白名单，不要默认暴露给所有客户端。
出现异常时先切断高风险路由，比事后查账更有效。

环境隔离示例

# Production
TOKENAI_BASE_URL=https://api.ciyuan.com
TOKENAI_API_KEY=tk_prod_xxx

# Staging
TOKENAI_BASE_URL=https://token-staging.bytrabbit.com
TOKENAI_API_KEY=tk_stage_xxx

审计与限流

日志、审计和限流应该一起设计。

关键不是能响应，而是异常时能快速定位和收口。

日志不只是排错，也用于审计

至少保留请求时间、令牌、模型、usage、响应状态和渠道信息。
异常高 usage、频繁 401/429、短时间高并发都应该进入运营告警视图。

限流既是风控也是安全护栏

分钟和小时级限流可以阻断意外失控流量。
收到 `429` 后要求客户端退避重试，而不是继续无间隔压测。

上线清单

上线前逐项确认这张清单。

上线前按这张表逐项核对即可。

生产令牌不直接出现在浏览器端、客户端仓库或公开文档示例里。
开发、测试、生产环境分别使用独立 Key 和独立充值余额。
高成本模型有单独白名单，不作为默认模型直接暴露。
服务端保留 usage、模型、状态码和调用时间，便于审计与对账。
客户端处理好 401 / 429 / SSE 解析失败，不会无间隔死循环重试。
上线前用真实令牌跑通一次最小链路，并确认钱包余额、限流和日志都工作正常。

页面加载中

先把安全边界和上线要求看完，再接生产。

令牌同时是权限边界和计费边界。

默认推荐由你自己的服务端转发。

环境隔离要先做对。

日志、审计和限流应该一起设计。

上线前逐项确认这张清单。

先把安全边界和上线要求看完，再接生产。

令牌同时是权限边界和计费边界。

默认推荐由你自己的服务端转发。

环境隔离要先做对。

日志、审计和限流应该一起设计。

上线前逐项确认这张清单。