容器執行合約
網頁服務映像檔要符合的規則、平台設定的變數,以及新版本上線後,前一個版本還會跑多久。平台能自動調整的地方會調整,並在版本頁留下提示。
規則#
| 項目 | 要求 | 不符合時 |
|---|---|---|
| 啟動指令 | 要有 CMD 或 ENTRYPOINT。 | 版本被拒收。 |
| 通訊埠 | 在 $PORT 提供 HTTP。 | 依「設定 → EXPOSE → 8080」的順序決定,見 專案設定。 |
| 平台 | linux/amd64。 | Agent Lab 一律為這個平台建置。 |
| 使用者 | 建議設定非 root 的 USER。 | 以 root 執行或沒設定時,改用 uid 10001、群組 0 執行;指定映像檔裡沒有的使用者,版本被拒收。 |
| 檔案系統 | 除了 /tmp 都是唯讀。 | 寫入其他路徑會失敗。 |
| 雲端憑證 | 平台不提供。 | 需要存取外部服務時,改用專案的機敏值。 |
映像檔改用 uid 10001 執行時,它要讀的檔案必須讓群組 0 可以讀。
提示#
平台調整過的地方,會在版本頁顯示提示。AI 工具從部署狀態也讀得到同樣的代碼。
| 代碼 | 意思 | 要做什麼 |
|---|---|---|
imageUserForced | 映像檔以 root 執行,改用 uid 10001 執行。 | 不用處理。想消除提示,就在 Dockerfile 設定非 root 的 USER。 |
imagePortFromExpose | 服務監聽映像檔 EXPOSE 的那一個通訊埠。 | 不用處理。 |
imagePortsAmbiguous | 映像檔 EXPOSE 了好幾個通訊埠,其中沒有 8080,所以用 8080 執行,這多半不是伺服器監聽的通訊埠。 | 在「設定 › 執行設定 › 通訊埠」選正確的通訊埠再重新啟動服務,或讓 Dockerfile 只 EXPOSE 那一個。 |
平台設定的變數#
| 變數 | 值 |
|---|---|
PORT | 提供 HTTP 的通訊埠。 |
AGENTLAB_RELEASE_ID | 這個容器跑的版本 ID,和 AI 工具從部署狀態讀到的 ID 相同。 |
AGENTLAB_ENVIRONMENT | 執行所在的環境:正式環境是 main,其他環境就是環境名稱。 |
這些名稱不能拿來新增變數或機敏值。如果專案在平台設定這兩個變數之前,就已經有叫 AGENTLAB_RELEASE_ID 或 AGENTLAB_ENVIRONMENT 的值,會照樣保留,其他設定也能正常儲存,只是容器拿到的是平台的值。有空時把它刪掉就好。
加入這兩個變數之前部署的版本不會有它們,重新部署一個新版本就會有了。
新版本上線時#
- 新版本啟動 新版本還沒準備好之前,前一個版本會用原本所有的執行個體繼續服務。
- 切換流量 幾秒內,訪客的新請求和排程工作的呼叫都會改送到新版本。前一個版本手上正在處理的請求,會在它那邊處理完。
- 前一個版本保留一個執行個體 切換後最多 15 分鐘,前一個版本會留一個執行個體繼續跑。它不會再收到新請求,但它自己在做的事會繼續做,例如消化佇列、定期輪詢、計時器。
- 前一個版本停止 程序會收到
SIGTERM,30 秒後還沒結束就會被強制終止。
也就是說,切換之後,前一個版本的程式碼最多還會跑 15 分鐘又 30 秒。另外,重新啟動時執行個體是一個一個替換的,所以同一個版本也會有短暫重疊;執行個體設定不只一個的專案,本來就隨時有好幾個同時在跑。
背景工作程式#
如果你的服務會從共用的地方拿工作來做,例如工作資料表或佇列,背景工作程式要寫成同時跑好幾份也不會出錯:
- 收到
SIGTERM就收尾。 不再拿新工作,手上的那一件做完或還回去,在 30 秒內結束。 - 每件工作先佔用再做。 用資料列鎖(
SELECT … FOR UPDATE SKIP LOCKED),或是設有到期時間、由工作程式定期續期的租約。這樣同一件工作不會有兩個程序在做,持有工作的程序掛掉時,那件工作也會被重新接手。 - 工作交給上線中的版本做。 工作程式看
AGENTLAB_RELEASE_ID就知道自己屬於哪個版本。想知道上線中的是哪個版本,可以加一個回傳AGENTLAB_RELEASE_ID的端點,讓工作程式呼叫自己的對外網址:會回應的只有上線中的版本。拿回來的 ID 跟自己不一樣,就停止拿新工作。 - 記下是誰做的。 把
AGENTLAB_RELEASE_ID寫進記錄,也寫進工作程式改動的資料列,之後就查得到某件工作是哪個版本做的。
// 網頁伺服器另外在 GET /release 回傳 process.env.AGENTLAB_RELEASE_ID。
const mine = process.env.AGENTLAB_RELEASE_ID;
let stopping = false;
process.on("SIGTERM", () => {
stopping = true; // 迴圈結束後,關掉網頁伺服器再結束程序
});
async function isLive() {
try {
const res = await fetch("https://your-app-address/release");
return res.ok && (await res.text()) === mine;
} catch {
return false;
}
}
async function work() {
while (!stopping) {
if (await isLive()) {
await claimAndRunOne(); // 例如 SELECT … FOR UPDATE SKIP LOCKED
} else {
await new Promise((resolve) => setTimeout(resolve, 10_000));
}
}
}會呼叫你服務的排程工作,每次執行也會記下這次送到哪個版本:在工作的執行紀錄裡是 outcome.releaseId。
啟動時會寫檔的映像檔#
有些映像檔啟動時會寫入 /tmp 以外的路徑。例如 nginx:alpine 會寫 /var/cache/nginx,在唯讀的檔案系統上啟動就會失敗。請換成不需要寫入的映像檔,或把寫入位置改到 /tmp:
FROM nginxinc/nginx-unprivileged:alpine
COPY dist/ /usr/share/nginx/html/只是要放靜態檔案?
直接部署靜態網站就好,不用自己跑 nginx。