命令列工具¶

使用 cscc-cli 登入平台、提交映像檔建置、串流建置日誌，並管理自己的 API token。

存取權限： 所有已登入使用者。

登入¶

cscc-cli 不再 fallback 到 Kubernetes 內部 service 名稱。新機器首次使用時，請用 --api-url 或 CSCC_API_URL 明確指定公開 API URL。URL 可包含 /api/v1，CLI 會自動正規化。

cscc-cli login --api-url https://api.cscc.nthu.edu.tw --username alice

CLI 會提示您輸入密碼，並呼叫 /api/v1/cli/login。此流程不使用 CAPTCHA，也不需要 X-API-Key。

登入成功後，CLI 會把 cscc_... 使用者 API token 存在本機設定檔，權限為 0600。後端只保存 token 的 SHA-256 雜湊，因此明文 token 只會在建立時顯示一次。

可選擇 token 名稱：

cscc-cli login --api-url https://api.cscc.nthu.edu.tw --username alice --name workstation

匯入由儀表板建立的 token¶

您也可以在儀表板的 設定 → API Key & CLI 建立 API token，然後匯入 cscc-cli：

cscc-cli login --api-url https://api.cscc.nthu.edu.tw --token cscc_...

CLI 會先用 /api/v1/auth/status 驗證 token，成功後才存入本機設定。這適合已經登入瀏覽器、不想在終端機再次輸入密碼的情境。

無狀態 token 覆寫¶

自動化腳本可使用 CSCC_API_TOKEN，不必儲存本機設定：

CSCC_API_URL=https://api.cscc.nthu.edu.tw CSCC_API_TOKEN=cscc_... cscc-cli whoami

CSCC_DEV_TOKEN 仍作為舊版相容 alias，但新的腳本應改用 CSCC_API_TOKEN。

TLS / 內部 CA¶

官方 cscc-cli release 已內建平台內部 root CA，因此大多數使用者不需要另外下載憑證。若平台 root CA 輪替，請先下載新發布的 CLI binary 再重新連線。

手動 CA 設定仍保留給自訂 CLI build、緊急 CA 輪替期間，以及 TLS 除錯：

環境變數	說明
`CSCC_API_URL`	API base URL，例如 `https://api.cscc.nthu.edu.tw/api/v1`
`CSCC_API_TOKEN`	選用的無狀態 `cscc_...` token 覆寫
`CSCC_API_CA_CERT_PATH`	一個或多個 PEM 檔路徑，可用 `,` 或 `;` 分隔
`CSCC_API_TLS_SERVER_NAME`	選用 TLS SNI 名稱；未設定時使用 config fallback
`SSL_CERT_FILE`	包含內部 root CA 的 PEM 檔路徑
`REQUESTS_CA_BUNDLE`	另一個 PEM bundle 路徑環境變數

範例：

CSCC_API_CA_CERT_PATH=/Users/me/platform-internal-root-ca.pem \
  cscc-cli login --api-url https://api.cscc.nthu.edu.tw --username alice

進階：從設定頁下載並信任 CLI CA¶

開啟 https://dashboard.cscc.nthu.edu.tw/settings，進入 API Key & CLI。

只有在使用自訂 CLI build、測試 CA 輪替或除錯 TLS trust 時才需要這個流程。官方 CLI 已內建平台 CA。

點擊 Download CLI CA，儲存 platform-internal-root-ca.pem。
執行儀表板產生的安裝指令。
用手動 CA override 驗證 CLI 連線：

CSCC_API_CA_CERT_PATH=~/.config/cscc-cli/platform-internal-root-ca.pem \
  CSCC_API_URL=https://api.cscc.nthu.edu.tw \
  cscc-cli whoami

若不想每次設定環境變數，可將 platform-internal-root-ca.pem 或 ca.crt 放在 ~/.config/cscc-cli/；CLI 會在檢查明確 env 與 saved config path 後自動偵測。

確認身分¶

cscc-cli whoami

