---
title: 容器執行合約
description: 容器 App 的映像檔要符合的規則。平台能自動調整的地方會調整，並在版本頁留下提示。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/runtime-contract
language: zh-Hant-TW
updated: 2026-10-06
---

# 容器執行合約

容器 App 的映像檔要符合的規則。平台能自動調整的地方會調整，並在版本頁留下提示。

## 規則

| 項目     | 要求                         | 不符合時                                                                                                                   |
| -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 啟動指令 | 要有 `CMD` 或 `ENTRYPOINT`。 | 版本被拒收。                                                                                                               |
| 通訊埠   | 在 `$PORT` 提供 HTTP。       | 依「設定 → `EXPOSE` → 8080」的順序決定，見 [App 設定](https://agentlab.cresclab.com/docs/zh-tw/deploy/app-settings.md#port)。 |
| 平台     | `linux/amd64`。              | 推送其他平台的映像檔會被拒絕。                                                                                             |
| 使用者   | 建議設定非 root 的 `USER`。  | 以 root 執行或沒設定時，改用 uid 10001、群組 0 執行；指定映像檔裡沒有的使用者，版本被拒收。                                |
| 檔案系統 | 除了 `/tmp` 都是唯讀。       | 寫入其他路徑會失敗。                                                                                                       |
| 雲端憑證 | 平台不提供。                 | 需要存取外部服務時，改用 App 的密鑰。                                                                                      |

映像檔改用 uid 10001 執行時，它要讀的檔案必須讓群組 0 可以讀。

## 提示

平台調整過的地方會以提示顯示在版本頁和映像檔的「檢查」分頁。AI 工具從部署狀態也讀得到同樣的代碼。

| 代碼                  | 意思                                                                                            | 要做什麼                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `imageUserForced`     | 映像檔以 root 執行，改用 uid 10001 執行。                                                       | 不用處理。想消除提示，就在 Dockerfile 設定非 root 的 `USER`。                                    |
| `imagePortFromExpose` | App 監聽映像檔 `EXPOSE` 的那一個通訊埠。                                                        | 不用處理。                                                                                       |
| `imagePortsAmbiguous` | 映像檔 `EXPOSE` 了好幾個通訊埠，其中沒有 8080，所以用 8080 執行，這多半不是伺服器監聽的通訊埠。 | 在「設定 › 執行設定 › 通訊埠」選正確的通訊埠再重新啟動服務，或讓 Dockerfile 只 `EXPOSE` 那一個。 |

## 啟動時會寫檔的映像檔

有些映像檔啟動時會寫入 `/tmp` 以外的路徑。例如 `nginx:alpine` 會寫 `/var/cache/nginx`，在唯讀的檔案系統上啟動就會失敗。請換成不需要寫入的映像檔，或把寫入位置改到 `/tmp`：

```dockerfile Dockerfile
FROM nginxinc/nginx-unprivileged:alpine
COPY dist/ /usr/share/nginx/html/
```

> [!TIP] 只是要放靜態檔案？
> 直接[部署靜態網站](https://agentlab.cresclab.com/docs/zh-tw/deploy/static-site.md)就好，不用自己跑 nginx。