Agent Sandbox：使用 RDS MySQL 儲存 API Key

背景資訊

ack-sandbox-manager 支援 Secret 和 MySQL 兩種 API Key 儲存後端，由 keyStorage.mode 配置項控制，取值為 secret（預設）或 mysql。Secret 後端在開發測試和 Key 數量較少的情境下已可滿足需求；如果需要在多租戶或 Key 數量較多的生產環境中使用，可切換為 RDS MySQL，此時資料規模不再受單個 Secret 大小限制。

根據叢集中的 API Key 總數選擇後端：

• 不超過 500 條：可以使用 Secret。

• 501～1000 條：建議規劃遷移至 MySQL。

• 超過 1000 條：應使用 MySQL，避免 Secret 因接近 1 MiB 上限而寫入失敗。

適用範圍

• 已完成 Agent Sandbox容器版 多租戶管理配置，安裝 ack-sandbox-manager（v0.6.7 及以上版本）並啟用 API Key 鑒權。具體操作，請參見多租戶管理。

建立並配置 RDS MySQL 執行個體

API Key 儲存屬於資料量小、以雜湊點查為主的 OLTP（Online Transaction Processing，聯機交易處理）負載。購買 RDS MySQL 執行個體前，可展開下方選型建議規劃執行個體配置。

1. 訪問 RDS 購買頁面，建立 RDS MySQL 執行個體。建議選擇與 ACS 叢集相同的地區和 VPC，並參考上方選型建議配置執行個體。

2. 建立資料庫和帳號。在 RDS 執行個體的資料庫管理和帳號管理頁面中完成以下操作。具體操作，請參見建立帳號。

   1. 建立一個資料庫，例如 e2b。

   2. 建立一個普通資料庫帳號，並記錄帳號名和密碼。

   3. 授予該帳號對目標資料庫的讀寫(DDL+DML)許可權。

3. 配置 IP 白名單。

   sandbox-manager 等控制面組件的訪問流量從控制面交換器發出，因此需要將控制面交換器網段加入 RDS 白名單。

   1. 登入Agent Sandbox控制台，在左側導覽列選擇容器版 > 沙箱实例，確認目的地組群。後續操作需在容器計算服務控制台完成。

   2. 登入容器計算服務控制台，進入目的地組群的基本資料頁面。

   3. 在網路區塊，單擊控制面交換器右側的編輯，複製所有勾選狀態的交換器的CIDR（網段）。

   4. 登入 RDS 管理主控台，進入目標執行個體的白名單與安全性群組頁面。

   5. 修改 default 白名單分組，將控制面交換器的 IPv4 網段添加到組內白名單。

4. 在 RDS 執行個體的資料庫連接頁面中，記錄內網地址和內網連接埠，例如：

   rm-******************.mysql.rds.aliyuncs.com:3306

5. 手動初始化表結構。執行 OpenKruise 社區提供的 mysql-schema.sql 指令碼初始化資料庫表結構：

   mysql -h <RDS內網地址> \
     -P <連接埠> \
     -u <資料庫帳號> \
     -p \
     <資料庫名> < mysql-schema.sql

   該指令碼會建立 teams 和 team_api_keys 表，並初始化內建的 admin Team。admin API Key 的雜湊無需遷移，ack-sandbox-manager 啟動時會根據當前 hashPepper 自動計算並寫入 team_api_keys。

配置 MySQL 儲存後端

1. 登入Agent Sandbox控制台，在左側導覽列選擇容器版 > 沙箱实例，確認目的地組群。後續操作需在容器計算服務控制台完成。

2. 登入容器計算服務控制台，進入目的地組群。

3. 在組件管理頁面找到 ack-sandbox-manager，單擊配置。

4. 配置以下參數：

   配置項	配置值或說明
   keyStorage.mode	設定為 mysql。
   keyStorage.mysql.dsn	MySQL 資料來源名稱（Data Source Name，DSN），描述串連目標資料庫的帳號、密碼、地址、連接埠及串連參數，格式見下方樣本。
   keyStorage.mysql.hashPepper	用於計算 API Key 雜湊的長期密鑰。

5. 按以下格式填寫 DSN：

   <帳號>:<密碼>@tcp(<RDS內網地址>:<連接埠>)/<資料庫名>?charset=utf8mb4&parseTime=true&loc=Local

   樣本：

   e2b_user:********@tcp(rm-******************.mysql.rds.aliyuncs.com:3306)/e2b?charset=utf8mb4&parseTime=true&loc=Local

   使用以下命令產生一個 32 位元組（256 bit）的隨機字串作為 hashPepper。

   openssl rand -hex 32

   命令輸出為 64 個十六進位字元，直接作為 keyStorage.mysql.hashPepper 的取值。

   重要

   請長期、安全地儲存 hashPepper，不要將其與資料庫密碼設定為相同的值。更換該值後，現有租戶 API Key 將無法通過鑒權，需要重新簽發。

