Skip to Content
Quasar应用与密钥管理

应用与密钥管理 (Apps & Keys)

与 Quasar 的每一次系统集成均以 应用 (App) 为边界起点：应用独立拥有所有已同步的链上交易、Webhook 终端配置和 API 凭据。在 Quasar Cloud 中，每个组织最多可创建 30 个应用；开源社区版 (Community Edition) 则提供统一的单租户工作区。

🛠️ 创建与配置应用

登录 Quasar 开发者控制台 （或私有节点的 /admin 后台），进入 Apps 面板点击新建。选择对应的运行环境 (environment)：

  • Live (生产环境)：承接真实主网业务流量，API 密钥前缀为 sk_live_ 与 pk_live_。
  • Test (测试环境)：用于日常开发调试与测试网集成，密钥前缀为 sk_test_ 与 pk_test_，同步交易所消耗的配额费率仅为生产环境的一半（详情参见 配额与速率限制）。

两种环境在交易状态机计算、确定性终态确认和 Webhook 调度逻辑上完全一致。

🔑 Secret Key 与 Public Key 的职责边界

密钥类型识别前缀HTTP 请求头接口访问权限
Secret key (服务端私钥)sk_live_, sk_test_x-tuwa-secret-key全量接口：同步链上交易、Webhook 回调订阅、查询全局历史记录
Public key (前端公钥)pk_live_, pk_test_x-tuwa-public-key严格只读，仅允许不涉及用户隐私的连通性探测接口（如 GET /v1/engine/test-ping）
  • 务必将 Secret Key 保留在后端安全环境（环境变量、Next.js Server Action、API Route 或微服务配置中心）。任何持有该密钥的客户端均可向您的应用注入交易并消耗账户配额。官方 @tuwaio/quasar-sdk 会自动封装鉴权头：
src/lib/quasar.ts
import { Quasar } from '@tuwaio/quasar-sdk'; export const quasar = new Quasar({ secretKey: process.env.QUASAR_SECRET_KEY ?? '' });
  • Public Key 具备严格防泄露保护，无法读取任何用户的链上数据：携带 Public Key 发起的 POST 写入或历史记录读取均会被 API 返回 403 Forbidden 拦截。请务必在自有后端使用 Secret Key 查询数据，并严格比对 SIWX 会话仅向用户呈现其已签名的钱包历史。
  • 加密存储与哈希检索：Quasar 对 Secret Key 进行端到端加密存储，并通过 SHA-256 哈希进行极速索引匹配。在控制台明文查看密钥必须通过账户密码及 2FA 双重身份验证。
  • 密钥紧急轮换 (Key Rolling)：在应用设置中点击轮换密钥将立即废弃旧密钥并派发新凭证。请在轮换后第一时间更新生产服务配置。

🛡️ 应用访问策略与安全防御

防御配置防护机制与阻断行为
Active (激活状态)一旦禁用该应用，所有携带该应用密钥的 API 请求将立即被拒绝并返回 403 Forbidden。
IP allowlist (IP 白名单)启用后仅接收来自指定白名单 IP 地址的 API 调用，未授权来源直接阻断并返回 403。
Domain allowlist (域名白名单)配置后请求必须携带合法匹配的 Origin 或 Referer 头部。标准后端环境使用 @tuwaio/quasar-sdk 发起的请求不包含此类浏览器头部，因此纯后端应用请保持该列表为空。

此外，应用设置中还用于登记您的链端 RPC 节点及第三方服务商凭据 (Alchemy, QuickNode, Pimlico)。Quasar 实施强加密存储，并在建立连接时严格拦截内网及本地回环 (loopback) 目标。

在 Quasar Cloud 中，必须先配置 RPC 提供商再同步交易：为您启用的链配置专用 RPC 节点或填入 Alchemy/QuickNode Key。云端引擎完全通过应用自身配置的节点拉取确认；ERC-4337 需要 Pimlico Bundler 凭证。如未配置链端提供商，API 将以 422 Unprocessable Entity 拒绝同步且不存库。自建社区版支持运营商全局兜底 RPC 及 Safe 多签同步。

🏢 应用间多租户严格隔离

Quasar 在每个进入 API 网关的请求中直接反解应用标识，所有的读取与写入在数据库层面均被 appId 严格限制：同一组织内不同应用的交易历史绝对物理隔离，互不可见。Webhook 投递在分发时也严格比对归属组织与应用，杜绝越权风险。

最后更新于
概览配额与速率限制