> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 固定 IP 代理转发方案

> 企业微信、飞书等平台对接中业务刚需固定出口 IP 时的代理转发方案（专用通道，域名白名单为封闭集合，仅覆盖平台接口域名），包括代理接口规范、Edge Function 调用方式、使用场景判断和与 Token 缓存的协作流程。

<Warning>
  本方案是否适用，取决于目标服务如何识别调用方：

  * **按来源 IP 鉴权**（企业微信、飞书等平台的 IP 白名单机制）：业务上刚需固定出口 IP，这是本代理服务的唯一场景。代理的域名白名单是封闭集合，仅覆盖这类平台的接口域名；`403` 表示目标域名不在覆盖范围内，属设计行为。
  * **按请求内凭证鉴权**（API Key / Bearer Token，常见于检索、支付、短信等第三方服务）：目标服务不校验调用方 IP，不存在固定 IP 刚需，Edge Function 直接 `fetch` 目标域名即可，不要接入本代理。

  个别第三方确实强制要求调用方 IP 白名单（即真实存在固定 IP 刚需）、且项目为官方 Supabase 时，请与 superun 团队评估自建 Supabase（固定出口 IP）等方案。
</Warning>

## 一、问题背景

企业微信平台的服务端 API 要求调用方 IP 在白名单内。Edge Function（Supabase / Deno Deploy）是 serverless 架构，每次请求的出口 IP 不固定，无法直接加入平台白名单。

需要一个固定出口 IP 的代理层，所有对平台 API 的请求通过它中转，这样只需在平台白名单中添加代理服务器的 IP 即可。

***

## 二、代理服务

### 2.1 地址

```
https://gateway.superun.ai/proxy/forward
```

### 2.2 工作原理

代理是 **完全透明** 的——不解析、不修改请求内容，只负责将请求原样转发到目标地址，并将响应原样返回。

### 2.3 接口规范

```
[GET|POST|PUT|DELETE|PATCH] https://gateway.superun.ai/proxy/forward?target_url={encodeURIComponent 编码后的目标URL}
```

| 参数                      | 位置           | 说明                                                                                   |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------ |
| `target_url`            | Query 参数（必填） | 目标请求的完整 URL，需要 `encodeURIComponent` 编码                                               |
| `superun-cloud-api-key` | Header（必填）   | Superun Cloud API Key，用于身份验证。在 Deno 环境中通过 `Deno.env.get("SUPERUN_CLOUD_API_KEY")` 获取 |
| Method / Headers / Body | —            | 透传：过滤掉 hop-by-hop 头和 `superun-cloud-api-key` 后原样转发，响应同样原样返回                          |

**错误响应**：

| 状态码                         | 响应体                                                                                                      | 含义                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `401 Unauthorized`          | `superun-cloud-api-key is missing or invalid. This API is only available in superun Cloud Edge Function` | `superun-cloud-api-key` 缺少或无效。该接口仅允许在 Superun Cloud Edge Function 中调用 |
| `403 Forbidden`             | `Proxy host was not supported, please contact the superun team`                                          | 目标域名不在本方案覆盖的平台域名集合内（封闭集合，属设计行为）                                       |
| `502 Bad Gateway`           | `Bad Gateway`                                                                                            | 代理无法连接到目标服务器                                                          |
| `500 Internal Server Error` | `Internal Server Error`                                                                                  | 代理自身异常                                                                |

***

## 三、Edge Function 调用方式

### 3.1 通用 `proxyFetch` 函数

```typescript theme={null}
const PROXY_BASE = "https://gateway.superun.ai/proxy/forward";
const SUPERUN_API_KEY = Deno.env.get("SUPERUN_CLOUD_API_KEY")!;

async function proxyFetch(
  targetUrl: string,
  init?: RequestInit
): Promise<Response> {
  const proxyUrl = `${PROXY_BASE}?target_url=${encodeURIComponent(targetUrl)}`;
  const headers = new Headers(init?.headers);
  headers.set("superun-cloud-api-key", SUPERUN_API_KEY);
  return fetch(proxyUrl, {
    method: init?.method ?? "GET",
    headers,
    body: init?.body,
  });
}
```

### 3.2 使用示例

**GET 请求**（企微获取 access\_token）：

```typescript theme={null}
const url = `https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${corpId}&corpsecret=${corpSecret}`;
const resp = await proxyFetch(url);
const data = await resp.json();
```

***

## 四、白名单配置

代理服务器的固定出口 IP：

```
43.153.7.159
43.153.29.204
```

***

## 五、域名白名单

代理的域名白名单是随平台对接能力一起维护的封闭集合，仅覆盖企业微信、飞书等平台的接口域名；集合外的域名返回 `403 Forbidden`，属设计行为。

是否在覆盖范围内，按页首的判断标准回溯：只有业务刚需固定出口 IP 的平台对接才经本代理；按 API Key / Bearer Token 鉴权的服务直接 `fetch` 目标域名即可。

***

<Card title="superun 网站" icon="globe" href="https://superun.com/web" horizontal>
  访问该网站以了解更多功能和示例.
</Card>