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

# 固定 IP 代理轉發方案

> 企業微信、飛書等平台對接中業務剛需固定出口 IP 時的方案（專用通道，域名白名單為封閉集合，僅覆蓋平台介面域名）：官方 Supabase 走代理轉發，自建 Supabase 直連。

<Warning>
  本方案是否適用，取決於目標服務如何識別呼叫方：

  * **按來源 IP 鑑權**（企業微信、飛書等平台的 IP 白名單機制）：業務上剛需固定出口 IP，這是本代理服務的唯一場景。代理的域名白名單是封閉集合，僅覆蓋這類平台的介面域名；`403` 表示目標域名不在覆蓋範圍內，屬設計行為。
  * **按請求內憑證鑑權**（API Key / Bearer Token，常見於檢索、支付、簡訊等第三方服務）：目標服務不校驗呼叫方 IP，不存在固定 IP 剛需，Edge Function 直接 `fetch` 目標域名即可，不要接入本代理。

  個別第三方確實強制要求呼叫方 IP 白名單（即真實存在固定 IP 剛需）、且專案為官方 Supabase 時，請與 superun 團隊評估自建 Supabase（固定出口 IP）等方案。
</Warning>

平台（企業微信、飛書等）要求呼叫方 IP 在白名單內。superun Cloud 的 Supabase 分兩類，按專案 `SUPABASE_URL` 域名判斷：

| 類型 | 域名 | 出口 IP | 對接方式 |
| - | - | - | - |
| 官方 Supabase | `*.supabase.co` | 不固定 | 經 superun 代理轉發 |
| 自建 Supabase | `*.db.superun.com` | 已固定 | 直連，無需代理 |

## 一、官方 Supabase：代理轉發

出口 IP 不固定，平台 API 請求須經 superun 代理中轉（透明轉發，僅過濾 hop-by-hop 標頭與鑑權標頭）：

```
[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（必填） | 取自 `Deno.env.get("SUPERUN_CLOUD_API_KEY")` |

錯誤：`401` Key 無效；`403` 目標域名不在本方案覆蓋的平台域名集合內（封閉集合，屬設計行為）；`502` 無法連接目標。

Edge Function 中用 `proxyFetch` 替代 `fetch` 呼叫平台 API：

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

function proxyFetch(targetUrl: string, init?: RequestInit) {
  const headers = new Headers(init?.headers);
  headers.set("superun-cloud-api-key", SUPERUN_API_KEY);
  return fetch(`${PROXY_BASE}?target_url=${encodeURIComponent(targetUrl)}`, {
    ...init,
    headers,
  });
}
```

**企業可信 IP**（代理出口，填入平台白名單）：

```
43.153.7.159
43.153.29.204
```

## 二、自建 Supabase：直連

出口 IP 已固定，Edge Function 直接請求平台 API，無需代理。

企業可信 IP 可能不止一個， **請勿寫死**。

> **Agent 說明**：判斷為自建 Supabase（`*.db.superun.com`）時，呼叫 tool 按 `SUPABASE_URL` 查詢其固定 **出口 IP**，再告知使用者（多個用分號分隔填入平台白名單）。勿猜測或寫死。

<Card title="superun 網站" icon="globe" href="https://superun.com/web" horizontal>
  訪問該網站以了解更多功能和範例.
</Card>