---
title: "發布、網址與存取控制"
category: "app-development"
canonical: "https://www.ai-go.app/zh-TW/docs/guide/app-release"
locale: "zh-TW"
last_updated: "2026-09-01"
source: "AI GO 開發者文件（https://www.ai-go.app）"
---

# 發布、網址與存取控制

應用程式寫完之後，還有三件事決定它能不能安全上線：怎麼發布、使用者從哪進來、以及誰能存取什麼。

---

## 發布流程

在 Builder 的「發布」分頁提交版本。

1. 填寫**版本號**與**更新日誌**
2. 依權限分流：
   - 有 `builder.publish` 權限 → **直接發布**
   - 沒有 → 建立**發布申請**，等候具權限者審核

發布申請可以被核准、拒絕（需填理由）或由申請人自行取消。這讓「誰能讓程式碼上到正式環境」成為可控的權責，而不是所有開發者都能直接推上線。

### 發布時會凍結什麼

發布不只是把程式碼推上去，它同時**凍結一份授權快照**：

- 引用宣告（哪些表、哪些欄位、什麼操作）
- Scope 宣告

這代表：開發階段改動引用設定不會立刻影響已上線的版本，必須重新發布才會生效。這是刻意的——避免有人在開發環境悄悄擴大權限就立即作用到正式資料上。

### 發布前的阻擋檢查

平台會在發布當下偵測設定缺口並阻擋：

| 檢查 | 阻擋原因 |
|---|---|
| 外部服務未授權 | 程式碼呼叫了外部服務，但該服務尚未加入網域白名單 |
| Action 數量減少 | 這版比上一版少了 Action，可能是誤刪——需明確確認才能繼續 |

這兩項都是「上線後才會在使用者面前爆掉」的典型情況，因此設計成發布前擋下。

> **注意**：發布檢查只驗證服務是否已授權（網域白名單）。平台**不代管、也不驗證**外部服務的金鑰——憑證存放在 App Secrets，由 Action 自行讀出並組進 `Authorization` header 送出。上線後外部 API 若回 `401`，代表應用自帶的憑證有問題，不是發布檢查能攔的範圍。

---

## 網址與識別碼

每個應用程式有兩種識別碼，各自的用途不同：

| | 隨機識別碼 | 可讀名稱 |
|---|---|---|
| 由誰決定 | 系統自動生成 | 您指定 |
| 可否修改 | 否 | 可以（未發布前） |
| 用途 | 永久穩定的內部識別 | 對外網址 |

可讀名稱的規則：

- 長度 4–63 字，僅小寫英數與連字號，不得以連字號開頭或結尾
- 大小寫不敏感（`MyApp` 會被正規化為 `myapp`）
- 不得使用系統保留字（`admin`、`api`、`www`、`login` 等）
- **全域唯一**（跨組織），撞名會被拒絕

若貴組織已選定工作區名稱，實際的對外子網域會帶上組織前綴（形如 `{工作區名稱}-{應用名稱}`）。**請永遠以系統回傳的網址為準，不要自行由組織名推導**——既有應用不會被改名，新舊規則可能並存。

發布後，網址即成為使用者的入口。管理者在主控台複製後分發給對應的使用者。

---

## 生命週期管理

| 操作 | 效果 |
|---|---|
| 重新發布 | 推出新版本，使用者下次載入即取得 |
| 暫停 | 持有網址的使用者無法登入；設定與程式碼保留 |
| 刪除 | 移除應用程式與其網址。**資料中心的資料不會被刪除** |

刪除應用不刪資料是刻意的——資料屬於組織，不屬於某個應用。這也是自建表設計成租戶層級的延伸結果。

---

## 存取控制的四層

應用程式能碰到什麼，由四層疊加決定。四層都通過才放行。

### 第一層：誰看得到這個應用

Internal App 可以設定**可見角色**——只有指定角色的成員能在應用列表看到它、能登入它。

判不可見的應用，對該使用者而言如同不存在：列表不顯示、直接開網址也會被拒絕，且回應與「查無此應用」相同，不洩漏它是否存在。

### 第二層：引用宣告（資料的範圍）

應用程式必須明確宣告要存取的 ERP 表、欄位與操作：

```json
{
  "table_name": "customers",
  "columns": ["id", "name", "email", "custom_data"],
  "permissions": ["read", "create", "update"]
}
```

沒宣告的表存取不到；宣告了表但沒宣告的欄位，讀取時看不到、寫入時被忽略。

**權限值**：

| 值 | 允許 |
|---|---|
| `read` | 查詢 |
| `create` | 新增 |
| `update` | 更新 |
| `delete` | 刪除 |

**實務建議**：一般營運應用**不要給 `delete`**。作廢應該設計成「改狀態欄位」，實際刪除留給管理者在受控環境執行。這樣既保留稽核軌跡，也避免誤刪。

系統核心表（身分驗證、租戶管理、權限設定、稽核紀錄）**永遠不可引用**。

### 第三層：Scope 核可（能力的範圍）

引用管的是「哪些資料」，Scope 管的是「哪些能力」。

應用程式宣告需要的 scope（發布時會自動掃描程式碼回填），由管理員在 Builder 的「Scope」分頁核可。

**高風險 scope 需要額外一道關卡**：把授權擴大到 `db.write`、`erp.*`、`secret.read`、`http`、`knowledge.read` 等高風險能力時，需要**擁有者當場輸入密碼再驗證**。這道設計防的是「授權被悄悄擴大」——即使管理員帳號被冒用，擴權也需要密碼。

External App 與 Self-Built App 的 scope 需要管理員顯式核可，不適用內部應用的簡化流程。

Scope 授權的變更會完整記錄——誰、在什麼時候、把哪個 scope 授給了誰，可在稽核紀錄中查詢。

### 第四層：使用者權限（RBAC）

即使應用程式本身有權限，實際操作仍受**使用者角色**約束。Internal App 可以讀取觸發者的權限標籤，據此決定顯示什麼、允許什麼。

伺服器端的最終判定以觸發者身分為準——前端藏起來的按鈕不是安全邊界。

---

## 三種存取模式對照

| | Internal | External | Self-Built |
|---|---|---|---|
| 使用場景 | 組織內部工具 | 對外客戶／供應商應用 | 第三方系統串接 |
| 認證方式 | 組織成員帳號 | 該應用的使用者系統 | **API Key** |
| 程式碼位置 | AI GO Builder | AI GO Builder | **第三方自行部署** |
| 資料存取 | Internal Proxy | External Proxy | **Open Proxy** |
| 引用需發布 | 否（即時生效） | 否（即時生效） | **是（需發布快照）** |

Self-Built 是給「不想在 AI GO 裡寫程式，只想把資料接出去用」的情境。它沒有 Builder、沒有前端，只有 API Key 與資料存取權。詳見第 11 章。

---

## 稽核

以下操作全部留下紀錄：

- 應用的建立、發布、暫停、刪除
- 引用宣告的變更
- Scope 授權的變更（含執行者身分）
- 每一次 SDK 呼叫

稽核紀錄在主控台「系統與維運管理 › 稽核日誌」查詢，需要 `system.audit_log` 權限。