環境變數

環境變數是範本用來設定其內部工作負載的方式：Hugging Face 權杖、模型名稱、日誌層級。請在範本表單的 環境變數 區段新增它們，每一列一組鍵與值，右邊有一個機密開關。

設定方式

項目	規則
鍵	最多 256 個字元。鍵留白的列在儲存時會被捨棄。
值	任何字串，最多 4,096 個字元。留白會把該項目存成未設定。一個範本，以及一次部署的覆寫，各自最多 100 項。
機密	對擁有組織以外的任何人遮蔽這個值。

沒有值的項目根本不會注入容器。這讓它很適合當佔位項目：把 HF_TOKEN 宣告為沒有值的機密項目，範本就能說明租用者必須提供什麼，而不會把權杖送給每一個讀到它的人。

透過 API 時，env 在 POST /v1/templates 與 PATCH /v1/templates/{id} 上是一個物件清單：

{
  "env": [
    { "key": "MODEL_ID", "value": "meta-llama/Llama-3-8B", "secret": false },
    { "key": "HF_TOKEN", "value": null, "secret": true }
  ]
}

在 PATCH 中送出 env 會取代整份清單。沒有逐鍵更新的做法。

機密值遮蔽

機密值只會回傳給擁有該範本的組織。其他所有人 —— 包括瀏覽你公開範本的人，也包括精選 system 範本的讀者 —— 拿到的是 value: null，而 secret 旗標保持不變。主控台會顯示鍵，並以隱藏的佔位符取代值。

遮蔽是跟著資料走，而不是跟著端點走：GET /v1/templates、GET /v1/templates/{id} 與 GET /v1/templates/by-hash/{hash_id} 全都會套用。

有兩個值得知道的後果：

複製一個不屬於你組織的範本時，副本中的每個機密值都會被清空。你從來就沒有讀取它們的權限，而成為副本的擁有者也不該改變這件事。複製你自己的範本則會保留這些值。
把既有的值標示為機密，只會讓它從此之後被隱藏，並不會收回已經讀過它的人手上的資訊。請改為輪替該憑證。

部署時的租用者覆寫

部署時可以透過 POST /v1/instances 上的 env_overrides 新增或取代環境變數項目：

{
  "offer_id": "…",
  "template_id": "…",
  "disk_gb": 100,
  "env_overrides": [{ "key": "HF_TOKEN", "value": "hf_…", "secret": true }]
}

系統會先套用範本的環境變數，再套用覆寫值，依鍵比對 —— 覆寫值勝出。任一邊的值為 null 的項目會被捨棄，而不是以空字串注入。這就是你不必編輯範本就能填入機密佔位項目的方法，也讓你的權杖不會出現在分享出去的配方裡。

平台覆蓋層永遠優先

範本環境變數與租用者覆寫合併之後，Superheat 會套用一層平台覆蓋層，而且這層是最後套用的。覆蓋層裡的鍵無法被範本的值或 env_overrides 項目蓋過 —— 你設定的內容會被無聲地取代掉。

變數	何時設定	內容
`CONTAINER_ID`	一律設定	工作負載識別碼
`GPU_COUNT`	一律設定	指派給這個執行個體的 GPU 數量
`SUPERHEAT_TCP_PORT_<n>`	每個已發布的 TCP 連接埠各一個	容器連接埠 `<n>` 對應到的主機連接埠
`PUBLIC_KEY`	`ssh`、`jupyter`，且你在部署時附加了 SSH 金鑰	你的 SSH 公開金鑰
`SUPERHEAT_SSH_PUBLIC_KEYS`	`ssh`、`jupyter`，且你在部署時附加了 SSH 金鑰	同樣的金鑰內容，以換行分隔的形式
`SUPERHEAT_ONSTART`	`ssh`、`jupyter`，且有設定時	啟動時指令碼的內容
`OPEN_BUTTON_PORT`	`ssh`、`jupyter`，且有連接埠標籤為 `open` 時	開啟按鈕的目標連接埠
`JUPYTER_TOKEN`	`jupyter`	平台產生的存取權杖
`SUPERHEAT_ACCESS_TOKEN`	範本在某個連接埠上要求存取權杖，或引用了它	同一個存取權杖
`SUPERHEAT_ACCESS_PORTS`	範本有宣告為 `auth: proxy` 的連接埠	存取代理守護的容器連接埠
任何範本值剛好是 `${SUPERHEAT_ACCESS_TOKEN}` 的鍵	對這樣的鍵永遠適用	存取權杖，於部署時替換進去
`JUPYTER_PORT`	`jupyter`	`8080`
`JUPYTER_DIR`	`jupyter`	範本的 Jupyter 工作目錄
`JUPYTER_LAB`	`jupyter`	`true` 使用 JupyterLab，`false` 使用傳統 notebook

所以在範本上設定 JUPYTER_TOKEN 沒有任何作用：權杖由平台自己產生，用它組出開啟按鈕的網址，並在執行個體上以 access_token 顯示給你的組織。帶著存取權杖的變數也是一樣 —— 例如範本值為 ${SUPERHEAT_ACCESS_TOKEN} 的 API_KEY —— 租用者的覆寫蓋不掉它。設定 GPU_COUNT 同樣沒有作用 —— 它反映的是你實際租到的切片，如果租用者能編輯它，信任這個值的程式就會被騙。

不要用覆蓋層的鍵當作範本變數的名稱

覆寫是無聲進行的。如果你的程式讀取 GPU_COUNT 並期待拿到自己設定的值，它拿到的會是平台的值，而且任何地方都不會出現錯誤。

你在容器內看到的內容

在衍生自基礎映像檔的映像檔上，sshd 與 Jupyter 啟動的登入 shell 不會繼承容器程序的環境，所以進入點會把環境寫入 /etc/environment 與 /etc/profile.d/superheat-env.sh。當你以 SSH 連進去時，你的變數，加上 CONTAINER_ID、GPU_COUNT 與 SUPERHEAT_TCP_PORT_* 這些項目，全都在那裡。

佈建用的機密值刻意被排除在這兩個檔案之外：SUPERHEAT_ONSTART、JUPYTER_TOKEN、SUPERHEAT_ACCESS_TOKEN、PUBLIC_KEY 與 SUPERHEAT_SSH_PUBLIC_KEYS 由進入點取用後就不會再匯出。在 SSH 工作階段中 echo $JUPYTER_TOKEN 什麼也拿不到，這是設計如此。需要權杖時，請從主控台的連線分頁複製。

設定方式​

機密值遮蔽​

部署時的租用者覆寫​

平台覆蓋層永遠優先​

你在容器內看到的內容​

設定方式

機密值遮蔽

部署時的租用者覆寫

平台覆蓋層永遠優先

你在容器內看到的內容