用 Helm 部署到 Kubernetes

爬山虎的 Helm chart 包含伺服器（API、MCP、CalDAV 和背景工作）、在同一個網址提供服務的 BostonIvy Web，以及方便入門的內建 PostgreSQL。伺服器每次發布新版本時都會發布新的 chart，位址是 oci://ghcr.io/ivylabsapp/charts/bostonivy。

開始之前

一個 Kubernetes 叢集、kubectl，以及 Helm 3.8 或更新版本（能從 OCI 儲存庫安裝 chart）。
一個 Ingress 控制器（範例中使用 ingress-nginx），以及指向它的網域。沒有的話也可以先試用，見不用 Ingress 試用。
一個具有 read:packages 權限的 GitHub 權杖。映像檔和 chart 都是 GitHub Container Registry 上的私有套件。

安裝

建立命名空間，以及拉取私有映像檔用的密鑰：

kubectl create namespace bostonivy
kubectl -n bostonivy create secret docker-registry ghcr \
  --docker-server=ghcr.io --docker-username=<你的 GitHub 使用者名稱> --docker-password=<具有 read:packages 的權杖>

讓 Helm 登入映像檔儲存庫，這樣它才能下載 chart：

echo "$GITHUB_TOKEN" | helm registry login ghcr.io -u <你的 GitHub 使用者名稱> --password-stdin

把設定寫進一個檔案，例如 values.yaml。url 必填，郵件裡的連結、分享連結、OAuth 和 OIDC 回呼都用它。

url: https://tasks.example.com
imagePullSecrets:
  - name: ghcr
ingress:
  enabled: true
  className: nginx
  annotations:
    # 即時更新走 /api/v1/realtime 上的長連線 WebSocket；上傳上限 64 MiB
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-body-size: 64m
  tls:
    - secretName: bostonivy-tls
      hosts: [tasks.example.com]

bostonivy-tls 是你網域的憑證：自行建立的 TLS Secret，或由 cert-manager 產生。

安裝：
```
helm install ivy oci://ghcr.io/ivylabsapp/charts/bostonivy --version 0.7.0 -n bostonivy -f values.yaml
```
本頁範例中的 release 叫 ivy，所以各資源名稱為 ivy-bostonivy-…。有 bostonivy-os 的簽出時，也可以從 deploy/helm/bostonivy 安裝。

建立第一個管理員

安裝完成後 Helm 也會印出這些步驟。輸入密碼時不會顯示：

printf 'Password: '; read -rs PW; echo
printf '%s\n' "$PW" | kubectl -n bostonivy exec -i deploy/ivy-bostonivy-server -- bostonivy admin create-user <使用者名稱> <電子郵件> --admin
unset PW

備份伺服器金鑰

伺服器金鑰和內建資料庫的密碼在安裝時產生，每次升級都會保留，存放在 Secret ivy-bostonivy-secrets 裡，解除安裝時 Helm 也不會刪除它。所有簽章和加密金鑰都由伺服器金鑰衍生：一旦遺失，所有人都要重新登入，加密儲存的 TOTP 和 webhook 密鑰也無法再讀取。現在就把它複製到安全的地方：

kubectl -n bostonivy get secret ivy-bostonivy-secrets -o jsonpath='{.data.auth-secret}' | base64 -d

想用自己的金鑰，可以設定 auth.secret，或者把它放進你自己管理的 Secret 的 auth-secret 鍵下，再設定 auth.existingSecret。

不用 Ingress 試用

保持 ingress.enabled 關閉，設定 auth.cookieSecure=false，然後把網頁服務轉送到本機：

kubectl -n bostonivy port-forward svc/ivy-bostonivy-web 8080:80

再開啟 http://localhost:8080。一旦改為透過 HTTPS 提供服務，就要把 auth.cookieSecure 改回 true。

設定項目

