用 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（见备份服务端密钥）。