部署至生產環境

上線是設定切換，而不是重寫。你的 queries、mutations 與流程在兩個環境中完全相同。改變的是你呼叫的主機與你使用的憑證——而且兩者都完全不同。

測試環境的任何東西都不會帶到生產環境。應用程式、API 金鑰、client secrets、redirect URI 與 webhook 訂閱在各自的環境中是分開存在的。測試環境的憑證永遠無法用在生產主機上，反之亦然。這是刻意設計的——能避免你不小心用測試工具移動真實資金。

端點對照表

目的	測試環境	生產環境
開發者控制台	`https://uni.staging.fluzapp.com/apps-and-integrations`	`https://fluz.app/for-developers`
OAuth 授權	`https://uni.staging.fluzapp.com/authorize`	`https://fluz.app/authorize`
Token 交換	`https://uni.staging.fluzapp.com/token/exchange`	`https://fluz.app/token/exchange`
Token 更新	`https://uni.staging.fluzapp.com/token/refresh`	`https://fluz.app/token/refresh`
GraphQL API	`https://transactional-graph.staging.fluzapp.com/api/v1/graphql`	`https://transactional-graph.fluzapp.com/api/v1/graphql`

GraphQL 主機與 OAuth 主機是不同服務、不同網域。只替換其中一個是最常見的切換錯誤——而且錯誤表現會讓人困惑，因為授權會成功，但每個 API 呼叫都會被拒絕。

進入各個入口網站

正式環境入口在 https://fluz.app/for-developers。從那裡的開發者分頁可點選 「Open Staging」 前往測試環境入口——你在兩個環境中的登入憑證相同。每個入口只會顯示該環境的應用程式與 API 金鑰。

將環境做成變數

如果任何主機、金鑰或 redirect URI 以字串常值寫在程式碼中，請在切換前修正。所有與環境相關的內容都應該放在設定中。

const ENVIRONMENTS = {
  staging: {
    authorizeUrl: 'https://uni.staging.fluzapp.com/authorize',
    tokenExchangeUrl: 'https://uni.staging.fluzapp.com/token/exchange',
    tokenRefreshUrl: 'https://uni.staging.fluzapp.com/token/refresh',
    graphqlUrl: 'https://transactional-graph.staging.fluzapp.com/api/v1/graphql',
    redirectUri: 'https://staging.example.com/oauth/finalize',
  },
  production: {
    authorizeUrl: 'https://fluz.app/authorize',
    tokenExchangeUrl: 'https://fluz.app/token/exchange',
    tokenRefreshUrl: 'https://fluz.app/token/refresh',
    graphqlUrl: 'https://transactional-graph.fluzapp.com/api/v1/graphql',
    redirectUri: 'https://app.example.com/oauth/finalize',
  },
};

export const fluz = ENVIRONMENTS[process.env.FLUZ_ENV ?? 'staging'];

// Credentials come from your secret store, keyed by the same environment name.
export const credentials = {
  clientId: process.env.FLUZ_CLIENT_ID,
  clientSecret: process.env.FLUZ_CLIENT_SECRET,
  apiKey: process.env.FLUZ_API_KEY,
  apiSecret: process.env.FLUZ_API_SECRET,
};

import os

ENVIRONMENTS = {
    "staging": {
        "authorize_url": "https://uni.staging.fluzapp.com/authorize",
        "token_exchange_url": "https://uni.staging.fluzapp.com/token/exchange",
        "token_refresh_url": "https://uni.staging.fluzapp.com/token/refresh",
        "graphql_url": "https://transactional-graph.staging.fluzapp.com/api/v1/graphql",
        "redirect_uri": "https://staging.example.com/oauth/finalize",
    },
    "production": {
        "authorize_url": "https://fluz.app/authorize",
        "token_exchange_url": "https://fluz.app/token/exchange",
        "token_refresh_url": "https://fluz.app/token/refresh",
        "graphql_url": "https://transactional-graph.fluzapp.com/api/v1/graphql",
        "redirect_uri": "https://app.example.com/oauth/finalize",
    },
}