6. 儲存配置。ack-sandbox-manager 將自動重啟並串連 RDS MySQL。

   當 keyStorage.mode 設定為 mysql 時，如果未配置 DSN 或 hashPepper，組件將啟動失敗。

驗證配置

1. 確認 ack-sandbox-manager Pod 正常運行：

   kubectl get pods -n sandbox-system -l component=sandbox-manager

   預期輸出：

   NAME                             READY   STATUS    RESTARTS   AGE
   sandbox-manager-79b7449778-xxx   2/2     Running   0          78m
   sandbox-manager-79b7449778-yyy   2/2     Running   0          79m
   sandbox-manager-79b7449778-zzz   2/2     Running   0          78m

2. 建立、查詢並刪除一個臨時 API Key，以驗證 MySQL 後端可正常讀寫。執行前請根據實際環境替換以下變數：

   • BASE_URL：ack-sandbox-gateway 對外訪問地址。

   • ADMIN_KEY：ack-sandbox-manager 配置的 admin API Key。

   以下指令碼依賴 jq（命令列 JSON 處理器）解析響應，執行前請確認本地已安裝。

   BASE_URL="https://api.your.domain.com"
   ADMIN_KEY="your-admin-key"
   
   TEST_KEY_ID=$(
     curl -fsS -X POST \
       -H "X-API-KEY: ${ADMIN_KEY}" \
       -H "Content-Type: application/json" \
       -d '{"name":"mysql-storage-verification"}' \
       "${BASE_URL}/api-keys" |
       jq -r '.id'
   )
   echo "Created: ${TEST_KEY_ID}"
   
   curl -fsS \
     -H "X-API-KEY: ${ADMIN_KEY}" \
     "${BASE_URL}/api-keys" |
     jq -e --arg id "${TEST_KEY_ID}" \
       'any(.[]; .id == $id)' >/dev/null && echo "Query OK"
   
   curl -fsS -X DELETE \
     -H "X-API-KEY: ${ADMIN_KEY}" \
     "${BASE_URL}/api-keys/${TEST_KEY_ID}" && echo "Deleted: ${TEST_KEY_ID}"

   預期輸出：

   Created: 4f2ab49a-aced-4830-b5da-5d382xxxxxxx
   Query OK
   Deleted: 4f2ab49a-aced-4830-b5da-5d382xxxxxxx

遷移已有 API Key（可選）

切換到 MySQL 後端後，如果原 Secret 後端中已有 API Key 需要在新後端繼續使用，可以使用 OpenKruise 社區提供的 migrate_secret_keys_to_mysql.py 指令碼產生 MySQL 遷移 SQL。遷移指令碼會：

• 通過 kubectl 讀取 e2b-key-store Secret。

• 使用與 keyStorage.mysql.hashPepper 相同的值計算 API Key 的 HMAC-SHA256 雜湊。

• 產生建表 DDL，以及 Team 和 API Key 的 Upsert 語句。

• 保留原有 Team、Key 名稱、建立資訊和配額配置。

指令碼僅依賴Python 3標準庫和 kubectl。

1. 校正 Secret 資料：

   python3 migrate_secret_keys_to_mysql.py \
     --namespace sandbox-system \
     --dry-run

   該命令會解析 Secret 中的所有條目，校正 id、name、key 等欄位的合法性，檢查 Team 中繼資料是否一致以及原始 Key 是否唯一，任何一項不通過都會中止遷移，避免產生不完整的 SQL。

2. 通過隱藏輸入設定 hashPepper（值必須與已配置的 keyStorage.mysql.hashPepper 完全一致），並產生遷移 SQL：

   read -rsp "請輸入 hashPepper: " E2B_KEY_HASH_PEPPER
   echo
   export E2B_KEY_HASH_PEPPER
   
   python3 migrate_secret_keys_to_mysql.py \
     --namespace sandbox-system \
     --output e2b_key_migration.sql

3. 將遷移 SQL 匯入 RDS MySQL：

   mysql -h <RDS內網地址> \
     -P <連接埠> \
     -u <資料庫帳號> \
     -p \
     <資料庫名> < e2b_key_migration.sql

4. 清理環境變數和遷移檔案：

   unset E2B_KEY_HASH_PEPPER
   rm -f e2b_key_migration.sql