> For the complete documentation index, see [llms.txt](https://www.axisnow.io/zh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.axisnow.io/zh/docs/guide/new-api.md).

# 使用 AxisNow 保护并加速 New API

在边缘为 New API 加上令牌预检、访问控制、限速与缓存，优化中国大陆和全球访问体验。

本教程把 New API 放到 AxisNow 后面，按路径配置四个数据面插件：认证与授权、通用访问控制、速率控制、缓存控制。完成后，管理接口只对管理员开放，格式非法的请求在边缘被丢弃，合法令牌按令牌限速，静态资源走边缘缓存，流式响应仍然逐字输出。

## New API + AxisNow 的好处 <a href="#benefits" id="benefits"></a>

New API 解决的是模型接入：渠道、令牌、计费。它没有解决、也不该由它解决的是请求怎样到达它、哪些请求有资格到达它。部署成功只是第一步，用户最终感受到的体验，既取决于上游模型，也取决于客户端到 New API 这段网络和入口。AxisNow 补的就是这一段。

* **零改造接入。** 不用改 New API 一行代码，通过域名接入和反向代理就能把已有服务纳入边缘网络，原 API 域名可以保留，客户端零改动。
* **就近接入，链路稳定。** 支持自建和订阅边缘节点，按用户分布组合入口：主要服务中国大陆用户、源站在海外，可以测试香港、日本、新加坡等节点。地域与线路调度基于探测选路、故障时自动切换。对流式输出来说，稳定比带宽更重要，一次中断就打断一整段对话。
* **源站只处理合法流量。** 格式非法的令牌、撞库、高频调用在边缘就被处理掉，New API 的 CPU 和数据库留给真正的调用。验证稳定后，源站防火墙只放行边缘回源地址，攻击者无法绕过边缘直达源站。
* **策略按入口分层。** 网页、管理接口、程序调用的 API 面对的访问者不同，可以分别制定规则。尤其是 API 入口不会被误用浏览器验证，SDK 和 AI Agent 完成不了交互式验证码。
* **随业务增长扩展。** 起步只需一个入口，之后按真实流量补节点、调整调度。已经在用多家 CDN 的话，可以用 AxisNow Multi-Edge 统一编排，降低对单一提供商的依赖。

一句话概括：New API 帮你连接模型，AxisNow 帮你把这些能力安全、稳定地交付给用户、应用和 AI Agent。

## 准备工作 <a href="#prerequisites" id="prerequisites"></a>

* 一个已部署、可通过 IP 访问的 New API 实例。
* 已在 AxisNow 部署边缘节点，New API 的域名（下文以 `api.example.com` 为例）可将 DNS 指向边缘。
* 管理员的出口地址段：公司出口 IP、VPN 或堡垒机地址。
* 一个用于测试的 New API 令牌。

## 配置总览 <a href="#overview" id="overview"></a>

核心原则是按路径分工：New API 的不同路径访问者不同，在边缘分别处理。

<figure><img src="https://3062891322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKDgGNU6JXG7cqYCk2aCz%2Fuploads%2Fgit-blob-ebefa57b2249b9da15322400a543ab1da703c914%2Fnew-api-architecture.png?alt=media" alt="应用和浏览器的请求进入 AxisNow 边缘后按路径分四类处理：中转接口做认证预检和按令牌限速，账户接口按 IP 限速，管理接口只放行管理员地址，静态资源长缓存；只有合法流量到达 New API，New API 到上游模型厂商的一段不经过 AxisNow"><figcaption></figcaption></figure>

全部规则如下，后面各步骤逐条配置。

<table data-search="false"><thead><tr><th width="60">#</th><th width="150">插件</th><th width="220">匹配路径</th><th>关键配置</th><th width="170">作用</th></tr></thead><tbody><tr><td>B1</td><td>认证与授权</td><td><code>/v1/*</code><br><code>/v1beta/*</code></td><td>自定义认证，强制认证，关闭绕过速率控制</td><td>拒绝格式非法的令牌</td></tr><tr><td>A1</td><td>通用访问控制</td><td><code>/api/channel/*</code><br><code>/api/option/*</code></td><td>管理员地址段以外阻断</td><td>保护渠道与上游密钥</td></tr><tr><td>R1</td><td>速率控制</td><td><code>/v1/*</code><br><code>/v1beta/*</code></td><td>按令牌所在的请求头计数</td><td>限制单个令牌的调用频率</td></tr><tr><td>R2</td><td>速率控制</td><td><code>/api/user/login</code><br><code>/api/user/register</code></td><td>按 IP 计数，低阈值</td><td>防撞库与批量注册</td></tr><tr><td>C1</td><td>缓存控制</td><td><code>/assets/*</code></td><td>忽略源站，缓存 180 天</td><td>加速控制台加载</td></tr></tbody></table>

## 步骤 1：接入域名与回源 <a href="#step-origin" id="step-origin"></a>

1. 在**端点 › 域**中新增 `api.example.com`，源地址填写 New API 的实例地址；回源参数填协议、回源 Host 和端口（New API 默认 `http`、`3000`）。
2. 把 `api.example.com` 的 DNS 指向 AxisNow 边缘。

<figure><img src="https://3062891322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKDgGNU6JXG7cqYCk2aCz%2Fuploads%2F3Pu8sjZjzUHa7YkFkm8j%2Fimage.png?alt=media&amp;token=a3a94f4a-0818-4d2d-9ffe-0b4b2700443b" alt=""><figcaption></figcaption></figure>

真实客户端 IP 插件默认已把客户端地址以 `X-Real-IP` 和 `X-Forwarded-For` 传给源站，New API 的日志和其自身的 IP 限制读取的是这两个请求头；边缘前面如果还有 CDN 或负载均衡，先按[真实客户端 IP](/zh/docs/edge/policies/real-ip.md)配置获取规则。

{% hint style="info" %}
AxisNow Edge 能自动处理流式响应，如果您的源站前面还有 Nginx，需要关掉 `proxy_buffering` 。[Nginx 代理缓冲说明](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering)
{% endhint %}

**验证**：用 `curl -N` 调用流式接口，`-N` 关闭 curl 自己的缓冲，输出应该一行行出现：

```bash
curl -N https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","stream":true,"messages":[{"role":"user","content":"从 1 数到 20"}]}'
```

链路没通之前不要往下配插件。

## 步骤 2：认证与授权，在边缘做令牌预检 <a href="#step-authn" id="step-authn"></a>

New API 的 `sk-` 令牌是存储在其数据库中的随机字符串，不是 JWT。边缘无法判断令牌**是否有效**，但能判断它**是否符合令牌格式**。未携带凭据、格式或长度不符的请求不可能是合法调用，用[认证与授权](/zh/docs/edge/policies/authn-authz.md)的自定义认证在边缘直接拒绝。

### 2.1 创建自定义认证方式 <a href="#step-authn-method" id="step-authn-method"></a>

New API 兼容多家协议，令牌可能出现在三个位置：

<table data-search="false"><thead><tr><th width="220">调用格式</th><th>令牌位置</th></tr></thead><tbody><tr><td>OpenAI 兼容</td><td><code>Authorization: Bearer sk-…</code></td></tr><tr><td>Claude 兼容（<code>/v1/messages</code>）</td><td><code>x-api-key</code> 请求头</td></tr><tr><td>Gemini 兼容（<code>/v1beta/*</code>）</td><td><code>x-goog-api-key</code> 请求头或 <code>key</code> 查询参数</td></tr></tbody></table>

在**策略 › 认证与授权 › 认证方式**里新建一个自定义认证方式，代码如下，可用的 API 见[边缘运行时](/zh/docs/edge/policies/edge-runtime.md)。代码按顺序提取令牌，只校验格式；`message` 写入访问日志，用于区分未携带凭据和格式非法：

```lua
-- New API 令牌格式预检：只拒绝格式非法的请求，真伪仍由 New API 判断
local function bearer(v)
    if type(v) ~= "string" then return nil end
    return v:match("^[Bb]earer%s+(.+)$") or v
end

function handle(ctx)
    local req = ctx.request
    local token = bearer(req.headers:get("authorization"))
        or req.headers:get("x-api-key")
        or req.headers:get("x-goog-api-key")
        or req.query:get("key")
    if type(token) ~= "string" then
        return auth.result({ verified = false, message = "no_credential" })
    end

    -- 去除 sk- 前缀；New API 允许管理员在令牌后追加 -渠道ID
    local body = token:gsub("^sk%-", ""):gsub("%-%d+$", "")

    -- 长度以您部署版本实际生成的令牌为准（默认 48 位字母数字）
    if #body ~= 48 or not body:match("^%w+$") then
        return auth.result({ verified = false, message = "invalid_format" })
    end
    return auth.result({ verified = true })
end
```

### 2.2 配置规则 B1 <a href="#step-authn-rule" id="step-authn-rule"></a>

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>api.example.com</code>，并且 请求 URI 路径 开头为 <code>/v1/</code>、<code>/v1beta/</code></td></tr><tr><td>动作</td><td>强制认证，认证方式选择 2.1 创建的自定义认证</td></tr><tr><td>绕过速率控制</td><td>关闭（默认开启，不关闭则步骤 4 的 R1 不生效）</td></tr><tr><td>绕过通用访问控制</td><td>开启或关闭均可，A1 的路径不在本规则范围内</td></tr><tr><td>认证失败封禁</td><td>开启</td></tr></tbody></table>

![](https://3062891322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKDgGNU6JXG7cqYCk2aCz%2Fuploads%2Fgit-blob-32a45b7644f91b5a17ef209a94acb888646913a5%2Fnew-api-authn-rules.png?alt=media)

这条规则有三点需要了解。

* 自定义认证没有授权规则，函数返回什么，结果就是什么。
* 开启[认证失败封禁](/zh/docs/edge/policies/authn-authz/how-it-works.md#controls)后，同一 IP 在窗口内多次失败即被临时封禁，封禁期间的请求不再执行认证代码，这是对抗扫描的主要手段。自定义认证的每次失败都计入，未携带凭据也算：遗漏请求头的客户端如果在窗口内反复重试，同样会被封禁。
* `OPTIONS` 预检请求不经认证直接放行，浏览器端调用不受影响。

**验证**：在认证方式的集成测试里分别提交一个真实令牌、一个少一位字符的令牌和一个未携带凭据的请求，只有第一个应该通过。

## 步骤 3：通用访问控制，限制管理接口来源 <a href="#step-acl" id="step-acl"></a>

渠道接口背后是全部上游密钥。New API 在源站会校验管理员身份，边缘再加一道来源限制，即使管理员账号被撞库，外部也无法访问这些接口。在[通用访问控制](/zh/docs/edge/policies/access-control.md)里新建规则 **A1**：

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>api.example.com</code>，并且 请求 URI 路径 开头为 <code>/api/channel/</code>、<code>/api/option/</code>，并且 客户端 IP 地址 不在以下各项之中 <code>203.0.113.0/24</code>（管理员地址段）</td></tr><tr><td>动作</td><td>阻断</td></tr></tbody></table>

![](https://3062891322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKDgGNU6JXG7cqYCk2aCz%2Fuploads%2Fgit-blob-c7586d801645ee6a097d41d7a3e9d6f7c00472c1%2Fnew-api-acl-rules.png?alt=media)

管理员地址段需在多处使用时，可创建为 [IP 对象](/zh/docs/edge/policies/objects.md)，条件改为「客户端 IP 地址 不在对象中」。

控制台本身是否开放，取决于部署方式：

* **团队内部自用**：把 A1 的路径条件改为「请求 URI 路径 不以 `/v1/`、`/v1beta/` 开头」，整个控制台只对管理员地址开放，公网只保留中转接口。这是最彻底的做法。
* **对外分发令牌**：用户需要登录控制台查看额度、创建令牌，控制台必须公开。只限制 A1 的两类管理接口，登录接口由步骤 4 的 R2 限速。

## 步骤 4：速率控制，限制持有凭据的调用 <a href="#step-rate-limit" id="step-rate-limit"></a>

步骤 2 拦截的是格式非法的请求。持有真实令牌高频调用的，以及对登录接口撞库的，需由[速率控制](/zh/docs/edge/policies/rate-limiting.md)处理。

**R1：中转接口按令牌限速**

[计数维度](/zh/docs/edge/policies/rate-limiting/configuration.md#dimensions)取不到值时会落入同一个空值计数器，所以按请求头计数时要按调用格式各写一条规则，否则 Claude、Gemini 格式的调用会被一并计入 `Authorization` 为空的计数器：

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>R1a：请求 URI 路径 开头为 <code>/v1/</code>，并且 请求头 <code>authorization</code> 存在<br>R1b：请求 URI 路径 在以下各项之中 <code>/v1/messages</code>，并且 请求头 <code>x-api-key</code> 存在<br>R1c：请求 URI 路径 开头为 <code>/v1beta/</code></td></tr><tr><td>计数 Key</td><td>R1a：请求头 <code>authorization</code><br>R1b：请求头 <code>x-api-key</code><br>R1c：请求头 <code>x-goog-api-key</code></td></tr><tr><td>阈值</td><td>按业务设定，例如每令牌每分钟 120 次</td></tr><tr><td>动作</td><td>阻断（默认 429 Too Many Requests）</td></tr></tbody></table>

按令牌而不是按 IP 计数，原因有两个：LLM 的调用方常是服务器，一个 IP 背后可能是整个团队；而一个泄露的令牌，也可能同时从上百个 IP 被调用。阈值的设定方法见 [API 限速实战](/zh/docs/guide/rate-limiting-api.md)。

**R2：账户接口按 IP 严格限速**

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 URI 路径 在以下各项之中 <code>/api/user/login</code>、<code>/api/user/register</code>，并且 HTTP 请求方法 在以下各项之中 <code>POST</code></td></tr><tr><td>计数 Key</td><td>客户端 IP 地址</td></tr><tr><td>阈值</td><td>例如每 IP 每分钟 10 次</td></tr><tr><td>动作</td><td>阻断</td></tr></tbody></table>

![](https://3062891322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKDgGNU6JXG7cqYCk2aCz%2Fuploads%2Fgit-blob-f6b2048070e026c86fb7c87b969e7b400bd29a5d%2Fnew-api-rate-limit-rules.png?alt=media)

登录接口由前端脚本调用，无法完成验证页，动作不能选挑战。New API 自身也能按用户、按模型限流，两者是分工关系：边缘的限速将突发流量挡在源站之外，New API 的限流按业务分配额度。

## 步骤 5：缓存控制，只缓存静态资源 <a href="#step-cache" id="step-cache"></a>

[缓存控制](/zh/docs/edge/policies/cache.md)的默认规则只按文件后缀缓存脚本、样式、图片这类静态文件，接口路径和首页不会被缓存，不需要额外排除。只需为带哈希的构建产物延长缓存时长。新建规则 **C1**：

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>api.example.com</code>，并且 请求 URI 路径 开头为 <code>/assets/</code></td></tr><tr><td>缓存时长</td><td>忽略源站，默认时长 180 天</td></tr><tr><td>缓存 Key</td><td>预设 静态资源</td></tr><tr><td>浏览器缓存</td><td>自定义 180 天</td></tr></tbody></table>

![](https://3062891322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKDgGNU6JXG7cqYCk2aCz%2Fuploads%2Fgit-blob-3d175d672fbca13e5fe4e2254d48bdc6a2ab1d96%2Fnew-api-cache-rules.png?alt=media)

`/assets/*` 的文件名带内容哈希，升级后文件名会变化，可以长期缓存；边缘单条规则的[缓存时长](/zh/docs/edge/policies/cache/configuration.md#ttl)上限是 180 天。不要为 `/v1/models` 这类接口开启缓存：返回的模型列表取决于令牌所在的分组，按 URL 缓存会把 A 用户的列表返回给 B 用户。

## 验证上线 <a href="#go-live" id="go-live"></a>

* 经边缘调用接口正常返回
* 持续数分钟的长响应能完整返回，中途未断开
* New API 日志里记录的是真实客户端 IP
* 集成测试：真实令牌通过，格式非法的令牌和无凭据请求被拒（B1）
* 从非管理员 IP 访问 `/api/channel/`，在边缘被阻断（A1）
* OpenAI、Claude、Gemini 三种格式的调用各成功一次
* 同一令牌超过阈值后返回 429 Too Many Requests（R1）
* `/assets/*` 第二次请求响应头 `X-Cache: HIT`（C1）

## 洞察 <a href="#insight" id="insight"></a>

上线后通过[洞察](/zh/docs/edge/insight.md)确认三项内容。

* **拦截量**：[仪表板](/zh/docs/edge/insight/dashboard.md)的状态码分布中，401 对应 B1 的拒绝，403 对应 A1 的阻断，429 对应 R1、R2 的限速。错误率仅统计 5xx 响应，不受拦截影响。
* **被拒绝的请求**：在[日志检索](/zh/docs/edge/insight/log-explorer.md)中以命中规则 B1 和响应状态码 401 筛选，展开日志查看 `extras.authn_authz.message`：`invalid_format` 为格式非法，`no_credential` 为未携带凭据。
* **首个 token 的延迟来源**：展开相应请求的耗时瀑布，「源站处理（TTFB）」占比接近 100% 时，等待发生在 New API 与上游模型之间，边缘未引入额外延迟。

## 最佳实践要点 <a href="#best-practices" id="best-practices"></a>

* **先通链路，再加插件。** 链路没通就配插件，回源问题和规则问题会混在一起，难以排查。
* **按路径分工，不用一条规则覆盖全站。** 中转接口、账户接口、管理接口、静态资源的访问者不同，风险也不同。
* **边缘负责拦截，源站负责判断。** 边缘拒绝非法请求、限制频率；令牌真伪、计费、额度仍由 New API 判断，不要在边缘复制业务逻辑。
* **限速按身份，不按 IP。** 对 API 调用，令牌才是责任主体，同一出口 IP 之后可能是整个团队；IP 只用于登录、注册这类无法获取身份的接口。
* **只给确定安全的路径开缓存。** 宁可少缓存一个静态文件，也不要让一个带用户上下文的响应被共享。
* **管理接口多一道来源限制。** 账号密码可能泄露，来源地址段是独立的第二道防线。

## 常见问题 <a href="#faq" id="faq"></a>

**攻击者构造一个格式正确的随机令牌，是否就绕过了预检？**

能通过格式预检，但没有意义。48 位字母数字的空间约为 62⁴⁸，无法猜中真实令牌。这类请求唯一的影响是增加 New API 的查询负载。注意 R1 按令牌计数，对每次更换随机令牌的请求不起作用；如需额外防护，可对中转接口再加一条按 IP 的宽松限速，阈值远高于正常业务量。

**为什么不直接在边缘验证令牌真伪？**

这需要边缘实时查询 New API 的令牌库，等于在边缘复制一份业务逻辑，令牌吊销、额度变化都要同步。格式预检不依赖源站，已能拦截绝大多数无效流量。

**接入后首个 token 仍然慢，是 AxisNow 的问题吗？**

通常不是。边缘让用户就近完成 TLS 握手、通过稳定链路回源，改善的是连接建立和传输稳定性。New API 到上游模型厂商的那一段不经过 AxisNow，首个 token 的等待时间主要取决于模型本身。在日志检索里展开这条请求的耗时瀑布，「源站处理（TTFB）」占总耗时接近 100%，「边缘处理」只有几毫秒，即说明等待发生在源站之后。

更多问题欢迎在[社区电报群组](https://t.me/AxisNowGroupZh)交流。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.axisnow.io/zh/docs/guide/new-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.