• DevOps
• 云原生
• 后端

本文基于 digger 仓库 self-hosting/kubernetes/helm-charts 目录中的官方 Helm Charts 文档整理而成。OpenTaco 是 Digger 基础设施即代码（IaC）编排平台的完整形态，通过一套 Helm Charts 即可在 Kubernetes 集群中部署 Terraform 编排、漂移检测、状态管理与 Web 前端等全部服务。读完本文，你将掌握从 OCI Registry 安装 opentaco umbrella chart、配置 Cloud SQL 与各类密钥、完成测试/生产环境部署及故障排查的完整实战路径。

架构总览：一个 Umbrella Chart 编排六大服务

OpenTaco 的部署体系采用 Helmumbrella chart（聚合 Chart）模式：顶层opentaco图表本身不包含业务容器，而是通过Chart.yaml中声明的 dependencies 将多个独立子 Chart 聚合为一个可整体安装的发布单元。查看 opentaco/Chart.yaml 可以看到其依赖声明：

apiVersion: v2 name: opentaco description: OpenTaco - Complete Infrastructure-as-Code platform deployment type: application version: 0.1.2-public appVersion: "0.1.0" dependencies: - name: taco-orchestrator # Terraform 编排后端 version: "0.1.2-public" repository: "oci://ghcr.io/diggerhq/helm-charts" condition: taco-orchestrator.enabled - name: taco-statesman # IaC 状态管理 version: "0.1.2-public" condition: taco-statesman.enabled - name: taco-sidecar # 沙箱 sidecar 服务 version: "0.1.4-public" condition: taco-sidecar.enabled - name: taco-token-service # API Token 管理 version: "0.1.2-public" condition: taco-token-service.enabled - name: taco-drift # 漂移检测 version: "0.1.2-public" condition: taco-drift.enabled - name: taco-ui # React 前端 version: "0.1.3-public" condition: taco-ui.enabled

各子 Chart 均通过condition字段与 values 文件中的xxx.enabled开关联动，默认全部启用。每个子 Chart 都提供独立的 Deployment、Service、Ingress 模板，并支持useExistingSecret引用外部预创建的 Secret（详见下文"密钥管理"）。整套平台的端口规划如下：

注意：官方文档中"4 个服务"的描述是早期简版；以当前仓库为准，umbrella chart 实际编排 6 个子 Chart。安装完成后，opentaco/templates/NOTES.txt 会在终端打印每个已启用组件的状态与访问方式，例如未开启 Ingress 时会提示使用kubectl port-forward svc/taco-ui 3030:3030访问前端。

快速开始：从 OCI Registry 一键安装

Helm Charts 的开发与发布分离：代码在 digger 主仓库中维护，但发布到 GitHub Container Registry（GHCR）的 OCI Registry 供用户直接安装。快速安装步骤如下：

# 1. 获取并配置 values 文件（详见下方"部署前配置清单"） # 该文件即仓库中的 opentaco/values-test.yaml.example # 将占位符替换为你的 GCP 项目 ID 与相关设置 mv values-test.yaml.example values-test.yaml # 2. 创建命名空间 kubectl create namespace opentaco # 3. 创建四个 Secret（详见"密钥管理"章节） kubectl create secret generic ui-secrets \ --from-env-file=.secrets/ui.env -n opentaco kubectl create secret generic taco-orchestrator-secrets \ --from-env-file=.secrets/digger-backend.env -n opentaco kubectl create secret generic statesman-secrets \ --from-env-file=.secrets/statesman.env -n opentaco kubectl create secret generic drift-secrets \ --from-env-file=.secrets/drift.env -n opentaco # 4. 从 OCI Registry 安装 helm install opentaco oci://ghcr.io/diggerhq/helm-charts/opentaco \ -f values-test.yaml \ -n opentaco

公共镜像托管在ghcr.io/diggerhq下，默认无需认证即可拉取（imagePullPolicy: IfNotPresent），这也是values-test.yaml.example中注释"imagePullSecrets not needed for public GHCR images"的原因。若使用私有镜像仓库，则需要在global.imagePullSecrets中配置拉取凭据。

