AI GO Hosted App — 部署指南

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

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

1. Hosted App 與 Custom App 的差別

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

怎麼選：要在 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 下執行）：

curl -fsSL https://raw.githubusercontent.com/AI-GO-APP/aigo-cli-releases/main/install.sh | 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. 應用程式的形狀要求

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

• 支援自動偵測主流語言框架；專案有 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. 資料持久化

複製 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. 配額與錯誤對照