此指令會驗證已儲存的 token，並印出目前使用者與角色資訊。角色變更會立即生效，因為每次請求都會由後端 RBAC/Casbin 狀態重新解析授權。

建置映像檔¶

Upload 模式為預設，接受目錄、.tar.gz 或 .zip：

cscc-cli build --project <project-id> --name trainer --tag v1.0.1 .
cscc-cli build --project <project-id> --name trainer ./context.tar.gz

若來源是目錄，CLI 會打包成 .tar.gz build context；目錄或上傳的 archive 根目錄必須包含 Dockerfile。

Dockerfile-only 模式與儀表板貼上 Dockerfile 的流程一致，會呼叫 /api/v1/images/build/dockerfile：

cscc-cli build --source dockerfile \
  --project <project-id> \
  --name trainer \
  --tag v1.0.1 \
  --dockerfile ./Dockerfile

cat Dockerfile | cscc-cli build --source dockerfile \
  --project <project-id> \
  --name trainer \
  --dockerfile -

Storage 模式會從可讀的平台 storage path 建置，並呼叫 /api/v1/images/build/from-storage：

cscc-cli build --source storage \
  --project <project-id> \
  --name trainer \
  --storage-source personal \
  --storage-path apps/trainer

cscc-cli build --source storage \
  --project <project-id> \
  --name trainer \
  --storage-source project_storage \
  --storage-id <storage-id> \
  --storage-path apps/trainer

常用選項：

選項	說明
`--project`	擁有此映像檔建置的專案 ID
`--name`	簡短映像檿名稱，例如 `trainer-api`
`--tag`	選用映像檔 tag；省略時使用平台預設值
`--source`	`upload`、`dockerfile` 或 `storage`
`--dockerfile`	`--source dockerfile` 時的 Dockerfile 路徑，或用 `-` 讀 stdin
`--storage-source`	`--source storage` 時使用 `personal` 或 `project_storage`
`--storage-path`	所選 storage 內的來源路徑
`--storage-id`	`project_storage` 建置使用的專案 storage ID
`--cpu-cores`	選用建置 CPU request
`--memory-gb`	選用建置記憶體 request，單位 GiB
`--timeout-minutes`	選用建置 timeout 覆寫
`--follow=false`	只提交建置，不串流日誌

提交後，--follow=true 會輪詢直到建置日誌可用，串流 /api/v1/images/build/:jobName/logs?follow=true，並在 backend 回報 completed、failed 或 deleted 時停止且印出狀態。

CLI 會依序從登入/匯入時的 --api-url、CSCC_API_URL、已儲存 config 取得 API endpoint；沒有內部 service fallback。Production 請使用 gateway API host：

export CSCC_API_URL=https://api.cscc.nthu.edu.tw

建置請求與日誌串流會使用 cscc-cli login 建立的使用者 token：

Authorization: Bearer cscc_...

CLI 建置不需要 CSCC_API_KEY、PLATFORM_API_KEY 或 X-API-Key header。專案必須啟用 Image Build Permission，且您的專案角色必須允許建置。

Token 管理¶

列出有效 API token：

cscc-cli tokens list

用 token ID 撤銷 token：

cscc-cli tokens revoke <token-id>

登出目前機器：

cscc-cli logout

登出會先呼叫 DELETE /api/v1/me/api-tokens/current 撤銷目前使用的 token，接著保留 TLS 設定並清除本機 token 欄位，讓手動憑證 override 可以重複使用。

預設值¶

設定	預設值	說明
`USER_API_TOKEN_TTL_HOURS`	`2160`	Token 有效時間，以小時計算（90 天）
`USER_API_TOKEN_MAX_ACTIVE`	`20`	每位使用者最多可同時持有的有效 token 數
`CLI_LOGIN_MAX_ATTEMPTS`	`5`	登入失敗幾次後鎖定
`CLI_LOGIN_LOCKOUT_SECONDS`	`900`	鎖定時間，單位為秒