部署前配置清单：替换占位符

在真正部署前，必须逐项检查 values 文件中的占位符。values-test.yaml.example与values-production.yaml.example中所有YOUR-、example.com、CHANGE THIS标记都需要替换为真实值。

1. Cloud SQL 配置（statesman 使用 Cloud SQL 时）

cloudSql: enabled: true instanceConnectionName: "YOUR-PROJECT-ID:YOUR-REGION:YOUR-INSTANCE" # ❌ CHANGE THIS credentialsSecret: "cloudsql-credentials" serviceAccount: "cloudsql-sa"

替换规则：

• YOUR-PROJECT-ID→ GCP 项目 ID，例如my-prod-project
• YOUR-REGION→ Cloud SQL 实例所在区域，例如us-central1
• YOUR-INSTANCE→ Cloud SQL 实例名，例如opentaco-postgres

完整示例：my-prod-project:us-central1:opentaco-postgres。

2. 镜像仓库（可选，默认公共 GHCR）

global: imageRegistry: ghcr.io/diggerhq # ✅ 公共仓库，无需认证 # 或使用你的私有仓库： # imageRegistry: us-central1-docker.pkg.dev/YOUR-PROJECT/YOUR-REPO

公共仓库是推荐默认项；只有使用自定义构建的镜像时才需切换为私有仓库路径。从模板实现看（如 taco-orchestrator/templates/backend-deployment.yaml），镜像地址的渲染逻辑是per-chart image.registry → global.imageRegistry → ghcr.io/diggerhq三级回退，最后拼接为仓库/镜像名:tag。

3. UI Ingress 配置（生产环境自定义域名）

taco-ui: ui: ingress: enabled: false # 生产环境设为 true hosts: - host: app.opentaco.example.com # ❌ CHANGE THIS paths: - path: / pathType: Prefix tls: - secretName: opentaco-ui-tls hosts: - app.opentaco.example.com # ❌ CHANGE THIS

将app.opentaco.example.com替换为你的真实域名，并确保集群中已安装 Ingress Controller（下文"Ingress 设置"）。taco-ui/templates/ingress.yaml 展示了该配置的渲染方式：ingressClassName、tls与rules均直接来自上述 values。生产示例中还常搭配cert-manager.io/cluster-issuer: letsencrypt-prod注解自动签发 TLS 证书。

4. 服务副本数（可选，默认 1）

digger-backend: digger: replicaCount: 1 # 生产环境可增至 2+ taco-statesman: taco: replicaCount: 1 # 生产环境可增至 2+

测试/开发环境保留 1 个副本即可；生产环境建议提升到 2+ 以保障高可用。values-production.yaml.example中 orchestration、statesman、drift、ui 均设置为replicaCount: 2并配置了资源配额（requests 与 limits）。

5. 快速校验：检查残留占位符

grep -E "YOUR-|example\.com|CHANGE THIS" opentaco/values-test.yaml

只要该命令返回任何结果，就说明还有占位符未替换，部署前必须处理干净。

密钥管理：从示例文件到 Kubernetes Secret

OpenTaco 的设计原则是：敏感配置不进 values 文件，而是通过 Kubernetes Secret 注入。每个子 Chart 默认secret.useExistingSecret: true，Deployment 通过envFrom.secretRef引用外部 Secret（见 taco-statesman/templates/deployment.yaml）。

1. 复制示例文件

仓库提供了完整的示例 env 文件目录：

cp -r secrets-example/ .secrets/

2. 填充真实凭据

.secrets/目录下共四个文件，分别对应四个 Secret：

.secrets/ ├── digger-backend.env # GitHub App、数据库、Sentry 等（→ taco-orchestrator-secrets） ├── drift.env # GitHub App、数据库连接（→ drift-secrets） ├── statesman.env # Auth0、S3、PostgreSQL/Cloud SQL（→ statesman-secrets） └── ui.env # WorkOS、后端服务 URL（→ ui-secrets）

各文件关键配置项（完整示例见 secrets-example/）：

