# 把憑據留在服務端：業務系統接入平臺的運行時模型

模塊憑據、Launch Grant、短期實例 Token、成員收斂、Scope 失敗關閉與冪等歸屬：遠端業務系統接入平臺時，服務端要守住的邊界。

> Runlume 提供平臺能力、獨立業務應用與專業服務，支持按需組合。功能、額度與交付範圍由所選套餐或服務約定確定；業務應用可獨立選用，跨應用協作遵循接入配置與授權邊界。

原始頁面: https://runlume.app/zh-hant/blog/platform-integration-runtime-model

開發者指南 · 應用接入 / 憑據與會話 / 接口契約

發佈：2026-09-19 · 作者：Runlume 團隊

遠端業務系統接入平臺時，容易出問題的往往不是接口調用本身，而是“誰持有憑據、憑據多久失效、成員被撤銷後多久生效”。這三件事決定了系統能不能長期穩定運行。下面是我們在這條鏈路上守住的做法和邊界。

## 憑據分兩級，長期那一級不出服務端

平臺側有兩類身份。模塊服務身份是長期憑據，只在業務系統服務端持有，用來交換 Launch Grant（`POST /integration/v1/sso/launch-grants/exchange`）和申請實例服務 Token（`POST /integration/v1/service-tokens`）；實例服務 Token 則是**最長五分鐘、Audience 固定、Scope 已按本次請求收窄**的短期憑據，響應帶 `no-store`。

因此瀏覽器永遠拿不到模塊憑據：前端只把用戶帶來的 Launch Code 交給自己的後端，其餘交換都在服務端完成。SDK 對短期 Token 的處理是按“實例 + 本次請求的 Scope 集合”緩存，最長 300 秒、沒有 Refresh，剩餘壽命不足安全窗口時重新申請，併發調用只觸發一次，且不跨實例複用。

## Launch 是一次性交換，換來的是本地會話

用戶從平臺進入業務系統時，帶的是 Launch Code，不是長期憑據。後端用模塊服務身份交換並消費 Grant，隨後建立業務系統自己的本地會話；會話裡只放派生身份，不放平臺 Token、Launch Code、Client Secret 或完整 Claims。

交換與會話校驗都要驗籤：用平臺運行時 JWKS 校驗簽名算法、Issuer、Audience、有效期、`token_use`、Account 與 AppInstance 以及 Scope，公鑰來源禁止重定向並限制響應體大小。這裡有一個容易混淆的地方：登錄說明頁上的“聯機正常”只證明後端能解析平臺公鑰，不代表用戶已登錄，也不代表 Launch 鏈路可用——三件事要分開描述。

## 成員被撤銷後，本地會話要能收斂

平臺會話有效，不等於本地會話可以一直用下去。長期會話期間，成員被移出實例、角色發生變化或實例被停用，都應在有限時間內反映到業務系統。做法是用實例服務身份批量校驗（`POST /integration/v1/session-checks`）：`active` 為真要求實例、實例成員、Account 與 Account 成員同時有效；非成員與不存在的用戶同樣返回 `active=false`，不洩漏成員是否存在。業務系統按自己聲明的校驗窗口收斂，實踐中寫請求的窗口可以比讀請求更短。

## Scope 不夠就在本地失敗，不要發出請求

每個運行時請求都帶 Scope。SDK 只在平臺實際授予的 Scope 覆蓋本次請求時才返回可用憑據，否則在本地失敗，不發業務請求。這條規則的意義在於把“平臺沒授權”和“平臺調用失敗”分開：前者是配置問題，應當立刻可見，而不是變成一串難以定位的上游錯誤。

## 冪等與重試歸調用方

SDK 不自動重試任何請求。寫操作必須由調用方提供穩定的冪等鍵，請求失敗也不重發——因為“結果未知”和“失敗”是兩種狀態，只有業務系統自己知道該補發、查詢還是提示用戶。錯誤方面，平臺的 Problem Details 會映射到穩定的錯誤類別（未認證、無權限、衝突、限流、服務端錯誤等）並標註是否可重試；憑據與響應正文不會進入日誌或錯誤序列化。

## 兩份製品，兩條獲取路徑

兩組 SDK 的可獲取性不同，接入前先確認自己屬於哪一類。TypeScript / Node 側是公共 npm 上的 `@td-runlume/platform-integration-sdk`，Apache-2.0，用於服務端調用。Java 側座標是 `app.runlume.platform:platform-integration-sdk-java`，由平臺的 Nexus 製品庫提供、**不在 Maven Central**，且只能憑平臺授予的憑據與許可使用，不要重新分發製品；Java 側通常配合 Spring Boot Starter 使用，SDK 組件與本地會話有效性管線由 Starter 裝配，業務系統只提供會話邊界與工作區讀取兩個擴展點。

接口路徑、Scope 名稱與可用能力以簽約時的契約和平臺文檔為準。本文只說明接入時服務端要守住的邊界；平臺提供的能力範圍可以從[平臺能力](/zh-hant/platform#capability-identity)開始瞭解。

## 相關頁面

- [平臺能力](https://runlume.app/zh-hant/platform)
- [業務應用](https://runlume.app/zh-hant/apps)
- [開發者](https://runlume.app/zh-hant/developers)
- [關於 Runlume](https://runlume.app/zh-hant/about)