7.5 KiB

Raw Blame History

Fischer AgentKit — K8s 部署指南

本文档指导在原生 Kubernetes 1.28+ 集群上通过 Helm Chart 部署 Fischer AgentKit。覆盖在线与离线两种安装场景，以及 Sealed Secrets / External Secrets 两种密钥后端。

1. 前置条件

组件	版本	说明
Kubernetes	>= 1.28	原生 K8s（信创 K8s / OpenShift P1 支持）
Helm	3.x	Chart 部署工具
kubectl	与集群对齐	集群操作
docker / containerd	任意	镜像构建与加载

集群需已部署以下 Operator 之一（二选一，对应 secrets.backend）：

Sealed Secrets（secrets.backend: sealed-secrets）
- 安装：helm install sealed-secrets sealed-secrets/sealed-secrets -n kube-system
- 工具：kubeseal（用于生成 encryptedData）
External Secrets Operator（secrets.backend: external-secrets）
- 安装：helm install external-secrets external-secrets/external-secrets -n kube-system
- 后端：Vault / AWS Secrets Manager / GCP Secret Manager / Azure Key Vault（运维预创建 SecretStore）

依赖中间件（Redis + PostgreSQL）需在命名空间内可达：

Redis：redis://redis:6379/0（可指向集群内 Redis 或外部托管）
PostgreSQL（含 pgvector 扩展）：postgresql+asyncpg://agentkit@postgres:5432/agentkit

ponytail: Chart 默认不部署 Redis/PostgreSQL（避免与客户已有基础设施重复）。升级路径：subchart 方式集成 bitnami/redis + bitnami/postgresql（P1）。

2. 在线安装

2.1 准备密钥

按 docs/deployment/secret-inventory.md 准备 11 个 secret slot 的明文值，然后根据所选 backend 生成密钥资源。

Sealed Secrets 方式（推荐单集群 / 离线场景）：

# 1) 写明文到临时 Secret（注意：永远不要 git commit 明文 Secret）
kubectl create secret generic agentkit-secrets --dry-run=client -o yaml \
  --from-literal=jwt-signing-key='<32字节随机串>' \
  --from-literal=api-key='<apikey>' \
  --from-literal=database-url='postgresql+asyncpg://agentkit:<pg-pwd>@postgres:5432/agentkit' \
  --from-literal=idp-signing-certs='{"feishu":"-----BEGIN CERT..."}' \
  --from-literal=third-party-api-keys='{"dashscope":"sk-...","deepseek":"sk-..."}' \
  --from-literal=tls-server-cert='<pem>' \
  --from-literal=mtls-client-cert='<pem>' \
  --from-literal=kms-hsm-pin='<pin>' \
  --from-literal=otel-exporter-token='Bearer <token>' \
  --from-literal=redis-password='<redis-pwd>' \
  --from-literal=postgres-password='<pg-pwd>' \
  > /tmp/agentkit-secret-plaintext.yaml

# 2) 用 kubeseal 加密（需 controller 已运行）
kubeseal --controller-name=sealed-secrets --controller-namespace=kube-system \
  --format yaml < /tmp/agentkit-secret-plaintext.yaml > agentkit-sealedsecret.yaml

# 3) 明文临时文件必须销毁
shred -u /tmp/agentkit-secret-plaintext.yaml

# 4) 应用 SealedSecret
kubectl apply -f agentkit-sealedsecret.yaml -n agentkit

External Secrets 方式（推荐多集群 / 云托管场景）：

# 1) 在 Vault / AWS SM / GCP SM 中预置 10 个 key（路径见 templates/external-secret.yaml remoteRef.key）
# 2) 创建 SecretStore（指向外部密钥后端）
kubectl apply -f - <<'EOF'
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: agentkit-vault-store
  namespace: agentkit
spec:
  provider:
    vault:
      server: https://vault.internal:8200
      path: secret
      auth:
        kubernetes:
          mountPath: kubernetes
          role: agentkit
EOF

# 3) Chart 安装时 secrets.backend=external-secrets 自动生成 ExternalSecret

2.2 helm install

# 创建 namespace
kubectl create namespace agentkit

# 安装（默认 sealed-secrets backend）
helm install agentkit deploy/helm/agentkit/ \
  --namespace agentkit \
  --set ingress.host=agentkit.your-domain.com \
  --set image.repository=fischer-agentkit \
  --set image.tag=0.1.0

