從 Git 建置並部署服務

連接 Git 儲存庫、完成第一次建置，並選擇新映像檔何時上線。

在專案選擇新增 → 從 Git 部署，填入儲存庫與應用程式的連接埠，再 檢查變更。套用後，Zeabur Builder 開始建置。第一個映像檔完成並部署後，服務才會啟動。

開始前

已有專案，以及在專案建立服務、Kubernetes Service 和 Build 的權限。使用私有儲存庫或建置變數時，也需要建立機密的權限。
叢集已安裝 Zeabur Builder 和 Keel。缺少元件時，新增選單會顯示原因，安裝方式見管理叢集元件。
建置好的映像檔推到 Zeabur chart 的 builds.registry，預設是元件目錄的 Zot（zot.zot.svc:5000）。改用 Harbor 或外部 registry 時，管理員在 chart 設定 builds.registry，並讓 Builder 與節點能存取它。
用安裝程式裝的 Zot 只讓 Builder、建置用的 Pod 和節點連進來。專案裡其他的 Pod 連不到 Zot，所以被入侵的應用程式拉不到別的專案的映像檔。
準備應用程式實際監聽的連接埠。要公開網站，另備可指向叢集入口的網域。

建立服務

填寫儲存庫和建置方式

開啟新增 → 從 Git 部署，在 儲存庫 填入 HTTPS 或 SSH 網址，例如 https://github.com/acme/web。

分支留空會追蹤儲存庫的預設分支。要固定追蹤 main，就在這裡填 main。

在 建置方式 選擇：

Railpack：讓建置器判斷應用程式語言。
Dockerfile：使用儲存庫裡的 Dockerfile。

在 更多設定 的 根目錄 指定要建置的資料夾，例如 apps/web。選擇 Dockerfile 時，Dockerfile 欄位的路徑從這個根目錄算起，留空使用 Dockerfile。

設定執行方式

確認名稱，並填入 連接埠。例如程式監聽 8080，這裡就填 8080。Zeabur 也會加入 PORT=8080。已自行設定 PORT 時，以你的值為準。

背景服務不接受連線時，把 連接埠 留空。要讓網站對外開放，開啟 公開網域 並確認網域。DNS 與 HTTPS 的設定見加入公開網域。

在 更多設定 分開填入：

環境變數：容器執行時讀取，每行一個 KEY=value。
建置變數：只有建置階段使用，例如下載私有套件的權杖。值以 BuildKit secret 傳入，不會留在映像檔裡。Dockerfile 用 RUN --mount=type=secret,id=KEY 讀取。
規格：服務執行時的 CPU 和記憶體。
安全性：Railpack 映像檔以 UID 1000 執行，預設選嚴格；Dockerfile 預設選相容。建立前仍能切換。用 Dockerfile 建置並選擇嚴格時，以數字 UID 指定非 root 使用者，例如 USER 1000。

允許讀取私有儲存庫

在 儲存庫存取 選擇符合儲存庫的方式：

選項	操作
公開儲存庫	不加認證資訊。
部署金鑰	按建立部署金鑰，複製公開金鑰，用旁邊的連結加入該儲存庫的部署金鑰，保留唯讀權限。
存取權杖	填入能讀取儲存庫的帳號與權杖，透過 HTTPS 存取。GitHub 預填 `x-access-token`，GitLab 預填 `oauth2`。

部署金鑰適用任何能用 SSH 連線的 Git 主機。Zeabur 內建 GitHub 和 GitLab 的主機金鑰，其他主機要先貼上它的主機金鑰：

在你的電腦執行表單列出的指令，例如 ssh-keyscan -t ed25519,ecdsa -p 2222 git.example.com。SSH 連接埠是 22 時沒有 -p。
把輸出貼到 主機金鑰（known_hosts），按 建立部署金鑰。Zeabur Builder 只接受 Ed25519 和 ECDSA 金鑰。
表單會列出每把主機金鑰的指紋，例如 SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU。和 Git 主機管理員公布的指紋對照，或請管理員在主機上執行 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub。指紋一樣，再把公開金鑰加到儲存庫。

