# Agent Lab 文件

> Agent Lab 是漸強實驗室的企業 AI agent 平台。這份文件說明怎麼用 Agent Lab 部署網頁與容器 App、管理版本與網址、設定排程工作。

---
title: 部署概覽
description: 上傳檔案或原始碼，Agent Lab 會把它建置成一個版本、給它網址並執行。每一個版本都會保留。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy
language: zh-Hant-TW
updated: 2026-10-06
---

# 部署概覽

上傳檔案或原始碼，Agent Lab 會把它建置成一個版本、給它網址並執行。每一個版本都會保留。

## 你可以部署什麼

- [靜態網站](https://agentlab.cresclab.com/docs/zh-tw/deploy/static-site.md): 已建置好的 HTML、CSS 和 JavaScript，例如 `dist/` 的內容，不需要伺服器。
- [容器 App](https://agentlab.cresclab.com/docs/zh-tw/deploy/container-app.md): 附 Dockerfile 的原始碼，用在 webhook、API，或需要密鑰、要呼叫其他服務的程式。
- [用 AI 工具部署](https://agentlab.cresclab.com/docs/zh-tw/deploy/ai-agent.md): 透過 MCP，讓 Claude Code 或 Codex 幫你建立 App、上傳並上線。

## 運作方式

1. **建立 App** 取一個名稱和網址標籤，標籤會成為 App 網址的一部分。
2. **上傳** 上傳的內容決定 App 是網頁還是服務：最上層有 `index.html` 就是網頁，有 `Dockerfile` 就是服務。
3. **建置與檢查** 平台建置出一個新版本，並掃描檔案裡的密鑰、個人資料和從外部載入的腳本；容器 App 還會掃描映像檔裡的套件漏洞。每個版本都有自己的預覽網址。
4. **上線** App 的第一個版本會自動上線。之後的版本，由你決定什麼時候上線。
5. **回到先前版本** 新版本有問題時，讓前一個版本重新上線，不必重新建置。

## 主要概念

| 名詞     | 意思                                                  |
| -------- | ----------------------------------------------------- |
| App      | 你部署的一個網站或服務，有自己的網址、版本和設定。    |
| 版本     | 一次上傳建置出來的結果。版本不會被覆寫。              |
| 對外網址 | 訪客打開的網址，顯示目前上線的版本。                  |
| 內網網址 | 只有同一個組織的服務能呼叫的網址。                    |
| 分支     | 同一個 App 的另一套環境，有自己的設定、密鑰和資料庫。 |

各語言的用詞對照見[術語對照表](https://agentlab.cresclab.com/docs/zh-tw/deploy/glossary.md)。

## 網頁還是服務

> [!WARNING] 有東西要在伺服器上執行，就部署成容器 App
> 例如接收 webhook 或表單、使用 API 金鑰、從伺服器呼叫其他服務。API 金鑰放進網頁的話，每個訪客都讀得到。


---
title: 部署靜態網站
description: 把建置好的網頁部署成一個有 HTTPS 網址的網站。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/static-site
language: zh-Hant-TW
updated: 2026-10-06
---

# 部署靜態網站

把建置好的網頁部署成一個有 HTTPS 網址的網站。

## 事前準備

- 建置好的檔案，例如執行 `npm run build` 之後產生的 `dist/`。
- 建立 App 的權限。只有管理員能建立 App。

要上傳 zip 的話，請在資料夾裡面壓縮，讓 `index.html` 位在 zip 的最上層：

```bash
cd dist
zip -r ../site.zip .
```

> [!WARNING] 常見錯誤
> 直接壓縮 `dist` 資料夾，`index.html` 會變成 `dist/index.html`。最上層沒有 `index.html`，這個版本就會被拒收。

## 1. 建立 App

1. **打開「部署 › App」** 按「建立 App」。
2. **填名稱和網址標籤** 標籤只能用小寫英文字母、數字和連字號，例如 `launch-page`。

> [!NOTE] 網址標籤不會再給別人
> App 刪除之後，這個網址也不會給別的組織使用。建立前請確認拼字。

## 2. 上傳

**主控台**
在 App 的「部署」分頁，把資料夾、`.zip` 或 `index.html` 拖進上傳區（也可以用按鈕選），再按「上傳並建置」。

平台會建置出新版本，並在上線前掃描檔案裡有沒有密鑰或個人資料。
**AI 工具**
在已連接 Agent Lab MCP 的 AI 工具裡輸入：

```prompt
把 dist/ 部署到 Agent Lab 的 launch-page。好了先給我預覽網址，我確認後再上線。
```

設定方式見[用 AI 工具部署](https://agentlab.cresclab.com/docs/zh-tw/deploy/ai-agent.md)。

## 3. 上線

App 的第一個版本建置成功後會自動上線，訪客打開對外網址就看得到：

```text
https://launch-page--acme.hosting.agentlab.run
```

之後的版本不會自動上線。先打開該版本的預覽網址檢查，再到「部署」分頁按「上線」。

## 下一步

- [版本、上線與回到先前版本](https://agentlab.cresclab.com/docs/zh-tw/deploy/versions.md)
- [網址與存取權](https://agentlab.cresclab.com/docs/zh-tw/deploy/addresses.md)：只想給特定的人看，可以把 App 設成私人並加上密碼。


---
title: 從 Dockerfile 部署 App
description: 從含 Dockerfile 的原始碼，部署一個持續執行的服務，例如 webhook、API 或給 agent 用的工具。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/container-app
language: zh-Hant-TW
updated: 2026-10-06
---

# 從 Dockerfile 部署 App

從含 Dockerfile 的原始碼，部署一個持續執行的服務，例如 webhook、API 或給 agent 用的工具。

## 事前準備

- 一個會回應 HTTP 請求的程式。
- 專案最上層有 `Dockerfile`。

## 1. 寫 Dockerfile

以下是 Node.js 的例子。伺服器監聽 `$PORT`，映像檔只 `EXPOSE` 一個通訊埠，並用非 root 的使用者執行：

```dockerfile Dockerfile
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
EXPOSE 8080
CMD ["node", "server.js"]
```

```js server.js
import { createServer } from "node:http";

const port = Number(process.env.PORT ?? 8080);

createServer((req, res) => {
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify({ ok: true, path: req.url }));
}).listen(port);
```

映像檔要符合這幾點，完整規則見[容器執行合約](https://agentlab.cresclab.com/docs/zh-tw/deploy/runtime-contract.md)：

- 有 `CMD` 或 `ENTRYPOINT` 啟動伺服器。
- 在 `$PORT` 提供 HTTP。
- 為 `linux/amd64` 建置。
- 除了 `/tmp`，檔案系統是唯讀的。

## 2. 上傳原始碼

在 App 的「部署」分頁，把原始碼資料夾或它的 `.zip` 拖進上傳區，再按「上傳並建置」。`Dockerfile` 要在最上層。自己壓 zip 時，記得排除 `node_modules`、`.git` 和 `.env`：

```bash
zip -r ../app.zip . -x 'node_modules/*' '.git/*' '.env*'
```

平台會建置映像檔，掃描漏洞與密鑰，並檢查映像檔是否符合執行合約。平台幫你調整過的地方會以提示列在版本頁，例如「映像檔以 root 執行，改用 uid 10001 執行」。

> [!NOTE] 已經有映像檔了？
> 推送到組織的映像檔登錄檔之後，在「部署新版本的來源」選「從映像檔」，就能直接用它建立新版本。

## 3. 上線並確認執行狀態

App 的第一個版本建置成功後會自動上線，之後的版本要到「部署」分頁按「上線」。

「執行」分頁會顯示正在服務的版本，以及有幾個執行個體已經就緒。

> [!WARNING] 版本一直沒有就緒
> 最常見的原因是通訊埠：伺服器沒有監聽平台給的通訊埠。處理方式見[部署失敗排除](https://agentlab.cresclab.com/docs/zh-tw/deploy/troubleshooting.md#not-ready)。

## 4. 加入密鑰

API 金鑰這類機密值，在 App 的「設定」輸入，程式從環境變數讀取。存檔後要重新啟動服務才會套用，重新啟動時舊的執行個體會繼續服務，直到新的就緒。詳見 [App 設定](https://agentlab.cresclab.com/docs/zh-tw/deploy/app-settings.md#secrets)。

> [!WARNING] 不要把密鑰放進原始碼
> 掃描找到映像檔裡有密鑰時，請把它從原始碼拿掉、改成 App 的密鑰，並且換一把新的金鑰。


---
title: 用 AI 工具部署
description: 讓 Claude Code、Codex 或其他支援 MCP 的 AI 工具幫你建立 App、上傳並上線。你只需要在瀏覽器登入一次。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/ai-agent
language: zh-Hant-TW
updated: 2026-10-06
---

# 用 AI 工具部署

讓 Claude Code、Codex 或其他支援 MCP 的 AI 工具幫你建立 App、上傳並上線。你只需要在瀏覽器登入一次。

## 1. 連接 Agent Lab MCP

在終端機執行你所用工具的指令。把 `acme` 換成你的組織名稱；主控台的「MCP」頁面會顯示已經填好組織名稱的指令。

**Claude Code**

```bash
claude mcp add --transport http agentlab-acme https://api.agentlab.cresclab.com/v1/mcp
```

**Codex**

```bash
codex mcp add agentlab-acme --url https://api.agentlab.cresclab.com/v1/mcp
codex mcp login agentlab-acme
```

**其他 MCP 工具**
新增一個 HTTP 類型的 MCP 伺服器，網址填：

```text
https://api.agentlab.cresclab.com/v1/mcp
```

瀏覽器會打開登入頁，登入並選好組織就連上了。

> [!NOTE] 不需要密碼、權杖或 API 金鑰
> 授權在瀏覽器完成。這條連線能做的事，和你本人在主控台能做的一樣多，不會更多。

## 2. 請 AI 工具部署

在專案資料夾裡，請 AI 工具讀部署指南，照著做：

```prompt
讀 https://app.agentlab.cresclab.com/agent/deploy.md，照著步驟把這個資料夾部署到 Agent Lab 的組織 acme。
```

要它查這份文件的話，給它這一頁的 Markdown 網址，或整份文件的目錄 `https://agentlab.cresclab.com/docs/zh-tw/llms.txt`。MCP 伺服器也有 `docs_read` 工具，可以讀到同樣的頁面。

## 3. AI 工具會怎麼做

1. **找到或建立 App** 建立前會先跟你確認網址標籤，因為標籤不能重複使用。
2. **上傳** 把 zip 直接上傳到平台給的位址，檔案不會經過對話。
3. **等候建置** 查詢版本狀態，直到成功或失敗。
4. **上線前問你** 先說明要上線哪一個版本，等你同意。

> [!NOTE] 密鑰還是由你輸入
> AI 工具會告訴你去哪裡輸入密鑰，不會要你把密鑰貼進對話。

所有工具見 [MCP 工具](https://agentlab.cresclab.com/docs/zh-tw/deploy/mcp-tools.md)。


---
title: 版本、上線與回到先前版本
description: 每次上傳都會產生一個新版本。版本不會被覆寫，任何建置成功的版本都可以上線，新舊都行。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/versions
language: zh-Hant-TW
updated: 2026-10-06
---

# 版本、上線與回到先前版本

每次上傳都會產生一個新版本。版本不會被覆寫，任何建置成功的版本都可以上線，新舊都行。

## 建置階段

上傳之後，版本會依序經過這些階段，「部署」分頁的版本列會顯示目前在哪一段：

| 階段     | 平台在做什麼                                                                                                |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| 排隊中   | 等待建置機器。畫面會顯示前面還有幾個。                                                                      |
| 建置中   | 建置網頁或容器映像檔。                                                                                      |
| 掃描中   | 檢查密鑰、個人資料、外部載入的腳本；容器 App 另外掃描映像檔的漏洞與密鑰。                                   |
| 審查中   | 整理掃描結果。                                                                                              |
| 等待確認 | 有檢查項目設成「會先問過你」，而且找到了問題。看過結果後，你可以決定照樣發佈。                              |
| 成功     | 版本可以上線。                                                                                              |
| 失敗     | 內容被拒收，或平台出錯。見[部署失敗排除](https://agentlab.cresclab.com/docs/zh-tw/deploy/troubleshooting.md)。 |

每個檢查項目在版本的檢查結果裡會標出它的處理方式：「會擋下部署」、「會先問過你」或「不執行」。

## 上線

App 的第一個版本建置成功後會自動上線。之後的版本，在「部署」分頁按版本列的「上線」。訪客會在一分鐘內看到新版本。

上線前，先打開該版本的預覽網址檢查。每個版本都有自己的預覽網址，不管目前上線的是哪一版都能開。

## 回到先前版本

新版本有問題時，在版本列表找到先前的版本，按「回到這個版本」。這和上線是同一個動作，不會重新上傳，也不會重新建置。

> [!NOTE] 內網呼叫也會跟著切換
> 其他 App 透過內網網址呼叫這個 App 時，打到的是目前上線的版本。上線或回到先前版本，內網呼叫的目標也會跟著換。

## 分支

App 有多個分支時，所有動作都只作用在你目前所在的分支。上傳按鈕會寫「上傳，並在 ‹分支› 上線」，上線也只影響這個分支。每個分支用自己的設定和密鑰。

在某個分支上線之前，平台會比對這個分支的變數與密鑰名稱，缺少的會先提醒你。


---
title: 網址與存取權
description: 每個 App 有對外網址、版本預覽網址和內網網址三種網址，可以設成公開或用密碼保護。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/addresses
language: zh-Hant-TW
updated: 2026-10-06
---

# 網址與存取權

每個 App 有對外網址、版本預覽網址和內網網址三種網址，可以設成公開或用密碼保護。

## 三種網址

網址由網址標籤和組織名稱組成，全部使用 HTTPS。

| 網址         | 誰能打開                               | 範例                                                    |
| ------------ | -------------------------------------- | ------------------------------------------------------- |
| 對外網址     | 任何人；App 設成私人時要輸入密碼       | `https://order-api--acme.hosting.agentlab.run`          |
| 版本預覽網址 | 拿到網址的人；App 設成私人時要輸入密碼 | 每個版本一個，列在版本旁邊                              |
| 內網網址     | 只有同組織的 App，瀏覽器打不開         | `https://order-api--acme.internal-hosting.agentlab.run` |

## 網址標籤

網址標籤在建立 App 時決定，只能用小寫英文字母、數字和連字號。標籤用過之後就留給你的組織，App 永久刪除了也不會給別人。

## 公開或私人

在 App 的「設定」選擇存取權：

| 選項 | 效果                                                                |
| ---- | ------------------------------------------------------------------- |
| 公開 | 任何人拿到網址都能看。                                              |
| 私人 | 這個 App 的每個網址（對外網址和各版本的預覽網址）都會先顯示密碼頁。 |

密碼由主控台產生，只顯示一次。弄丟了就重新產生一組。

> [!NOTE] 私人 App 不經過 CDN
> 給幾個人審閱沒問題，但不適合承接大量流量。

## 從另一個 App 呼叫

同一個組織的 App 之間，用內網網址互相呼叫：

- 只有你組織的 App 能從平台內部呼叫。其他組織、建置過程和網際網路都呼叫不到。
- 憑證是公開信任的，一般的 HTTP 用戶端不用額外設定。
- 呼叫會打到目前上線的版本。
- 內網網址不會顯示密碼頁。需要保護的端點，請在程式裡自己檢查。

從內網網址進來的請求會帶 `X-Franky-Caller-App` 標頭，值是發出請求的 App 的網址標籤。只有在 `Host` 是內網網域時才信任它：

```js server.js
const internal = req.headers.host?.endsWith(".internal-hosting.agentlab.run");
const caller = internal ? req.headers["x-franky-caller-app"] : undefined;

if (req.url.startsWith("/admin") && caller !== "billing-worker") {
  res.writeHead(403).end();
  return;
}
```


---
title: App 設定
description: 在 App 的「設定」調整通訊埠、密鑰和存取權，或暫停、移除 App。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/app-settings
language: zh-Hant-TW
updated: 2026-10-06
---

# App 設定

在 App 的「設定」調整通訊埠、密鑰和存取權，或暫停、移除 App。

## 通訊埠

平台照這個順序決定容器 App 的通訊埠，並用環境變數 `PORT` 告訴你的程式：

1. 「設定 › 執行設定 › 通訊埠」有填，就用它。
2. 沒填，就用映像檔 `EXPOSE` 的那一個 TCP 通訊埠。
3. 兩者都沒有，就用 `8080`。

## 密鑰

密鑰是 API 金鑰、權杖這類機密值。在主控台輸入，程式用環境變數讀取。每個分支有自己的一組密鑰。

> [!WARNING] 密鑰只在主控台輸入
> 不要寫進檔案、指令，也不要貼進和 AI 工具的對話。

## 套用設定

執行設定存檔後不會馬上影響正在跑的服務。總覽會提示設定已變更，按「重新啟動服務」才會套用。重新啟動時，舊的執行個體會繼續服務，直到新的就緒。

## 暫停、移除與永久刪除

| 動作     | 會發生什麼                                                           | 能不能復原                         |
| -------- | -------------------------------------------------------------------- | ---------------------------------- |
| 暫停 App | App 下線，訪客看到中性頁面。所有內容都保留，暫停期間不能部署新版本。 | 可以，按「恢復 App」。             |
| 移除 App | App 立刻下線，開始 7 天的寬限期。                                    | 7 天內可以還原，之後版本會被刪除。 |
| 永久刪除 | 所有版本和網址立刻刪除，要輸入 App 名稱確認。                        | 不能。網址也不會再給任何人。       |


---
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。


---
title: 排程工作
description: 排程工作依照時間表，對你組織的某個 App 發出一次 HTTP 呼叫，類似 Google Cloud Scheduler。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/scheduled-jobs
language: zh-Hant-TW
updated: 2026-10-06
---

# 排程工作

排程工作依照時間表，對你組織的某個 App 發出一次 HTTP 呼叫，類似 Google Cloud Scheduler。

## 排程工作的內容

呼叫會打到當下上線的版本。

| 欄位 | 說明                                                                                             |
| ---- | ------------------------------------------------------------------------------------------------ |
| App  | 要呼叫的容器 App。                                                                               |
| 路徑 | 接在 App 網址後面，以 `/` 開頭，可以帶查詢字串，例如 `/tasks/daily`。                            |
| 方法 | `GET`、`POST`、`PUT`、`PATCH` 或 `DELETE`，預設 `POST`。只有 `POST`、`PUT`、`PATCH` 會送出內文。 |
| 排程 | 五個欄位的 cron 運算式：分、時、日、月、星期。最密每分鐘一次。                                   |
| 時區 | 預設 `Asia/Taipei`。                                                                             |

cron 運算式的例子：

| 運算式         | 執行時間        |
| -------------- | --------------- |
| `0 9 * * *`    | 每天 09:00      |
| `*/15 * * * *` | 每 15 分鐘      |
| `0 8 * * 1`    | 每週一 08:00    |
| `0 0 1 * *`    | 每月 1 日 00:00 |

## 建立排程工作

1. **在 App 加一個端點** 例如 `POST /tasks/daily`，把要定期做的事寫在裡面，部署上線。
2. **建立排程工作** 打開「部署 › 排程工作」，選 App，填路徑和排程。
3. **手動執行一次** 用「立即執行」試跑，在執行紀錄確認回應碼和記錄。

## 確認呼叫來自排程

預設的呼叫不帶任何驗證資訊。要讓 App 確認來源，二選一：

- 在排程工作設定自訂標頭，例如 `X-Cron-Secret`，值存成 App 的密鑰，程式裡比對。
- 開啟簽署權杖，呼叫會帶 `Authorization: Bearer <JWT>`。用 `https://api.agentlab.cresclab.com/.well-known/jwks.json` 驗證，`aud` 是 `franky:app:<App ID>`。

## 執行規則

| 項目 | 行為                                                          |
| ---- | ------------------------------------------------------------- |
| 重疊 | 不會重疊。上一次還沒結束時，到期的那一次會略過。              |
| 送達 | 至少送達一次，可能重複。請用 `X-Franky-Run-Id` 標頭去除重複。 |
| 重試 | 預設 0 次，最多 5 次。                                        |
| 逾時 | 15 秒到 30 分鐘，預設 3 分鐘。                                |

```js server.js
const runId = req.headers["x-franky-run-id"];
if (await alreadyHandled(runId)) {
  res.writeHead(200).end();
  return;
}
```


---
title: 部署失敗排除
description: 版本失敗時，先在版本頁看原因。內容被拒收就修正後重新上傳；平台出錯就直接重試。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/troubleshooting
language: zh-Hant-TW
updated: 2026-10-06
---

# 部署失敗排除

版本失敗時，先在版本頁看原因。內容被拒收就修正後重新上傳；平台出錯就直接重試。

## 內容被拒收

| 你看到的             | 原因                                     | 怎麼修                                                               |
| -------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
| 找不到 `index.html`  | 壓縮的是資料夾本身，不是資料夾裡的內容。 | 進到資料夾裡再壓縮，讓 `index.html` 在最上層。                       |
| 檔案裡有密鑰         | 上傳的內容裡有像 API 金鑰或權杖的字串。  | 從檔案移除，換一把新的金鑰，改在 App 的「設定」輸入，再重新上傳。    |
| 映像檔沒有 `CMD`     | Dockerfile 沒有啟動指令。                | 加上 `CMD` 或 `ENTRYPOINT`。                                         |
| `USER` 不存在        | Dockerfile 指定了映像檔裡沒有的使用者。  | 改用數字 uid，或映像檔裡已有的使用者，例如 `node`。                  |
| 推送被拒，不是 amd64 | 在 Apple 晶片的 Mac 上建置成了 arm64。   | 用 `docker build --platform linux/amd64` 重新建置。                  |
| 嚴重漏洞             | 映像檔裡的套件有已知的嚴重漏洞。         | 把套件升級到掃描結果寫的修正版本，或換成已包含該版本的新基底映像檔。 |

## 等待確認

有檢查項目設成「會先問過你」並且找到問題時，版本會停在「等待確認」。看過掃描結果後，你可以決定照樣發佈。高風險漏洞就屬於這一類，修法和嚴重漏洞相同，升級之後提示才會消失。

## 版本一直沒有就緒

建置成功、也上線了，但「執行」分頁的執行個體一直沒有就緒，多半是通訊埠的問題：伺服器沒有監聽平台給的通訊埠。

1. 看版本頁有沒有 `imagePortsAmbiguous` 提示。
2. 讓伺服器監聽環境變數 `PORT`，或到「設定 › 執行設定 › 通訊埠」填伺服器實際監聽的通訊埠。
3. 按「重新啟動服務」。

## 啟動後不斷重新啟動

最常見的原因是程式寫入了 `/tmp` 以外的路徑，而檔案系統是唯讀的。把寫入位置改到 `/tmp`，見[容器執行合約](https://agentlab.cresclab.com/docs/zh-tw/deploy/runtime-contract.md#writable-paths)。

## 平台出錯

失敗原因是平台本身時，不需要修改內容，也不用重新上傳，直接重試同一個版本。

## 還是找不到原因

- 到「執行」分頁看執行個體的狀態和最近的記錄。
- 到映像檔的「檢查」分頁看平台留下的提示。
- 請已連接 Agent Lab MCP 的 AI 工具讀部署狀態幫你判斷。它讀到的失敗原因和這一頁的代碼相同。


---
title: MCP 工具
description: Agent Lab MCP 伺服器上和部署有關的工具。AI 工具能做的事，不會超過你在主控台能做的。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/mcp-tools
language: zh-Hant-TW
updated: 2026-10-06
---

# MCP 工具

Agent Lab MCP 伺服器上和部署有關的工具。AI 工具能做的事，不會超過你在主控台能做的。

## 連線網址

```text
https://api.agentlab.cresclab.com/v1/mcp
```

連接方式見[用 AI 工具部署](https://agentlab.cresclab.com/docs/zh-tw/deploy/ai-agent.md#connect)。每個工具都要帶 `organization` 參數，值在連線時由伺服器告知。

## App 與版本

| 工具                    | 用途                                                 |
| ----------------------- | ---------------------------------------------------- |
| `sites_list`            | 列出 App，以及各自的網址和內網網址。                 |
| `sites_create`          | 建立 App。網址標籤不能重複使用。                     |
| `sites_deploy`          | 開始一個新版本，回傳上傳位址和權杖。                 |
| `sites_deploy_finalize` | 上傳完成後，送出這個版本開始建置。                   |
| `sites_deploy_status`   | 版本的階段、失敗原因、通訊埠和提示。                 |
| `sites_deploy_retry`    | 重試因平台出錯而失敗的版本，不用重新上傳。           |
| `sites_promote`         | 讓某個版本上線，也用來回到先前版本。                 |
| `sites_runtime_status`  | 正在服務的版本，以及就緒的執行個體數。               |
| `sites_restart`         | 不中斷服務，套用已儲存的設定。                       |
| `sites_files`           | 版本的檔案清單：路徑、大小和雜湊值，不回傳檔案內容。 |
| `sites_lifecycle`       | 暫停、恢復、移除或還原 App，所有分支一起生效。       |
| `sites_purge`           | 永久刪除 App，無法復原。                             |

## 排程工作

| 工具                                             | 用途                                       |
| ------------------------------------------------ | ------------------------------------------ |
| `scheduled_jobs_list`、`scheduled_jobs_get`      | 列出排程工作，或讀取一個。                 |
| `scheduled_jobs_create`、`scheduled_jobs_update` | 建立或修改。修改會取代整個設定，請先讀取。 |
| `scheduled_jobs_run`                             | 立即執行一次。                             |
| `scheduled_jobs_runs`                            | 執行紀錄，以及單次執行的記錄。             |
| `scheduled_jobs_lifecycle`                       | 暫停、恢復或刪除。                         |

## 分支與文件

| 工具                | 用途                                           |
| ------------------- | ---------------------------------------------- |
| `environments_list` | 列出組織的分支。                               |
| `docs_read`         | 以 Markdown 讀這份文件。不指定頁面時回傳目錄。 |

> [!NOTE] 有多個分支時要指定分支
> 組織有一個以上的分支時，每個呼叫都要指定分支，否則會以 `environmentRequired` 拒絕。

## 錯誤裡的文件連結

部署被拒收時，`sites_deploy_status` 的失敗原因會附上 `help`，指向[部署失敗排除](https://agentlab.cresclab.com/docs/zh-tw/deploy/troubleshooting.md)的英文 Markdown 版；映像檔提示會附上 `noticesHelp`，指向[容器執行合約](https://agentlab.cresclab.com/docs/zh-tw/deploy/runtime-contract.md#notices)。


---
title: 術語對照表
description: 這份文件在四種語言使用的用詞。先跟主控台一致，主控台沒有的才參考 Google Cloud、Cloudflare 和 Vercel 的在地化文件。
url: https://agentlab.cresclab.com/docs/zh-tw/deploy/glossary
language: zh-Hant-TW
updated: 2026-10-06
---

# 術語對照表

這份文件在四種語言使用的用詞。先跟主控台一致，主控台沒有的才參考 Google Cloud、Cloudflare 和 Vercel 的在地化文件。

## 用詞

| English              | 正體中文     | 日本語             | ไทย                    | 參考 / Reference                               |
| -------------------- | ------------ | ------------------ | ---------------------- | ---------------------------------------------- |
| Deploy               | 部署         | デプロイ           | ดีพลอย                 | Google Cloud, Cloudflare, Vercel               |
| App                  | App          | アプリ             | แอป                    | Cloudflare Workers & Pages                     |
| Version              | 版本         | バージョン         | เวอร์ชัน               | Cloudflare Versions (Cloud Run: revision)      |
| Go live              | 上線         | 公開               | เผยแพร่                | Vercel: Promote to Production                  |
| Roll back            | 回到先前版本 | ロールバック       | ย้อนกลับ               | Cloudflare Rollbacks, Vercel Instant Rollback  |
| Production           | 正式環境     | 本番環境           | โปรดักชัน              | Vercel, Cloudflare                             |
| Preview address      | 版本預覽網址 | プレビューアドレス | ที่อยู่พรีวิว          | Cloudflare Preview URLs                        |
| Public address       | 對外網址     | 公開アドレス       | ที่อยู่สาธารณะ         | Agent Lab console                              |
| Internal address     | 內網網址     | 内部アドレス       | ที่อยู่ภายใน           | Agent Lab console                              |
| Address label        | 網址標籤     | アドレスラベル     | ป้ายกำกับที่อยู่       | Agent Lab console                              |
| Branch               | 分支         | ブランチ           | สาขา                   | Cloudflare Pages branches, Vercel Environments |
| Build                | 建置         | ビルド             | บิลด์                  | Google Cloud Build                             |
| Container image      | 容器映像檔   | コンテナイメージ   | อิมเมจคอนเทนเนอร์      | Google Cloud Artifact Registry                 |
| Image registry       | 映像檔登錄檔 | イメージレジストリ | รีจิสทรีอิมเมจ         | Google Cloud Artifact Registry                 |
| Port                 | 通訊埠       | ポート             | พอร์ต                  | Google Cloud                                   |
| Instance             | 執行個體     | インスタンス       | อินสแตนซ์              | Google Cloud Run                               |
| Environment variable | 環境變數     | 環境変数           | ตัวแปรสภาพแวดล้อม      | Google Cloud, Vercel, Cloudflare               |
| Secret               | 密鑰         | シークレット       | ความลับ                | Google Secret Manager, Cloudflare Secrets      |
| Access               | 存取權       | アクセス           | การเข้าถึง             | Google Cloud IAM                               |
| Logs                 | 記錄         | ログ               | บันทึก                 | Google Cloud Logging                           |
| Scheduled job        | 排程工作     | スケジュールジョブ | งานตามกำหนดเวลา        | Google Cloud Scheduler                         |
| Cron expression      | cron 運算式  | cron 式            | นิพจน์ cron            | Cloudflare Cron Triggers                       |
| Time zone            | 時區         | タイムゾーン       | เขตเวลา                | Google Cloud                                   |
| Restart              | 重新啟動     | 再起動             | รีสตาร์ต               | Google Cloud                                   |
| Pause / Resume       | 暫停 / 恢復  | 一時停止 / 再開    | หยุดชั่วคราว / เปิดต่อ | Agent Lab console                              |
| Remove / Restore     | 移除 / 還原  | 削除 / 復元        | ลบออก / กู้คืน         | Agent Lab console                              |
| Delete permanently   | 永久刪除     | 完全に削除         | ลบถาวร                 | Agent Lab console                              |
| Notice               | 提示         | お知らせ           | ประกาศ                 | Agent Lab console                              |

## 選詞原則

- 主控台已經有的字就照用，文件和畫面才對得起來。
- 主控台沒有的字，用 Google Cloud 台灣版文件的譯法，例如通訊埠、執行個體、記錄，不用端口、實例、日誌。
- 業界習慣用外來語的就保留，例如 App、デプロイ、ดีพลอย。
- 寫使用者在畫面上看到的名稱：寫「分支」，不寫系統內部的「環境」。