# 或使用 External Secrets backend
helm install agentkit deploy/helm/agentkit/ \
  --namespace agentkit \
  --set secrets.backend=external-secrets \
  --set secrets.externalSecret.secretStoreName=agentkit-vault-store \
  --set ingress.host=agentkit.your-domain.com

# 或使用 override values 文件
helm install agentkit deploy/helm/agentkit/ \
  --namespace agentkit \
  -f values-prod.yaml

2.3 启用 workload identity（KMS/HSM）

helm install agentkit deploy/helm/agentkit/ \
  --namespace agentkit \
  --set workloadIdentity.enabled=true \
  --set workloadIdentity.audience=sts.your-cloud.com

3. 离线安装

离线场景（政企内网无公网）需先在联网环境打包，再拷贝到离线集群安装。

3.1 联网环境打包

cd deploy/offline
make all IMAGE_REPO=fischer-agentkit IMAGE_TAG=0.1.0
# 产物：dist/agentkit-image-0.1.0.tar.gz + dist/agentkit-0.1.0.tgz

3.2 拷贝到离线集群

# 将整个 dist/ 目录拷贝到离线集群节点（scp / U 盘 / 内网传输）
scp -r dist/ user@offline-node:/opt/agentkit/dist

3.3 离线集群安装

ssh user@offline-node
cd /path/to/deploy/offline
make install DIST_DIR=dist NAMESPACE=agentkit RELEASE=agentkit
# install.sh 会：docker load 镜像 + helm install（image.pullPolicy=Never）

4. 安装后验证

# 1) Pod 状态
kubectl get pods -n agentkit
# 期望：agentkit-xxx 1/1 Running

# 2) Service / Ingress
kubectl get svc,ingress -n agentkit

# 3) 健康检查
kubectl exec -n agentkit deploy/agentkit-agentkit -- \
  curl -s http://localhost:8001/api/v1/health
# 期望：{"status":"ok"}

# 4) Secret 已注入
kubectl exec -n agentkit deploy/agentkit-agentkit -- env | grep -E 'JWT|API_KEY|DATABASE' | sed 's/=.*/=<redacted>/'
# 期望：所有 env 都有值（不为空）

# 5) helm 状态
helm status agentkit -n agentkit

5. 故障排查

5.1 Pod CrashLoopBackOff

# 查看日志
kubectl logs -n agentkit deploy/agentkit-agentkit --tail=50

# 常见原因：
# - Secret 未注入：检查 SealedSecret 是否已解封（kubectl get sealedsecret -n agentkit）
# - DB 连接失败：检查 postgres 服务可达性 + DATABASE_URL 正确性
# - Redis 连接失败：检查 redis 服务 + REDIS_PASSWORD

5.2 SealedSecret 未解封

kubectl describe sealedsecret agentkit-secrets -n agentkit
# 若 status.conditions 显示 error，原因通常是：
# - sealed-secrets-controller 未运行（kubectl get pods -n kube-system | grep sealed-secrets）
# - 加密时用的 controller 与当前 controller 私钥不匹配（需重新 kubeseal）

5.3 ExternalSecret 同步失败

kubectl get externalsecret agentkit-secrets -n agentkit -o yaml
# 关注 status.conditions，常见：
# - SecretStore 不存在或不可达
# - Vault / SM 权限不足
# - remoteRef.key 在外部后端不存在

5.4 Ingress 不通

# 检查 ingress controller
kubectl get pods -n ingress-nginx
# 检查 TLS secret
kubectl get secret agentkit-tls -n agentkit
# 检查 DNS 解析到 ingress controller LB

6. 卸载

helm uninstall agentkit -n agentkit
kubectl delete namespace agentkit
# 注意：SealedSecret 解封后的明文 Secret 需手动删除
kubectl delete sealedsecret agentkit-secrets -n agentkit 2>/dev/null || true

7. 升级

# 镜像升级
helm upgrade agentkit deploy/helm/agentkit/ \
  --namespace agentkit \
  --set image.tag=0.2.0

# 配置变更
helm upgrade agentkit deploy/helm/agentkit/ \
  --namespace agentkit \
  -f values-prod.yaml

密钥轮换流程见 docs/deployment/key-rotation-runbook.md。

7.5 KiB Raw Blame History Unescape Escape