---
title: "Hosted App 部署指南"
description: "說明如何把任意技術棧的應用部署為 AI GO Hosted App：CLI 與 API 部署流程、環境變數、平台資料存取、自訂網域與配額。"
canonical: "https://www.ai-go.app/zh-TW/docs/hosted-app"
locale: "zh-TW"
last_updated: "2026-09-01"
source: "AI GO（https://www.ai-go.app）"
---

# AI GO Hosted App — 部署指南

Hosted App（平台介面稱「自訂 App」）讓您把**任意技術棧的應用程式**部署到 AI GO 平台：上傳原始碼，平台自動建置成容器並以獨立網址運行，同時可透過隨附憑證安全存取 AI GO 的租戶資料。

> 本產品線於 2026 年第三季推出，部分進階功能仍在對各租戶陸續生效中。

---

## 目錄

1. [Hosted App 與 Custom App 的差別](#1-hosted-app-與-custom-app-的差別)
2. [前置條件](#2-前置條件)
3. [快速開始（CLI）](#3-快速開始cli)
4. [應用程式的形狀要求](#4-應用程式的形狀要求)
5. [環境變數](#5-環境變數)
6. [存取 AI GO 平台資料](#6-存取-ai-go-平台資料)
7. [Internal App 與登入處理](#7-internal-app-與登入處理)
8. [資料持久化](#8-資料持久化)
9. [自訂網域](#9-自訂網域)
10. [管理功能與 REST API](#10-管理功能與-rest-api)
11. [配額與錯誤對照](#11-配額與錯誤對照)

---

## 1. Hosted App 與 Custom App 的差別

兩者是**平行的產品線**，依需求選擇：

| | Custom App | Hosted App |
|---|---|---|
| 開發方式 | 平台 Builder 內開發（React + TypeScript + Python Action） | 本機開發，任意語言／框架 |
| 產物 | 平台內的微應用（Shadow DOM） | 容器化的獨立應用 |
| 網址 | 平台站內 | `https://{slug}.deploy.ai-go.app`（可綁自訂網域） |
| 建置 | 平台編譯 | 自動偵測語言建置容器（免寫 Dockerfile） |
| 取平台資料 | 內建 SDK（`db.ts`／`ctx`） | 注入的 API 憑證 + REST |
| 適合 | 在平台內做業務介面、深度使用租戶資料 | 遷入既有服務、需要常駐進程／WebSocket／自選框架 |

**怎麼選**：要在 AI GO 裡做內部工具、直接操作 ERP 與自建表 → Custom App（見〈Custom App 開發者指南〉）。已有一套現成系統要搬上來、或需要平台 Builder 不支援的技術 → Hosted App。

## 2. 前置條件

- **付費方案**：免費檔無法建立 Hosted App（回 403 `hosted_app_requires_paid_plan`）。
- **權限**：操作帳號需具備 `hosted_apps.deploy` 權限（權限不足時平台介面不會顯示建立入口）。
- 建立入口：平台 Builder 頁「我的 Apps」→「自訂 App」；詳情頁在儀表板「AI Apps」區。

## 3. 快速開始（CLI）

安裝 `aigo` CLI（macOS Apple Silicon／Linux x86_64；Windows 請在 Git Bash 下執行）：

```bash
curl -fsSL https://raw.githubusercontent.com/AI-GO-APP/aigo-cli-releases/main/install.sh | bash
```

部署三步：

```bash
aigo login --token        # 貼上 Deploy Token（在 App 詳情頁「設定」分頁發行）
cd my-app                 # 專案根目錄（打包時自動排除 .git / node_modules）
aigo hosted deploy --slug my-app
```

- `--slug` 命中既有 app ＝重新部署（網址不變）；否則**註冊新 app**（佔用配額名額）。部署前可用 `aigo hosted list` 核對。
- 建置日誌即時串流；狀態機為 `queued → building → active | failed`。
- 指令細節以 `aigo --help` 為準（CLI 獨立發版，本文件不複製指令面）。
- 也可完全走 REST API 部署（`POST /api/v1/hosted-apps` 取得上傳資訊後上傳 tarball），適合 CI 環境。

## 4. 應用程式的形狀要求

建置與部署失敗最常見的原因，動手前逐條確認：

| 要求 | 違反時的症狀 |
|---|---|
| 只能開**單一 HTTP port** | 建置預檢警告、rollout 失敗 |
| 監聽環境變數 **`$PORT`**、綁定 **`0.0.0.0`** | `connection refused`、健康檢查失敗 |
| **單一前台行程**（不可 supervisord／pm2／多服務 compose） | 預檢擋下 |
| **提交 lockfile**（package-lock.yaml／go.sum 等） | `frozen-lockfile` 類錯誤 |
| 建置資源上限 2 CPU／4 GiB、預設 900 秒 | `OOMKilled`／`exit code 137`／逾時 |
| 不可是 monorepo 或空目錄 | 預檢擋下；無法辨識的目錄會當靜態網站部署 |

- 支援自動偵測主流語言框架；專案有 Dockerfile 時依 Dockerfile 建置。
- 建置期可連的套件源為白名單（npm／PyPI／Docker Hub 等）；私有 registry 無法使用。
- 應用預設 **scale-to-zero**（閒置縮到零、有流量再喚醒）；需要常駐請在設定開啟 always-on。

## 5. 環境變數

於詳情頁「環境變數」分頁或 `PUT /api/v1/hosted-apps/{id}/runtime-settings` 設定：

- key 格式 `^[A-Z][A-Z0-9_]*$`、≤64 字元；上限 128 個、單值 ≤32 KiB、總量 ≤128 KiB（超出回 422）。
- `PORT`、`K_` 前綴、`AIGO_` 前綴為平台保留，不可自訂。
- 每個變數可標「執行期／建置期／兩者」（2026-09 起，陸續生效）。⚠️ 標「建置期」的值會寫進映像並出現在建置日誌——**機密請只標執行期**。
- 設定變更立即生效，不需重新建置。

## 6. 存取 AI GO 平台資料

每個 Hosted App 建立時，平台自動配發一組專屬 API 憑證，**只經由環境變數注入容器**（不會出現在任何 API 回應）：

```
AIGO_API_TOKEN         # Bearer token
AIGO_PLATFORM_API_URL  # 平台 API 位址（容器內專用；本機開發改用租戶網域）
AIGO_APP_ID / AIGO_TENANT_ID / AIGO_APP_URL / AIGO_ENV
```

用法：`Authorization: Bearer $AIGO_API_TOKEN` 呼叫 `$AIGO_PLATFORM_API_URL/api/v1/open/...`。

⚠️ **ERP 資料表預設零授權**：新 app 呼叫任何 ERP 表都會 403——要先在詳情頁「資料存取」分頁加入資料引用並發布。資料中心自建表則預設整租戶可用。

憑證管理（詳情頁操作）：補建（冪等）／輪替（新舊重疊 30 分鐘）／撤銷（立即失效）。

## 7. Internal App 與登入處理

可見度設為 `internal` 時僅限租戶成員存取，登入由平台代理處理，App 幾乎不用做事，只有一條要寫對：

- 頁面導覽會自動轉向登入；**背景 fetch/XHR** 則收到 `401` + JSON `{"code": "hosted_app_auth_required", ...}`。
- 前端判斷 `code === "hosted_app_auth_required"` 後執行 `window.location.reload()` 觸發頂層導覽即可；**不要**自行導向回應裡的 `login_origin`、不要無限重試。
- 登入 session 為 24 小時；平台 cookie 不會進到你的容器，無需處理。

## 8. 資料持久化

| 位置 | 持久？ |
|---|---|
| 容器檔案系統 | ❌ 重新部署／重啟／縮到零即消失 |
| 持久碟 `/data`（設定開啟後，`AIGO_DATA_DIR` 指向） | ✅ 10 GiB，跨部署保留 |
| 平台資料（經 `/open` API 寫入） | ✅ |

複製 app 時**不會**複製持久碟內容與 Deploy Token。

## 9. 自訂網域

詳情頁「網域」分頁（或 `POST /api/v1/hosted-apps/{id}/domains`）：

1. 加入網域 → 平台回傳需設定的 DNS 記錄
2. 到您的 DNS 服務商設定
3. 驗證 → 憑證簽發後生效（`pending_dns → pending_cert → active`）

限制：不可用 `ai-go.app` 網域樹、不支援萬用字元；需已有運行中的版次。

## 10. 管理功能與 REST API

詳情頁提供：總覽、部署歷史、記錄（建置＋執行期日誌，含 AI 解讀）、活容器檔案管理與網頁終端（除錯用，寫入不持久）、網域、環境變數、資料存取、設定（Deploy Token 管理）。

REST 前綴 `https://{tenant}.ai-go.app/api/v1/hosted-apps`（登入 session）。日常部署面（建立、部署、日誌、重啟、runtime-settings）也接受 Deploy Token；管理面（刪除、複製、改名、網域、檔案／終端、憑證）**僅限登入 session**——用 Deploy Token 呼叫會 403，屬預期行為。

## 11. 配額與錯誤對照

| 錯誤 | 含義 | 處置 |
|---|---|---|
| 403 `hosted_app_requires_paid_plan` | 免費方案 | 升級方案；重試無效 |
| 429 `hosted_app_quota_exceeded` | 已達每租戶 app 數上限 | 刪除不用的 app（會釋放名額）或聯繫平台調整 |
| 422 | 環境變數／參數出界 | 依訊息修正 |
| 503（建置管線未就緒） | 平台側暫時性狀態 | 稍後重試 |
| 部署 `failed` | 建置或啟動失敗 | 看建置日誌，對照第 4 章形狀要求 |
| 403（管理端點） | 用了 Deploy Token | 改用登入 session |