245 lines
7.5 KiB
Markdown
245 lines
7.5 KiB
Markdown
# 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`。
|