設定項目	預設值	作用
`url`	必填	使用者連到爬山虎的網址；連結、OAuth 和 OIDC 回呼都用它
`imagePullSecrets`	`[]`	拉取私有映像檔用的密鑰
`auth.secret`、`auth.existingSecret`	自動產生	伺服器金鑰，直接提供或取自你自己的 Secret（鍵為 `auth-secret`）
`auth.cookieSecure`	`true`	使用 HTTPS 時保持開啟；只有在純 http 上試用時才關閉
`database.url`、`database.existingSecret`	內建	外部的 PostgreSQL 16 或更新版本；留空則使用內建的
`postgresql.enabled`	`true`	叢集內的單一 PostgreSQL，適合試用和小規模
`mail.smtpUrl`、`mail.from`	空	例如 `smtp://user:password@host:587`，或 `log`；留空表示不寄信
`config`	空	以 TOML 撰寫的額外伺服器設定，例如 `[[auth.oidc]]` 登入提供者
`server.env`、`server.envFrom`	`[]`	其他任何 `BOSTONIVY_<區段>__<鍵>` 設定
`server.replicas`	`1`	多於一個時需要 S3 儲存和 `worker.separate`
`worker.separate`、`worker.replicas`	`false`、`1`	把背景工作（郵件、webhook、提醒、維護）放到獨立的 Pod 執行
`persistence.*`	10Gi，ReadWriteOnce	本機儲存時的附件和頭像
`web.image.tag`	`0.2.0`	要提供的 BostonIvy Web 版本
`ingress.*`	關閉	主機名稱預設取自 `url`；要允許 WebSocket 長時間讀取，即時更新才能運作

資料庫

內建的 PostgreSQL 只有一個 Pod，適合試用和小規模部署。正式環境請使用託管資料庫或 operator，並讓爬山虎指向它：

postgresql:
  enabled: false
database:
  url: postgres://bostonivy:<密碼>@db.example.com:5432/bostonivy

也可以把位址放進你自己的 Secret，再設定 database.existingSecret。爬山虎需要 PostgreSQL 16 或更新版本。

郵件、登入和其他設定

郵件： mail.smtpUrl 和 mail.from。設為 log 時郵件會寫進伺服器記錄，適合試用。

TOML 形式的伺服器設定： config 接受一段 TOML，例如登入提供者：

config: |
  [[auth.oidc]]
  id = "google"
  # 其他欄位見 bostonivy.example.toml

其他設定： server.env 接受 BOSTONIVY_<區段>__<鍵> 形式的變數；bostonivy-os 裡的 bostonivy.example.toml 列出了全部設定項目。

擴充

除了本機儲存的檔案，伺服器本身不保存狀態。要執行多個副本：

server:
  replicas: 3
  env:
    - name: BOSTONIVY_STORAGE__KIND
      value: s3
    # 再加上 bostonivy.example.toml 裡 [storage] 區段的儲存桶設定
worker:
  separate: true
persistence:
  enabled: false

檔案改存到 S3 相容儲存，而不是只能掛載到一個 Pod 的磁碟區。
worker.separate 把背景工作放到獨立的 Pod，工作只執行一次，而不是每個伺服器副本都執行。
想讓各副本共用流量限制的計數，就在 server.env 裡設定 BOSTONIVY_REDIS__URL。
即時更新、工作階段撤銷和外掛都透過 PostgreSQL 在副本之間同步，不需要其他元件。

升級與備份

用新版本的 chart 升級：

helm upgrade ivy oci://ghcr.io/ivylabsapp/charts/bostonivy --version <新版本> -n bostonivy -f values.yaml

伺服器 Pod 會滾動更新，新版本啟動時自動遷移資料庫。遷移只增不刪，搭配備份可以退回。

需要備份三樣東西：

資料庫。 使用內建 PostgreSQL 時：

kubectl -n bostonivy exec ivy-bostonivy-postgresql-0 -- pg_dump -U bostonivy bostonivy > backup.sql

附件和頭像： 檔案磁碟區，或你的儲存桶。
伺服器金鑰： auth-secret（見備份伺服器金鑰）。