---
title: 推送 Docker 映像檔並部署
description: 安裝 agentlab CLI（alpha 版）並登入，用 docker push 把 linux/amd64 映像檔推送到組織的映像檔登錄檔，再部署成專案的新版本。只限付費方案。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/registry
language: zh-Hant
updated: 2026-10-28
---

# 推送 Docker 映像檔並部署

安裝 agentlab CLI（alpha 版）並登入，用 docker push 把 linux/amd64 映像檔推送到組織的映像檔登錄檔，再部署成專案的新版本。只限付費方案。

## 事前準備

- Pro、Team 或 Business 方案。Free 方案沒有映像檔登錄檔，請改用[原始碼部署](https://agentlab.cresclab.com/docs/zh-tw/deploy/source-build.md)或[從 Dockerfile 部署](https://agentlab.cresclab.com/docs/zh-tw/deploy/container-app.md)。
- 可以部署的角色。
- Docker，以及 CLI 需要的 Node.js 24 以上。CLI 支援 macOS、Linux 和 Windows，x64 與 arm64 都可以。

## 1. 安裝 CLI

```sh
npm install --global @crescendolab/agentlab-cli@alpha
agentlab --version
```

> [!WARNING] CLI 還是 alpha 版
> 正式版推出前，指令和行為都可能改變。請照上面的指令，用 `alpha` 標籤安裝。

Windows 上請允許套件的安裝腳本執行：它會把 `docker-credential-agentlab.exe` 放在 npm 指令捷徑旁邊，Docker 才找得到。

## 2. 登入並設定 Docker

```sh
agentlab login
agentlab auth configure-docker
agentlab status
```

`agentlab login` 會打開瀏覽器，登入後選擇組織。`agentlab auth configure-docker` 把 Agent Lab 的憑證小幫手加進 Docker 設定，之後 `docker push` 會用你的身分登入，不需要另外 `docker login`。`agentlab status` 會顯示帳號、組織和登入何時到期。

一次登入對應一個組織。要換組織，再執行一次 `agentlab login`。

## 3. 建置並推送

映像檔的路徑是 `registry.agentlab.cresclab.com/<組織 id>/<名稱>:<標籤>`。組織 id 是一串 UUID，在 **映像檔** › **設定說明** 看到的指令已經幫你填好。

```sh
docker build --platform linux/amd64 -t registry.agentlab.cresclab.com/<組織 id>/orders-api:v1 .
docker push registry.agentlab.cresclab.com/<組織 id>/orders-api:v1
```

請建置成 `linux/amd64`，其他平台的映像檔推送時會被拒絕。Apple 晶片的 Mac 一定要加 `--platform linux/amd64`。

推送後，映像檔會依[容器執行規範](https://agentlab.cresclab.com/docs/zh-tw/deploy/runtime-contract.md)檢查；有開啟掃描的話，也會掃描弱點。**檢查** 欄會先顯示 **檢查中**，再變成 **通過**、**有警告** 或 **已拒絕**。推送本身不會改變上線中的版本。

## 4. 部署映像檔

1. 開啟專案的「部署」分頁，在 **部署新版本的來源** 選 **從映像檔**。
2. 選擇 **倉庫** 和 **標籤或 digest**，按 **部署映像檔**。

也可以從 **映像檔** 打開倉庫，按 **部署到專案**。

建立版本時，標籤會轉成 digest，所以之後再推送同一個標籤，也不會改到這個版本。只有正式環境時，版本通過檢查後就會自動上線；有多個環境時，由你在「部署」分頁決定什麼時候上線（見[版本](https://agentlab.cresclab.com/docs/zh-tw/deploy/versions.md)）。被拒絕的映像檔不能部署；**有警告** 的映像檔要等有人確認。

## 從 CI 推送

CI 裡不用 CLI，改用 robot token。擁有者或管理員在 **部署設定** › **Robot token** 建立，token 只顯示一次。它只能推送，屬於組織，不屬於建立它的人。

```sh
echo "$AGENTLAB_ROBOT_TOKEN" | docker login registry.agentlab.cresclab.com -u agentlab --password-stdin
docker push registry.agentlab.cresclab.com/<組織 id>/orders-api:$GIT_SHA
```

使用者名稱不會被檢查。要撤銷 token，也在同一個地方。

## 映像檔要符合的規則

推送的映像檔和從 Dockerfile 建置的映像檔，規則都一樣。完整清單見[容器執行規範](https://agentlab.cresclab.com/docs/zh-tw/deploy/runtime-contract.md)。

| 規則     | 要求                                                                                        |
| -------- | ------------------------------------------------------------------------------------------- |
| 平台     | 只能是 `linux/amd64`。                                                                      |
| 啟動指令 | 要有 `CMD` 或 `ENTRYPOINT`。                                                                |
| 通訊埠   | 在 `$PORT` 提供 HTTP。依序採用專案的通訊埠設定、映像檔唯一 `EXPOSE` 的通訊埠，最後是 8080。 |
| 使用者   | 建議設定非 root 的 `USER`。用 root 或沒設 `USER` 時，以 uid 10001、群組 0 執行。            |
| 檔案系統 | 除了 `/tmp`，都是唯讀。                                                                     |
| 大小     | 最大 2.5 GiB。                                                                              |

## 會保留什麼

- **每個倉庫保留 5 個版本。**推送或建置帶來第 6 個時，最舊、沒有被使用的映像檔會被移除。上線中、屬於專案最近 5 個版本，或被排程工作使用的映像檔，都算在使用中。倉庫裡的映像檔全都在使用中時，推送會被拒絕。
- **各方案的儲存空間：**Pro 50 GB、Team 250 GB、Business 依合約。
- **推送映像檔的弱點掃描**只有 Team 和 Business 有，預設關閉：在 **部署設定** 打開 **掃描 push 的映像檔**。
- **從原始碼建置的專案**，映像檔也放在這裡，倉庫以專案命名。
- 在 **映像檔** 可以**刪除**單一映像檔或整個倉庫（限管理員）。使用中的映像檔不能刪除。
- **不支援拉取。**登錄檔只接受為了部署而推送的映像檔，`docker pull` 會被拒絕。

## CLI 指令

| 指令                             | 作用                                             |
| -------------------------------- | ------------------------------------------------ |
| `agentlab login [--org <uuid>]`  | 在瀏覽器登入。`--org` 會預先選好組織。           |
| `agentlab auth configure-docker` | 讓 Docker 用 Agent Lab 的憑證小幫手存取登錄檔。  |
| `agentlab status [--json]`       | 目前登入的帳號、組織，以及登入何時到期。         |
| `agentlab logout`                | 登出，並刪除這台電腦存著的登入資訊和登錄檔憑證。 |

- 登入資訊存在系統的鑰匙圈；沒有鑰匙圈時，存在 `~/.config/agentlab/credentials.json`（權限 `0600`）。
- 擁有者和管理員可以在 **部署設定** 關閉 **允許用 agentlab CLI 登入**，已登入的 CLI 不久後就會停止運作。**已登入的 CLI** 列出每一次登入，每一筆都可以 **撤銷登入**。
- 要移除 CLI：先 `agentlab logout`，再 `npm uninstall --global @crescendolab/agentlab-cli`。

## 推送失敗時

| 看到的訊息             | 原因和處理方式                                                                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthorized`         | 再執行一次 `agentlab login`。如果你曾經對這個登錄檔執行過 `docker login`，Docker 會先用那組：`docker logout registry.agentlab.cresclab.com`。 |
| `denied`，提到方案     | 方案沒有映像檔登錄檔，或儲存空間已滿。擁有者或管理員可以在 **設定 › 方案與付款** 升級。                                                       |
| `denied`，提到平台     | 映像檔不是 `linux/amd64`。加上 `--platform linux/amd64` 重新建置。                                                                            |
| `denied`，提到版本上限 | 倉庫裡每個映像檔都在使用中。先部署較新的版本，或推送到新的倉庫。                                                                              |
| 推送後顯示 **已拒絕**  | 映像檔違反了上面的規則，檢查結果會寫出是哪一條。                                                                                              |