• GitHub App 凭据（digger-backend.env）：GITHUB_APP_ID、GITHUB_APP_CLIENT_ID、GITHUB_APP_CLIENT_SECRET、GITHUB_APP_PRIVATE_KEY_BASE64（Base64 编码的私钥）、GITHUB_WEBHOOK_SECRET，以及DATABASE_URL、DIGGER_ENCRYPTION_SECRET（32 字符）、DIGGER_INTERNAL_SECRET（50 字符）、DIGGER_LICENSE_KEY、PUBLIC_BASE_URL等
• Statesman（statesman.env）：S3 存储（OPENTACO_S3_BUCKET/OPENTACO_S3_REGION/OPENTACO_S3_PREFIX）、Auth0 认证（OPENTACO_AUTH_ISSUER/OPENTACO_AUTH_CLIENT_ID/OPENTACO_AUTH_CLIENT_SECRET/OPENTACO_AUTH_AUTH_URL/OPENTACO_AUTH_TOKEN_URL）、AWS 凭据（AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION/AWS_ENDPOINT，可用于 Tigris 等 S3 兼容存储）、JWT 配置（OPENTACO_TOKENS_KID/OPENTACO_TOKENS_ACCESS_TTL/OPENTACO_TOKENS_REFRESH_TTL）、OPENTACO_PUBLIC_BASE_URL、OPENTACO_OAUTH_STATE_KEY（32+ 字符随机串，用于 PKCE 流程 OAuth state 加密）、OPENTACO_SECRET_KEY（签名 Terraform Cloud 远端 backend 的上传/下载 URL，必填）
• Drift（drift.env）：DATABASE_URL、DIGGER_APP_URL、DIGGER_DRIFT_REPORTER_HOSTNAME（公共基础 URL）、DIGGER_HOSTNAME（集群内 drift 服务自调用地址，如http://opentaco-taco-drift:3004）、DIGGER_WEBHOOK_SECRET（32 字符）、GITHUB_APP_PRIVATE_KEY_BASE64
• UI（ui.env）：WorkOS 认证（WORKOS_API_KEY/WORKOS_CLIENT_ID/WORKOS_COOKIE_PASSWORD/WORKOS_WEBHOOK_SECRET/WORKOS_REDIRECT_URI）、ALLOWED_HOSTS（逗号分隔，如your-domain.com,.ngrok-free.dev,.sslip.io,localhost）、PUBLIC_URL、各后端 URL 及其 webhook 密钥

3. 创建 Kubernetes Secret

kubectl create secret generic ui-secrets \ --from-env-file=.secrets/ui.env -n opentaco kubectl create secret generic taco-orchestrator-secrets \ --from-env-file=.secrets/digger-backend.env -n opentaco kubectl create secret generic statesman-secrets \ --from-env-file=.secrets/statesman.env -n opentaco kubectl create secret generic drift-secrets \ --from-env-file=.secrets/drift.env -n opentaco

4. 更新 Secret

Secret 创建后无法直接修改内容，更新流程是"删除重建 + 滚动重启 Pod"：

# 删除旧 Secret kubectl delete secret statesman-secrets -n opentaco # 用新值重建 kubectl create secret generic statesman-secrets \ --from-env-file=.secrets/statesman.env -n opentaco # 重启 Pod 以加载新环境变量 kubectl delete pods -l app.kubernetes.io/name=statesman -n opentaco

Cloud SQL 设置：statesman 的数据库后端

Statesman 使用 Google Cloud SQL 作为数据库；backend 与 drift 则既可使用外部数据库（Supabase 等），也可复用 Cloud SQL。Cloud SQL 的连接方式不是直连公网，而是通过cloud-sql-proxy sidecar 容器将实例暴露到 Pod 的localhost:5432。

1. 创建 Cloud SQL 实例

gcloud sql instances create taco-postgres \ --database-version=POSTGRES_15 \ --tier=db-f1-micro \ --region=us-central1 \ --database-flags=max_connections=100

2. 创建数据库

gcloud sql databases create taco \ --instance=taco-postgres

3. 创建服务账号并授权

