「我有一個 API 要上線,要接 PostgreSQL,還要一個對外的網址。CI 已經把映像檔推到公司的 registry 了,接下來要做什麼?」
替公司做內部部署平台,很常收到 RD 這樣問。服務最後一定是 Deployment、Service 和 Ingress,但你希望 RD 不必先學會這些,就能自己把服務上線。
Zeabur 在 2026 年 10 月開源的 2.0 是一個值得參考的例子,因為它沒有發明自己的服務模型。表單產生的是一般的 Kubernetes 物件,沒有 Zeabur 專屬的欄位;官方文件也寫明 Zeabur 沒有自己的資料庫,畫面上的專案和服務都直接從叢集讀出來,移除 Zeabur 之後,物件都還在。
所以它的抽象不在物件上,而在使用者看得到的地方:表單問什麼問題、哪些答案由平台自己查、畫面上用什麼詞、出錯時怎麼說。這篇從原始碼整理出七個做法,每個都用開頭那位 RD 的情境舉例,也寫出照著做要付出的代價。
情境是假設的。我沒有安裝執行 Zeabur,內容來自原始碼(commit d4bd01b,版本 0.1.1,仍是 pre-alpha)與官方文件,最新版本可能已經不同。原始碼與開發規範是英文,引號內的中文是我的翻譯;官方中文文件與介面文字直接引用。
1. 問使用者答得出來的問題,物件是答案的結果
把 YAML 包成表單,最直接的做法是一個欄位對應一個 Kubernetes 欄位。這樣的表單,RD 還是填不出來,因為每個欄位背後都要先懂那個物件。
Zeabur 改問 RD 答得出來的問題,第一個是「你手上有什麼」。新增選單的選項是 Docker 映像檔、從 Git 部署、上傳資料夾、Docker Compose、應用程式範本,以及各種資料庫,沒有一個叫 Deployment 或 Ingress;從 YAML 建立放在最後的 進階 裡。
RD 手上有映像檔,選 Docker 映像檔。表單接著問映像檔、名稱、連接埠,以及要不要公開網域,環境變數、磁碟區、規格等收在 更多設定。這些答案在瀏覽器裡組成一組物件:
| RD 回答的問題 | 產生的物件 |
|---|---|
| 映像檔、名稱 | Deployment |
| 連接埠 | Service,以及容器的 TCP 就緒檢查 |
| 公開網域 | Ingress;叢集有 cert-manager 的簽發者時加上 TLS |
| 環境變數 | Secret <名稱>-env |
| 磁碟區 | PersistentVolumeClaim |
| 規格:小/中/大 | requests 與記憶體的 limit |
RD 回答的是「要不要接受連線」「要不要從外面連得到」,Service 和 Ingress 是答案的結果。連接埠留空,就是不接受連線的背景服務,只會建立 Deployment。
做不到的事,也在填表之前說。叢集還沒裝 PostgreSQL 的 operator(Zeabur 用 CloudNativePG)時,選項下方直接寫「需要先安裝 …」,點開是安裝步驟;角色權限不夠的選項照樣顯示,但無法點選,並標出哪個角色才能用。RD 不會填完一整張表,才在最後一步失敗。
問題換了,從答案產生物件的規則就得由平台維護。映像檔、Git、Compose 三個入口最後都會變成 Deployment,這套規則要共用,否則同樣的答案從不同入口進來,會得到不一樣的物件。
2. 使用者答不出來的,平台自己去查
有些問題換成白話,RD 還是答不出來:服務聽哪個連接埠?「安全性」該選哪個?Zeabur 的做法是平台自己去查,查得到就先填好。
連接埠:輸入映像檔之後,Zeabur 去 registry 讀映像檔宣告的連接埠,也就是 Dockerfile 的 EXPOSE,填進表單。公司的私有映像檔也讀得到,用 RD 填的 registry 帳密,或專案裡現有的 pull Secret。
安全性:表單只有 嚴格 與 相容 兩個選項,分別對應 Pod Security 的 restricted 與 baseline,預設值看映像檔設定的使用者。只有數字、而且不是 0 的 UID(例如 USER 1000)才預設嚴格;USER app 這種用名稱指定的使用者,即使不是 root,也預設相容。
原因在 kubelet:設了 runAsNonRoot 時,kubelet 無法從名稱判斷使用者是不是 root,會直接拒絕啟動容器。平台如果一律預設嚴格,RD 第一次部署用 USER app 的映像檔,就會撞上一個講 runAsNonRoot 的錯誤。
這兩個推斷都遵守三個原則:
- 只填空白的欄位,「使用者自己填的值永遠優先」。
- 讀不到不擋部署。registry 連不上時,RD 自己填連接埠就好,原始碼的說法是「部署永遠不必等它」。
- 說出依據。表單會說明為什麼選了嚴格或相容,建立前仍能切換。
推錯比不推更糟,所以預設值要偏向不會讓第一次部署失敗的那一邊,即使那一邊沒那麼安全。
3. 替使用者做取捨,但把後果說出來
有些 Kubernetes 的限制,使用者不該需要知道,卻很容易踩到。Zeabur 把這些限制寫進產生物件的程式,讓使用者選不出會壞的組合,再用白話說出後果。
假設 RD 的 API 要保存上傳的檔案,在表單加了一個磁碟區。表單建立的是 ReadWriteOnce 的 PVC,配上預設的 RollingUpdate,新副本被排到別的 Node 時會掛不上磁碟。所以只要有磁碟區,Zeabur 就把副本數固定為 1,更新策略改成 Recreate。RD 不必知道這些,但文件寫明了後果:「更新時會先停止舊副本,再啟動新副本,這段時間服務會中斷。」
規格也是取捨。小、中、大三種規格都只設記憶體上限,沒有 CPU 上限。原始碼和文件都沒有寫理由,我的解讀是:CPU limit 會讓平均用量很低的服務在突發時被 throttle,連熟悉 Kubernetes 的人都不好查(見CPU 才用三成,為什麼還被 throttle?);記憶體用超過就會被終止,所以要有上限。
替所有人做同一個選擇,就一定有人被擋住。一個服務要兩個副本又要磁碟,在表單上做不到,只能改 YAML(第 7 節)。
4. 使用者選要接哪個資料庫,接線交給平台
開頭的 RD 還要接 PostgreSQL。連線需要的 Secret 名稱、key 和資料庫的位址,RD 不知道,平台卻都查得到:資料庫和服務在同一個專案裡,兩邊的物件它都讀得到。所以 Zeabur 不問連線字串,只問要接哪一個。
RD 建立 PostgreSQL 時就可以勾選要接上的服務,之後也能在資料庫頁按 接到服務。勾選的服務會加上 DATABASE_URL,值引用 CloudNativePG 建立的 Secret:
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: <資料庫的 Secret>
key: uri
RD 不必知道 Secret 的 key 或資料庫 Service 的 DNS 名稱,密碼也不會以明文出現在 Deployment 裡。變數名稱沿用 Railway 的慣例,MongoDB 是 MONGO_URL,Dragonfly 是 REDIS_URL。
接線的程式得跟著每個 operator 的 Secret 格式寫。PostgreSQL 直接引用 CloudNativePG 提供的完整連線字串;其他資料庫要先把密碼讀進一個變數,再用 $(變數) 組出 URL。每多支援一種資料庫,就多一種接法要維護。
5. 只翻每天會看到的詞
前面四個做法處理的是把服務建起來、接上資料庫。服務上線之後,RD 每天看的是服務頁,表單和服務頁上都會一直出現 Kubernetes 的物件。全部保留原文,RD 看不懂;全部翻譯,又會造出一套沒人認得的詞。
Zeabur 的用詞規範只替四種每天會遇到的物件取白話名稱:Pod 是副本,PersistentVolumeClaim 是磁碟,Secret 是機密變數,ConfigMap 是設定檔。其他的 kind 與欄位,例如 Deployment、replicas,都保持原樣;kind 名稱只出現在 YAML、物件頁,以及白話名稱旁的小標籤。
規範的理由是,不要發明兩邊都不用的中間詞:「專業的人會搜尋 kind,初學者會搜尋白話」。假如把 Ingress 改叫「對外入口」,熟悉 Kubernetes 的人找不到它,不熟的人也不會因此更懂。
規範裡另外兩條也可以直接拿來用:
- 一個概念只用一個詞。「服務」指使用者部署的東西;要指 Kubernetes 的 Service 物件時,一律寫「Kubernetes Service」。
- 能顯示真實值,就不解釋。直接顯示
api.shop.svc.cluster.local:8080並提供複製,而不是說明私有位址是什麼。
這些規則和一張術語表一起寫在 repo 的規範文件裡。用詞要在做畫面之前定下來,等每個畫面各自翻譯完再統一,就得把所有畫面都改一遍。
6. 出錯時,翻譯錯誤,也說出誰能修
服務一出錯,Kubernetes 回報的是 CrashLoopBackOff、OOMKilled、ImagePullBackOff。平台如果只包裝了建立流程,RD 這時還是得懂 Kubernetes,或者回頭找平台團隊。
Zeabur 把事件與狀態整理成診斷,每個診斷都有原因、為什麼、怎麼處理,以及依據了哪些狀態與事件。假設 RD 的 API 啟動時讀不到某個環境變數就退出,中文介面會這樣說(服務名稱與次數是示意):
- 原因:「api 反覆崩潰、重新啟動。」
- 為什麼:「它已重新啟動 7 次。叢集每次都會再啟動它,兩次之間等得越來越久,預設最多等 5 分鐘。」
- 處理:「錯誤訊息在重新啟動前那一次的日誌裡。」
原本的 reason 與結束碼還在,收在預設摺疊的「原始錯誤」裡。第 2 節提到的 runAsNonRoot 錯誤也會這樣翻譯:RD 把用 USER app 的映像檔改成嚴格時,看到的是「api 無法啟動:服務的安全性設為『嚴格』,但映像檔用名稱指定使用者,叢集無法確認它不是 root。」處理方式是改用數字指定使用者,或改回相容。
診斷裡最值得借的,是把「問題在哪裡」和「誰能修」拆成兩個欄位。原始碼的說明是:不能讓人把 Node 滿了或 registry 連不上,讀成自己的 bug。
| 情況 | 問題在哪裡 | 誰能修 |
|---|---|---|
| 程式以非 0 的結束碼反覆退出 | 應用程式 | 使用者 |
| ResourceQuota 擋住、沒有 Node 放得下 | 叢集 | 叢集管理員 |
| Node 連不到 registry | registry | 叢集管理員 |
| 沒設記憶體上限,Node 記憶體不足時被終止 | 叢集 | 使用者 |
最後一列說明了為什麼要拆開:記憶體不足發生在整台 Node 上,但能避免它再發生的,是替服務設定記憶體上限。只有一個欄位的話,不是把叢集的問題算到 RD 頭上,就是把 RD 能修的事推給管理員。需要管理員處理時,處理方式會以「這需要叢集管理員處理:」開頭,主要按鈕是 複製診斷,讓 RD 把整份診斷交給對的人。
網址打不開時沒有單一的錯誤可以翻譯,Zeabur 改成沿著請求的路徑,從 DNS 一路檢查到就緒的副本,指出斷在哪一段;查不到的段落,例如網域前面有 CDN,標成無法確認,不算失敗。
診斷得一種錯誤一種錯誤地寫,也不可能涵蓋所有情況。Zeabur 為此留了一種「無法解釋」的診斷,讓原始的錯誤訊息不會是畫面上唯一的說明。
7. 表單不夠用時,退回一般的 Kubernetes
抽象一定有做不到的地方。Zeabur 沒有替這些情況再發明一層,而是讓人退回一般的 Kubernetes:
- 服務頁的幾個分頁有第二個檢視:日誌旁邊是終端機,部署紀錄旁邊是事件,設定旁邊是 YAML。
- 表單沒有啟動指令的欄位,要改
command與args,就切到 YAML。需要表單以外的欄位時,按 以 YAML 編輯,目前的表單內容會一起帶過去。這些修改和表單一樣,要先經過 檢查變更。 - 由 Helm、Argo CD 或 Flux 管理的物件,介面只能重新啟動,修改要回到原本的工具。
因為表單產生的本來就是一般的物件,退回 YAML 時看到的不是平台私有的格式。文件附了等效的 YAML,用 kubectl apply 套用的結果和表單相同。
退回 YAML,也就離開了表單的保護。第 3 節替 RD 做的取捨,例如磁碟區與副本數,在 YAML 裡就要自己負責。
結語:七個做法
回到開頭的 RD。在 Zeabur 上,RD 從頭到尾回答的是「手上有什麼」「要不要接受連線」「要不要從外面連得到」「要接哪個資料庫」,Deployment、Service、Ingress 和 Secret 都是答案的結果。出問題時,畫面告訴 RD 原因、該怎麼做,以及該由誰處理。
做內部部署平台時,可以拿這七個做法對照:
- 問使用者答得出來的問題,物件是答案的結果;做不到的事在填表前就說。
- 使用者答不出來的,平台自己去查;使用者的值優先,讀不到不擋部署,並說出依據。
- Kubernetes 的限制寫進產生物件的程式,替使用者做的取捨,用白話說出後果。
- 接資料庫時,使用者只選接哪一個,平台產生引用 Secret 的連線變數。
- 只翻每天會看到的詞,一個概念只用一個詞。
- 錯誤翻譯成原因與處理,並把「問題在哪裡」和「誰能修」分開。
- 表單不夠用時,退回一般的 Kubernetes,產生的始終是標準物件。
這篇只談畫面與產生物件這一側。2.0 不保存自己的狀態要付出什麼代價,以及它怎麼和 Helm、Argo CD、kubectl 共用同一批物件,是另外的題目。
參考資料
原始碼固定在 zeabur-oss/zeabur 的 commit d4bd01b,依章節列出:
- 開頭:官方文章 Zeabur 開源專案:用更安全的做法,延續熟悉的部署體驗(2026-10-28)、文件 Zeabur 如何管理服務、部署容器映像檔
- 第 1 節:新增選單
menu.tsx、表單與產生物件的程式image-service.ts、文件 部署容器映像檔 - 第 2 節:讀取映像檔
images.rs、連接埠image-ports.ts、安全性pod-security.ts - 第 3 節:
image-service.ts、文件 部署容器映像檔 - 第 4 節:連線變數
connect.ts、接到服務的介面connect.tsx - 第 5 節:用詞規範
wording.md、kind-name.ts - 第 6 節:診斷
diagnosis.rs、問題歸屬fault.rs、中文診斷句子server/zh-TW.ts、介面文字zh-TW.ts、連線檢查trace.rs - 第 7 節:介面規範
zeabur-ui、文件 調整副本、資源與健康檢查、用 YAML 建立和編輯物件