儲存庫網址填 HTTPS 時，Zeabur 改用 git@主機:路徑.git 連線。SSH 不在 22 埠，或使用者不是 git 時，直接填 SSH 網址，例如 ssh://git@git.example.com:2222/acme/site.git。

檢查並套用

按 檢查變更，核對服務名稱、公開網域、機密與 Build。

套用後，開啟服務的建置分頁，查看建置狀態與各次建置的日誌。第一次建置完成前，服務的映像檔標籤是 pending，還沒有可執行的版本。建置結束十分鐘後，建置的 Pod 和日誌會一起刪除。

確認結果

在建置確認已有成功的映像檔，再到概覽確認服務就緒。若開啟公開網域，到網路打開網址，確認看到應用程式。

用 kubectl 查看 Build 和每次建置：

kubectl -n shop get build web -o wide
kubectl -n shop get buildruns
kubectl -n shop get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}'

Build 的 READY 是 True，REVISION 是建置的提交，-o wide 多出的 IMAGE 是最新的映像檔。每次建置是一個 BuildRun，PHASE 依序經過 Pending、Planning、Building，最後是 Succeeded 或 Failed，失敗原因在 REASON。Deployment 的映像檔從 :pending 換成 Build 推送的 tag，表示 Keel 已經部署新版。

新提交與自動部署

Zeabur Builder 每分鐘檢查一次分支。有新的提交時，它建置新映像檔，完成後通知 Keel，由 Keel 把服務換成新映像檔。建置紀錄會標出每次建置的觸發原因，例如新的提交或推送觸發。Builder 怎麼偵測新提交、怎麼接 Git 主機的 webhook，見 Zeabur Builder 文件。

服務建置分頁的 新建置完成後自動部署 預設開啟，控制的是建置完成後要不要馬上上線。

要馬上建置一次，在建置按 重新建置，檢查變更後套用。Builder 會用分支最新的提交。想先確認建置結果再上線，就關閉 新建置完成後自動部署，建置成功後按 部署最新版，檢查並套用映像檔變更。

要改建置資料夾、Dockerfile 或建置變數，到服務設定的建置修改，下一次建置開始生效。

用 kubectl 做同樣的事

表單建立的物件如下，存成 web.yaml 後用 kubectl -n shop apply -f web.yaml 套用。registry 位址 zot.zot.svc:5000 換成 chart 的 builds.registry，路徑固定是 <registry>/<專案>/<服務名稱>：

apiVersion: v1
kind: Secret
metadata:
  name: web-git
  labels:
    app.kubernetes.io/name: web
    builder.zeabur.com/git-credentials: "true"
type: kubernetes.io/basic-auth
stringData:
  username: x-access-token
  password: <權杖>
---
apiVersion: v1
kind: Secret
metadata:
  name: web-env
  labels:
    app.kubernetes.io/name: web
type: Opaque
stringData:
  PORT: "8080"
---
apiVersion: v1
kind: Secret
metadata:
  name: web-build-env
  labels:
    app.kubernetes.io/name: web
type: Opaque
stringData:
  NPM_TOKEN: <權杖>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app.kubernetes.io/name: web
  annotations:
    keel.sh/policy: force
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: web
  template:
    metadata:
      labels:
        app.kubernetes.io/name: web
    spec:
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: web
          image: zot.zot.svc:5000/shop/web:pending
          ports:
            - containerPort: 8080
          envFrom:
            - secretRef:
                name: web-env
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 256Mi
          readinessProbe:
            tcpSocket:
              port: 8080
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: [ALL]
---
apiVersion: v1
kind: Service
metadata:
  name: web
  labels:
    app.kubernetes.io/name: web
spec:
  selector:
    app.kubernetes.io/name: web
  ports:
    - name: http
      port: 8080
      targetPort: 8080