# 为 Cloud SQL proxy 创建服务账号 gcloud iam service-accounts create cloudsql-sa \ --display-name="Cloud SQL Proxy Service Account" # 授予 Cloud SQL Client 角色 gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member="serviceAccount:cloudsql-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/cloudsql.client" # 创建并下载密钥 gcloud iam service-accounts keys create cloudsql-key.json \ --iam-account=cloudsql-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

4. 创建 Cloud SQL 凭据 Secret

kubectl create secret generic cloudsql-credentials \ --from-file=credentials.json=cloudsql-key.json \ -n opentaco

5. 在 values 文件中启用 Cloud SQL

statesman: enabled: true taco: cloudSql: enabled: true instanceConnectionName: "PROJECT_ID:REGION:INSTANCE_NAME" # 例如 "dev-XXXXXXX:us-west2:taco-postgres" credentialsSecret: "cloudsql-credentials"

从模板源码（taco-statesman/templates/deployment.yaml）可以看到：启用 Cloud SQL 后，容器列表会追加cloud-sql-proxy（镜像gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.0），以--port=5432监听本地端口，并将cloudsql-credentialsSecret 中的credentials.json挂载到/secrets/cloudsql目录，通过GOOGLE_APPLICATION_CREDENTIALS环境变量注入。taco-orchestrator 的 backend-deployment.yaml 中也有完全相同的 sidecar 模式。

6. 设置 statesman.env 的数据库连接

# Cloud SQL 通过 proxy sidecar 使用 localhost 访问 OPENTACO_POSTGRES_HOST=localhost OPENTACO_POSTGRES_PORT=5432 OPENTACO_POSTGRES_USER=postgres OPENTACO_POSTGRES_PASSWORD=YOUR_DB_PASSWORD OPENTACO_POSTGRES_DBNAME=taco OPENTACO_QUERY_BACKEND=postgres

OPENTACO_QUERY_BACKEND可选值包括postgres、mssql、sqlite等；production values 中sslmode通常设为disable，因为 SSL 由 proxy 处理。Token Service 同样通过 Cloud SQL 复用同一实例（database.backend: postgres、host: 127.0.0.1、用户token_svc、库名token_service）。

部署与验证

测试环境

cd opentaco helm install opentaco . -f values-test.yaml -n opentaco

生产环境

# 审查并定制生产 values vim opentaco/values-production.yaml # 部署 helm install opentaco . -f values-production.yaml -n opentaco

生产环境与测试环境的典型差异（参考 values-production.yaml.example）：副本数提升至 2、配置资源 requests/limits、开启 UI Ingress（含 TLS 与 cert-manager 注解）、statesman 存储切换为s3并配置secretKey、drift 开启cronjobs.enabled: true、networkPolicies.enabled: true等。

验证部署

# 检查 Pod 状态 kubectl get pods -n opentaco # 查看日志 kubectl logs -f deployment/opentaco-taco-statesman -n opentaco -c statesman # 本地访问 UI kubectl port-forward svc/opentaco-taco-ui 3030:3030 -n opentaco open http://localhost:3030

仓库为子 Chart 提供了 helm-unittest 测试用例（如 taco-statesman/tests/deployment_test.yaml、taco-orchestrator/tests/deployments_test.yaml），可用helm unittest <chart>本地渲染验证模板输出是否符合预期。

服务间通信：Kubernetes DNS 与 UI 环境变量

各服务通过 Kubernetes 集群内 DNS 互相访问：

# 集群内部地址： http://opentaco-taco-orchestrator-web:3000 http://opentaco-taco-drift:3004 http://opentaco-taco-statesman:8080 http://opentaco-taco-ui:3030

这些 URL 配置在ui.env中：

ORCHESTRATOR_BACKEND_URL="http://opentaco-taco-orchestrator-web:3000" DRIFT_REPORTING_BACKEND_URL="http://opentaco-taco-drift:3004" STATESMAN_BACKEND_URL="http://opentaco-taco-statesman:8080"

服务名的拼接规则为<release-name>-<chart-name>[-web]:<port>。其中 orchestrator 的 Service 名为<release>-taco-orchestrator-web（见 backend-service.yaml）。如果以opentaco之外的名字作为 release 名安装，必须同步修改这些主机名，否则 UI 将无法访问后端。opentaco/values.yaml中taco-ui.ui.env.backends段落也内置了相同的默认值。

