> ## 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 白名单限制下的固定出口 IP 代理转发方案，包括代理接口规范、Edge Function 调用方式、使用场景判断和与 Token 缓存的协作流程。

## 一、问题背景

企业微信平台的服务端 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`                                          | 目标域名未在代理白名单中，需向 Superun 团队申请开通                                        |
| `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
```

***

## 五、域名白名单

代理服务对目标域名实施白名单机制。只有经过 Superun 团队审批的域名才能通过代理转发，未授权的域名将返回 `403 Forbidden`。

如需新增代理域名，请联系 Superun 团队申请开通。

***

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