FLUZ = ENVIRONMENTS[os.environ.get("FLUZ_ENV", "staging")]

# Credentials come from your secret store, keyed by the same environment name.
CREDENTIALS = {
    "client_id": os.environ["FLUZ_CLIENT_ID"],
    "client_secret": os.environ["FLUZ_CLIENT_SECRET"],
    "api_key": os.environ["FLUZ_API_KEY"],
    "api_secret": os.environ["FLUZ_API_SECRET"],
}

預設應該是測試環境，而不是生產環境。如果部署遺失了環境變數，你會希望它打到測試環境，而不是移動真實資金。

在正式環境入口重建你的應用程式

在 https://fluz.app/for-developers 重新操作一次 Create an OAuth App 與 Configure OAuth App。然後逐項檢查下列事項——每一點都是常見的遺漏：

重新簽發所有憑證

生產環境的 client_id、client_secret、apiKey 與 apiSecret 全都是新值。將它們放入你的生產機密儲存。確認生產設定中沒有殘留任何測試環境的值。

在生產主機上重新註冊 redirect URI

以生產環境的 callback URL，且必須是精確且正規化的形式。接著移除任何 localhost 或測試環境的 URI——生產應用程式不應接受導回到開發者筆電。

重新指向 webhook URL

指向可對外存取、受監控且具備警示的生產端點。重新勾選各事件訂閱；它們不會被複製。如果你在測試環境使用了全收件 URL，請決定在生產環境是否仍要如此。

將 Origin 設為你的生產網域

對於內嵌元件，這必須與實際提供頁面的網域一致，否則元件不會載入。

重新選擇你的 scopes

Scope 選擇不會轉移。逐一對照你的整合所呼叫的 API，確認每個呼叫所需的 scope 都已在生產應用程式的 Permissions 分頁勾選。缺少的 scope 會被靜默忽略，而不是被拒絕。

完成 Overview 分頁

名稱、副標、描述、頭像與標誌將會出現在真實使用者的授權畫面上，影響他們是否授權你存取其資金。若你不處理，範例文字就會被送上生產環境。

確認你的應用程式狀態

應用程式在控制台中有狀態——仍在審查中的應用程式，尚不能讓你的客戶使用。在對外宣布前，確認你的生產應用程式為啟用狀態。

生產環境下哪些行為不同

測試環境在沒有真實資金的情況下，盡可能鏡射生產的能力與交易流程。大多數面向是一致的，但仍有差異。

	測試環境	生產環境
資金	模擬	真實。轉帳在你這一側不可逆
KYC	具可預測結果的測試流程	以真實身分資料進行的實際驗證，可能被拒
卡片授權	模擬	真實網路授權與實際拒絕
清算時程	立即或模擬	真實銀行時程
資金來源	測試用銀行卡與帳戶	真實卡片與透過 Plaid 連結的帳戶
失敗模式	你選擇測試的那些	餘額不足、卡片過期、網路拒絕、驗證失敗

三個值得事先規劃的後果：

冪等性不再是可選項。 每個資金移動呼叫都需要唯一的 idempotencyKey，而小工具的權杖需要唯一的 jti。在測試環境，重複只是麻煩；在生產環境，則可能造成重複付款。參見 Idempotency。
你的錯誤處理會被真正考驗。 測試使用者不會因餘額不足被拒，也不會以你沒寫劇本的方式未通過 KYC。每條失敗路徑都需要在上線前就有明確的使用者導向處置，而不是上線後再補。
對帳很重要。 在轉帳兩端驗證餘額，而不是僅憑 200 回應就假設成功。

雙向的資料衛生

切勿將生產資料放入測試環境。 不要有真實客戶資訊、真實金融資訊或任何 PII。測試環境只應包含為測試而建立的資料。反之亦然：不要將測試使用者、測試資金來源或測試 webhook 載荷帶入生產。測試遺留物進到真實總帳後很難清理，有些甚至無法刪除。

如果你要發布內嵌小工具，同樣的規則適用，另外加上以下幾點：

