部署

两种部署模式

本地：Docker Compose

框架仓库附带两套完整的技术栈——应用、PostgreSQL（含 pgvector）、Redis、Vault 以及一套可观测性栈：

docker compose -f compose-grafana.yml up --build      # Grafana stack
docker compose -f compose-opensearch.yml up --build   # OpenSearch Dashboards stack

脚手架生成的项目会拥有各自的 compose.yml（app + postgres + redis + vault）——参见你的第一个智能体。

生产环境：基于 Terraform 的 Kubernetes 部署

Agent-Lab 提供了 Terraform 脚本，用于在 Kubernetes 上部署应用及其依赖。本演练出于参考目的使用 Minikube 集群——真实部署请使用可用于生产环境的集群。

前提条件

• Terraform
• kubectl
• jq

搭建 Kubernetes 集群

Minikube（Linux）——分配足够的资源（参考技术栈较为庞大）：

minikube start --memory=20g --cpus=4

获取集群 IP，并将各服务域名映射到该 IP：

minikube ip
# 192.168.49.2

192.168.49.2 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

Docker Desktop（Mac / Windows）——启用其内置的 Kubernetes：

使用 Docker Desktop 时，域名通过 localhost 解析：

127.0.0.1 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

预置依赖

下面的每个模块都位于 terraform/ 中——按以下顺序，在每个目录中执行 terraform init && terraform apply 进行应用：

Keycloak 实例（09_keycloak-instance/），然后获取管理员密码：

echo "$(kubectl --namespace keycloak get secret/keycloak-initial-admin -o go-template='{{index .data "password" | base64decode}}')"

按照使用 Keycloak 进行认证配置 OIDC 连接，或者交由 12_agent-lab-auth-realm/ 模块完成（见下文）。

Vault 初始化（已应用 08_vault-instance/）——初始化并解封：

kubectl --namespace vault exec vault-0 -- vault operator init \
    -key-shares=1 \
    -key-threshold=1 \
    -format=json > cluster-keys.json

export VAULT_UNSEAL_KEY=$(jq -r ".unseal_keys_b64[]" cluster-keys.json)
kubectl --namespace vault exec vault-0 -- vault operator unseal $VAULT_UNSEAL_KEY

可观测性（可选，但推荐）——供模拟测试套件和追踪后端使用的 LLM 可观测性平台：

获取 Elastic 凭据：

echo "$(kubectl --namespace elastic get secret elasticsearch-es-elastic-user -o=jsonpath='{.data.elastic}' | base64 --decode)"

echo "$(kubectl --namespace elastic get secret/elastic-eck-apm-server-apm-token \
    -o go-template='{{index .data "secret-token" | base64decode}}')"

OpenTelemetry Collector（11_otel-instance/）——应用导出数据的 OTLP 端点（可观测性）。

LiteLLM 网关（17_litellm-instance/）——一个自托管的 OpenAI 兼容 LLM 网关，支持虚拟密钥、费用跟踪，并提供管理界面（/ui）：

echo "$(kubectl --namespace litellm get secret/litellm-masterkey -o go-template='{{index .data "masterkey" | base64decode}}')"

curl -s https://<litellm_fqdn>/health/readiness

部署 Agent-Lab

由三个模块将所有组件连接起来：

cd terraform/12_agent-lab-auth-realm/ && terraform init && terraform apply
cd terraform/15_agent-lab-dependencies/ && terraform init && terraform apply
cd terraform/16_agent-lab-instance/ && terraform init && terraform apply

关于密钥：部署会在启动时从 Vault（secret/app_secrets）读取配置——载荷中的键列在配置参考中。

Helm chart

仓库还附带一个 Helm chart charts/agent-lab，它将应用部署及其边车（sidecar）组件打包在一起：供 Web 智能体使用的无头 Chrome（CDP）、HPA、ingress、配置和服务账号。如果你已经在自行运维各项依赖，只想安装应用本身，就可以使用它。

检查清单

在宣告完成之前，请确认：

• GET /status/liveness 和 GET /status/readiness 返回 200
• GET /docs 能正常渲染，且 GET /agents/list 有响应（启用认证时需携带令牌）
• 追踪数据已到达你的 OTLP 端点（参见可观测性）
• Vault 中包含 secret/app_secrets，且含有所有载荷键
• Keycloak realm 中已有一个客户端和一个服务账号