升级与更新

# 更新依赖 cd opentaco helm dependency update # 升级部署 helm upgrade opentaco . -f values-test.yaml -n opentaco # 需要时强制重建 Pod kubectl delete pods --all -n opentaco

由于子 Chart 依赖通过 OCI 仓库拉取，升级前执行helm dependency update可确保拉取最新版本的依赖图表。

故障排查

Pod 无法启动

# 检查 Pod 状态 kubectl get pods -n opentaco # 查看事件 kubectl describe pod POD_NAME -n opentaco # 查看日志 kubectl logs POD_NAME -n opentaco

Secret 问题

# 列出 Secret kubectl get secrets -n opentaco # 验证 Secret 内容（列出所有 key） kubectl get secret taco-orchestrator-secrets -n opentaco -o jsonpath='{.data}' | jq 'keys'

Cloud SQL 连接问题

# 查看 Cloud SQL proxy sidecar 日志 kubectl logs POD_NAME -n opentaco -c cloud-sql-proxy # 核对实例连接名 gcloud sql instances describe INSTANCE_NAME --format="value(connectionName)"

Chart 结构与外部依赖服务

Chart 目录结构

self-hosting/kubernetes/helm-charts/ ├── opentaco/ # Umbrella chart │ ├── Chart.yaml │ ├── values.yaml # 默认值 │ ├── values-test.yaml.example # 测试环境模板 │ ├── values-production.yaml.example # 生产环境模板 │ └── values.platform-reference.yaml ├── digger-backend/ # 独立版 Terraform 编排 Chart（含可选内置 PostgreSQL） ├── taco-orchestrator/ # Terraform 编排 ├── taco-statesman/ # 状态管理 ├── taco-drift/ # 漂移检测 ├── taco-ui/ # Web 前端 ├── taco-token-service/ # Token 服务 ├── taco-sidecar/ # 沙箱 sidecar ├── opentaco-platform-reference/ # 平台参考实现（Traefik + CNPG + MinIO） └── secrets-example/ # 示例密钥文件

必需的云服务与凭据

配置文件速查表

源码级补充：几个值得留意的实现细节

Orchestrator 的 Job 管理 RBAC：taco-orchestrator 需要以 Kubernetes Job 的方式在集群内派生运行任务，因此 rbac.yaml 为其创建了job-managerRole，授予对batch/jobs、pods、pods/log的读写与查看权限，并通过 RoleBinding 绑定到 ServiceAccount。生产环境若使用 GKE Workload Identity，可在digger.serviceAccount.annotations与workloadIdentity中配置 GCP 服务账号映射。

Drift 的定时处理 CronJob：当taco-drift.drift.cronjobs.enabled: true时，cronjobs.yaml 会创建两个每分钟执行一次的 CronJob（process-drift与process-notifications），使用curlimages/curl镜像以DIGGER_WEBHOOK_SECRET作 Bearer 认证，分别调用 drift 服务的/_internal/process_drift与/_internal/process_notifications接口，concurrencyPolicy: Forbid防止任务重叠。

平台参考 Chart（opentaco-platform-reference）：该 Chart 是快速验证 OpenTaco 的参考实现，安装 Traefik Ingress、CloudNativePG 操作符与共享 CNPG 集群（为 orchestrator/statesman/token 三服务创建独立数据库与凭据）、MinIO StatefulSet（默认minio.opentaco.svc.cluster.local:9000，bucketopentaco）及 bucket 初始化 Job。官方文档明确说明它不是生产蓝图的替代品——生产环境应直接使用opentacoumbrella chart，并按团队标准自行管理 Ingress、数据库生命周期与对象存储。

密钥注入的两种模式：所有子 Chart 均支持两种配置方式——在 values 中直接填写字段由 Chart 自动生成 Secret（useExistingSecret: false），或引用预创建 Secret（useExistingSecret: true，生产推荐）。后者的优势是 Secret 独立于 Helm release 生命周期，更新凭据无需helm upgrade。

• DevOps
• 云原生
• 后端