---
apiVersion: builder.zeabur.com/v1alpha1
kind: Build
metadata:
  name: web
  labels:
    app.kubernetes.io/name: web
spec:
  builderRef: railpack
  source:
    git:
      url: https://github.com/acme/web.git
      ref: main
    credentialsRef:
      name: web-git
  output:
    image: zot.zot.svc:5000/shop/web
  env:
    - name: NPM_TOKEN
      valueFrom:
        secretKeyRef:
          name: web-build-env
          key: NPM_TOKEN
  notify:
    - type: keel
      url: http://keel.keel.svc.cluster.local:9300/v1/webhooks/native

web-git 只在私有儲存庫用存取權杖時需要，Build 用 spec.source.credentialsRef 指向它，標籤 builder.zeabur.com/git-credentials: "true" 讓 Zeabur Builder 讀得到。公開儲存庫拿掉這個機密和 credentialsRef。
web-build-env 和 Build 的 spec.env 只在有建置變數時需要。
Deployment 先用不存在的 :pending tag，第一次建置完成後由 Keel 換掉。keel.sh/policy: force 就是 新建置完成後自動部署。
用 Dockerfile 建置時，builderRef 改成 dockerfile，需要時在 spec.source.git 加 contextDir 和 dockerfile。ref 留空時，表單寫 HEAD，追蹤預設分支。

改用部署金鑰時，自己產生金鑰，把公開金鑰加到儲存庫，再把私密金鑰和 known_hosts 放進 kubernetes.io/ssh-auth 機密。Build 的 url 改成 SSH 網址，例如 git@github.com:acme/web.git：

ssh-keygen -t ed25519 -N '' -C web-deploy -f ./web-deploy
ssh-keyscan -t ed25519,ecdsa github.com > known_hosts
kubectl -n shop create secret generic web-git --type=kubernetes.io/ssh-auth \
  --from-file=ssh-privatekey=./web-deploy --from-file=known_hosts=./known_hosts
kubectl -n shop label secret web-git app.kubernetes.io/name=web builder.zeabur.com/git-credentials=true

建置之後的動作也都是一般的 kubectl 指令：

介面動作	kubectl
重新建置	`kubectl -n shop annotate build web --overwrite builder.zeabur.com/rebuild="$(date -u +%Y-%m-%dT%H:%M:%SZ)"`
關閉新建置完成後自動部署	`kubectl -n shop annotate deployment web keel.sh/policy-`
開啟新建置完成後自動部署	`kubectl -n shop annotate deployment web keel.sh/policy=force`
部署最新版	`kubectl -n shop set image deployment/web web="$(kubectl -n shop get build web -o jsonpath='{.status.latestImage}')"`

移除 Zeabur 之後，Zeabur Builder 和 Keel 仍會繼續建置和部署，它們不需要 Zeabur。

建置或部署停住時

畫面上的情況	接著做
從 Git 部署提示缺少 registry 或 Keel	到元件安裝。registry 也可以由管理員在 Zeabur chart 設定 `builds.registry`。
儲存庫存取遭拒	使用部署金鑰時，在建置按顯示部署金鑰，確認已加到正確的儲存庫。使用權杖時，檢查讀取範圍與有效期限。修正後重新建置。
找不到分支或建置器	依建置頁的原因檢查儲存庫分支，以及叢集內對應的 Railpack 或 Dockerfile 建置器。
建置成功，服務仍使用舊映像檔	檢查新建置完成後自動部署和 Keel 狀態，或按部署最新版手動套用。
容器啟動後沒有回應	查看服務日誌，確認程式監聽的連接埠與表單相同，再查看網路的連線檢查。

刪除服務

在服務右上角的更多選 刪除服務。檢查將刪除與保留的物件再套用。沒有其他服務使用同一個 Build 時，刪除流程也會刪除它。表單建立的 Git 認證機密，在沒有其他 Build 使用時才一起刪除。

若使用部署金鑰，另到 Git 主機移除這次加入的公開金鑰。若建立了專用權杖，也到 Git 主機撤銷它。