部署到生产环境

上线是一次配置切换，而不是重写。你的查询、变更和流程在两个环境中是相同的。变化在于你调用的主机以及你使用的凭证——而且两者都会完全不同。

预发布环境的任何内容都不会继承到生产环境。应用、API 密钥、客户端密钥、重定向 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`
令牌交换	`https://uni.staging.fluzapp.com/token/exchange`	`https://fluz.app/token/exchange`
刷新令牌	`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 密钥。

将环境做成变量

如果你的代码库里还有任何主机、密钥或重定向 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 上再次完成创建 OAuth 应用和配置 OAuth 应用。然后逐项检查以下内容——这些都是人们常忘记的：

重新签发所有凭证

生产环境的 client_id、client_secret、apiKey 和 apiSecret 全部是新值。将它们放入你的生产机密存储中。确认生产配置中没有残留任何预发布值。

在生产主机上重新注册重定向 URI

使用生产回调 URL，且必须是其精确的规范形式。然后移除任何 localhost 或预发布 URI——生产应用不应接受重定向到开发者笔记本电脑。

重新指向 webhook URL

指向可公开访问、受监控且具备告警的生产端点。逐个事件重新订阅；它们不会被复制。如果你在预发布中使用了全量捕获 URL，请决定是否真的要在生产中也这样做。

将 Origin 设为你的生产域名

对于嵌入式小部件，这必须与实际承载页面的域名匹配，否则小部件不会加载。

重新选择你的作用域

作用域选择不会转移。走查你的集成所调用的每个 API，并确认每一个所需的作用域都在生产应用的“Permissions”选项卡上勾选。缺失的作用域会被静默丢弃，不会报错。

完成 Overview 选项卡

名称、副标题、描述、头像和标志是实际用户在真实的同意屏上看到的，他们需要据此决定是否授予你访问他们资金的权限。占位文案若不处理就会进入生产。

确认你的应用状态

控制台中的应用带有状态——处于审核中的应用尚不能供你的客户使用。在对外发布前，确认你的生产应用已激活。

生产环境中的行为差异

预发布环境在不涉及真实资金的情况下镜像生产环境的能力与交易流程。这覆盖了大部分，但并非全部。

	预发布	生产
资金	模拟	真实。转账在你方不可逆
KYC	具有可预测结果的测试路径	基于真实身份数据的实际验证，存在真实拒绝
卡授权	模拟	实时网络授权与真实拒绝
清算时效	立即或模拟	真实银行时间线
资金来源	测试银行卡与账户	真实卡和通过 Plaid 关联的账户
失败模式	你选择测试的那些	资金不足、卡过期、网络拒绝、验证失败

有三点后果值得提前规划：

幂等性不再是可选项。 每个动账调用都需要唯一的 idempotencyKey，小部件令牌需要唯一的 jti。在预发布中，重复只是麻烦；在生产中，它是重复付款。参见 Idempotency。
你的错误处理会被真正触发。 测试用户不会因为资金不足被拒，也不会以你未编排的方式未通过 KYC。每条失败路径都需要在上线前，而不是上线后，就定义好面向用户的结果。
对账很重要。 验证转账双方的余额，而不是从一个 200 响应就假定成功。

双向的数据卫生

切勿将生产数据放入预发布环境。 不要包含真实客户信息、真实金融信息或 PII。预发布用于专门为测试创建的数据。反之亦然：不要把测试用户、测试资金来源或测试 webhook 负载带入生产。测试产物落入真实账本后很难清理，有些甚至无法删除。

小部件割接

如果你要发布嵌入式小部件，除遵循相同规则外，还需注意：

从生产应用的 Installation 选项卡重新生成嵌入代码。 片段中内置的 apiKey 与环境相关。
使用你的生产 apiSecret 在服务端签发 patToken。确认该密钥从生产机密存储加载，且令牌生成器没有仍指向预发布值。
确认 Origin 与你的生产域名完全匹配。
重新检查交易类型。 Pay-In 和 Payout 的资金方向相反；在向用户开放前，用一次真实的小额转账验证方向是否正确。

上线前检查清单

配置

生产应用已创建、已配置并处于激活状态
四类凭证均已重新签发并存入生产机密存储
生产应用上不再保留任何预发布或 localhost 重定向 URI
Webhook URL 指向生产端点，事件订阅已重新选择
作用域已重新选择并与实际 API 调用匹配
完成 Overview 选项卡——名称、副标题、描述、头像、标志

代码

代码库内不再硬编码任何主机、密钥或重定向 URI
环境解析默认指向预发布
同时切换了 OAuth 主机与 GraphQL 主机
幂等键按操作生成，而非按会话
回调路由具备幂等性并校验 state
令牌刷新在过期前执行，而非等待失败后再处理

运维

Webhook 端点已被监控，对投递或处理失败具备告警
日志捕获请求标识符与幂等键，且绝不记录机密、PAN 或 PII
明确负责人维护“用户无法连接”和“转账卡住”的运行手册
已用最小可能金额，双向跑通一次真实端到端交易，并核对了双方账本

发布

先内测给内部用户，再小范围试点，最后全面开放
可在不发版的情况下禁用集成——用功能开关，而不是回滚
构建并测试了重新授权路径，应对刷新令牌过期或用户撤销

常见割接失败

症状	原因
OAuth 成功，但每个 API 调用都被拒绝	GraphQL 主机仍指向预发布（或反之）
生产 URL 上的 `/authorize` 报错	生产应用的重定向 URI 未注册，或 `client_id` 仍是预发布值
在干净同意后立刻令牌交换失败	基本认证头由预发布的 `client_id`/`client_secret` 构建
小部件无法在生产站点渲染	`Origin` 仍设置为预发布或 localhost 域名
小部件打开但交易被拒绝	`patToken` 使用预发布的 `apiSecret` 签发
预发布可用的权限在生产失败	未在生产应用上重新选择作用域
生产环境没有收到 webhook	URL 未重新指向，或事件订阅未重新选择
同意屏显示占位应用名称	从未填写生产环境的 Overview 选项卡
发生重复转账	幂等键被复用或在重试时重新生成

接下来

配置 OAuth 应用

针对你的生产应用重新跑一遍每个选项卡。

授权流程

在生产主机上验证同意屏。

刷新访问令牌

在不重新提示的情况下保持生产连接可用。

API 功能

一切都已在真实资金环境中运行。

​端点映射

​访问各个门户

​将环境做成变量

​在线上门户重新创建你的应用

​生产环境中的行为差异

​双向的数据卫生

​小部件割接

​上线前检查清单

​常见割接失败

​接下来

配置 OAuth 应用

授权流程

刷新访问令牌

API 功能

端点映射

访问各个门户

将环境做成变量

在线上门户重新创建你的应用

生产环境中的行为差异

双向的数据卫生

小部件割接

上线前检查清单

常见割接失败

接下来