# 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 方式**（推荐单集群 / 离线场景）：

```bash
# 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 方式**（推荐多集群 / 云托管场景）：

```bash
# 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

```bash
# 创建 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）

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

## 3. 离线安装

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

### 3.1 联网环境打包

```bash
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 拷贝到离线集群

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

### 3.3 离线集群安装

```bash
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. 安装后验证

```bash
# 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

```bash
# 查看日志
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 未解封

```bash
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 同步失败

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

### 5.4 Ingress 不通

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

## 6. 卸载

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

## 7. 升级

```bash
# 镜像升级
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`。