從生產應用程式的 Installation 分頁重新產生嵌入碼。 片段中內嵌的 apiKey 是和環境綁定的。
以生產的 apiSecret 在伺服器端簽署 patToken。確認該機密是從你的生產機密儲存載入，且權杖產生器沒有仍指向測試環境值。
確認 Origin 與你的生產網域完全一致。
重新檢查交易類型。 Pay-In 與 Payout 的資金流向相反；在對使用者開放前，先用真實小額轉帳驗證方向是否正確。

上線前檢查清單

設定

已建立、設定並啟用的生產應用程式
重新簽發四組憑證並存入生產機密儲存
生產應用程式上不再留有任何測試或 localhost 的 redirect URI
Webhook URL 指向生產端點，並重新勾選事件訂閱
重新勾選的 scopes 與實際 API 呼叫相符
完成 Overview 分頁——名稱、副標、描述、頭像、標誌

程式碼

程式碼庫中沒有硬編碼的主機、金鑰或 redirect URI
環境解析預設為測試環境
同時替換了 OAuth 主機與 GraphQL 主機
冪等等鍵以每次作業為單位產生，而非每個工作階段
Callback 路由具備冪等性並驗證 state
Token 於到期前自動更新，而非等待失敗後才處理

營運

Webhook 端點受監控，且在傳遞或處理失敗時會發出警示
日誌會記錄請求識別碼與冪等等鍵，且絕不記錄機密、PAN 或 PII
已有人負責「使用者無法連線」與「轉帳卡住」的處理手冊
已以最小金額，雙向各跑過一次真實端到端交易，並完成雙方總帳對帳

發佈

先內部使用者，再小規模族群，最後全面開放
可在不進行程式碼部署的情況下停用整合——用功能旗標，不是回滾
已建置並測試重新授權路徑，以應對更新權杖到期或使用者撤銷授權

常見切換失誤

症狀	成因
OAuth 成功，但每個 API 呼叫都被拒絕	GraphQL 主機仍指向測試環境（或反之）
生產 URL 的 `/authorize` 出錯	生產應用程式未註冊該 redirect URI，或 `client_id` 仍為測試值
乾淨的同意後，Token 交換立即失敗	Basic auth 標頭用測試環境的 `client_id`/`client_secret` 組成
小工具在正式網站無法渲染	`Origin` 仍設定為測試或 localhost 網域
小工具能開啟但交易被拒	`patToken` 使用測試環境的 `apiSecret` 簽署
測試環境可用的權限在生產失敗	未在生產應用程式上重新勾選 scopes
生產環境沒有收到 webhooks	未重新指向 URL，或未重新勾選事件訂閱
同意畫面出現佔位應用名稱	從未填寫生產環境的 Overview 分頁
重複轉帳	冪等等鍵重複使用，或在重試時重新生成

後續步驟

設定 OAuth 應用程式

針對你的生產應用程式重新跑一次每個分頁。

授權流程

在生產主機上驗證同意畫面。

更新 access token

在不重新提示的情況下，維持生產連線有效。

API 功能

一切都在真實資金上執行。

建立平台

部署至生產環境

端點對照表

進入各個入口網站

將環境做成變數

在正式環境入口重建你的應用程式

生產環境下哪些行為不同

雙向的資料衛生

小工具（Widget）切換

上線前檢查清單

常見切換失誤

後續步驟

設定 OAuth 應用程式

授權流程

更新 access token

API 功能

​端點對照表

​進入各個入口網站

​將環境做成變數

​在正式環境入口重建你的應用程式

​生產環境下哪些行為不同

​雙向的資料衛生

​小工具（Widget）切換

​上線前檢查清單

​常見切換失誤

​後續步驟

設定 OAuth 應用程式

授權流程

更新 access token

API 功能

端點對照表

進入各個入口網站

將環境做成變數

在正式環境入口重建你的應用程式

生產環境下哪些行為不同

雙向的資料衛生

小工具（Widget）切換

上線前檢查清單

常見切換失誤

後續步驟