taiji-AI-PAD/k8s/README.md

AKS 部署指南

本文档说明如何将 taiji-AI-PAD 部署到 Azure Kubernetes Service (AKS)。

前置要求

1. Azure CLI 已安装并登录 (az login)
2. kubectl 已安装
3. Docker 已安装
4. AKS 集群 已创建
5. Azure Container Registry (ACR) 已创建（用于存储 Docker 镜像）

重要变更

数据库配置

• PostgreSQL 数据库已更新为 taiji.postgres.database.azure.com
• 请确保在 secrets.yaml 中更新数据库连接字符串

部署步骤

1. 准备环境变量

设置以下环境变量（或直接在脚本中替换）：

export ACR_NAME="your-acr-name"
export AKS_RESOURCE_GROUP="your-resource-group"
export AKS_CLUSTER_NAME="your-aks-cluster-name"

2. 更新 Secret 配置

重要： 在部署前，必须更新 secrets.yaml 文件中的敏感信息：

# 数据库连接字符串 - 已更新为 taiji 数据库
DATABASE_URL: "postgresql+asyncpg://taiji:YOUR_PASSWORD@taiji.postgres.database.azure.com:5432/postgres?sslmode=require"

# Redis 连接字符串
REDIS_URL: "rediss://:YOUR_REDIS_PASSWORD@taiji.southeastasia.redis.azure.net:10000/0?ssl_cert_reqs=none"

# 其他 API 密钥
OPENROUTER_API_KEY: "YOUR_OPENROUTER_API_KEY"
RAPIDAPI_KEY: "YOUR_RAPIDAPI_KEY"
# ... 等等

3. 创建 Secret

有两种方式创建 Secret：

方式 1: 使用 kubectl 命令（推荐用于测试）

kubectl create secret generic taiji-secrets \
  --from-literal=DATABASE_URL="postgresql+asyncpg://taiji:PASSWORD@taiji.postgres.database.azure.com:5432/postgres?sslmode=require" \
  --from-literal=ASYNC_DATABASE_URL="postgresql+asyncpg://taiji:PASSWORD@taiji.postgres.database.azure.com:5432/postgres?sslmode=require" \
  --from-literal=REDIS_URL="rediss://:REDIS_PASSWORD@taiji.southeastasia.redis.azure.net:10000/0?ssl_cert_reqs=none" \
  --from-literal=SECRET_KEY="zsbgnw" \
  --from-literal=ENCRYPTION_KEY="zsbgnw" \
  --from-literal=LITELLM_MASTER_KEY="sk-taiji-master-key" \
  --from-literal=OPENROUTER_API_KEY="YOUR_KEY" \
  --from-literal=OPENROUTER_BASE_URL="https://openrouter.ai/api/v1" \
  --from-literal=RAPIDAPI_KEY="YOUR_KEY" \
  --from-literal=RAPIDAPI_HOST="YOUR_HOST" \
  -n taiji-ai

方式 2: 使用 Azure Key Vault（推荐用于生产环境）

# 安装 Key Vault CSI 驱动
az aks enable-addons --addons azure-keyvault-secrets-provider --name $AKS_CLUSTER_NAME --resource-group $AKS_RESOURCE_GROUP

# 创建 SecretProviderClass（参考 Azure 文档）

4. 运行部署脚本

cd k8s
chmod +x deploy.sh
./deploy.sh $ACR_NAME $AKS_RESOURCE_GROUP $AKS_CLUSTER_NAME

或者手动执行步骤：

# 1. 获取 AKS 凭据
az aks get-credentials --resource-group $AKS_RESOURCE_GROUP --name $AKS_CLUSTER_NAME

# 2. 创建命名空间
kubectl apply -f namespace.yaml

# 3. 构建并推送镜像
az acr login --name $ACR_NAME
docker build -t $ACR_NAME.azurecr.io/taiji-mcp-server:latest ../services/mcp-server
docker push $ACR_NAME.azurecr.io/taiji-mcp-server:latest
# ... 其他服务类似

# 4. 更新 Deployment 文件中的 ACR 名称
sed -i "s/YOUR_ACR_NAME/$ACR_NAME/g" *.yaml

# 5. 创建 ACR 拉取 Secret
kubectl create secret docker-registry acr-secret \
  --docker-server=$ACR_NAME.azurecr.io \
  --docker-username=$(az acr credential show --name $ACR_NAME --query username -o tsv) \
  --docker-password=$(az acr credential show --name $ACR_NAME --query passwords[0].value -o tsv) \
  --namespace=taiji-ai

# 6. 应用配置
kubectl apply -f configmap.yaml
kubectl apply -f secrets.yaml  # 或使用上面创建的 secret

# 7. 部署服务（按依赖顺序）
kubectl apply -f nats.yaml
kubectl apply -f litellm-gateway.yaml
kubectl apply -f data-ingestion.yaml
kubectl apply -f mcp-server.yaml
kubectl apply -f api-gateway.yaml
kubectl apply -f monitoring.yaml  # 可选

验证部署

检查 Pod 状态

kubectl get pods -n taiji-ai

所有 Pod 应该处于 Running 状态。

检查服务状态

kubectl get services -n taiji-ai

获取 API Gateway 外部 IP

kubectl get service api-gateway-service -n taiji-ai

访问 http://<EXTERNAL-IP>/health 验证服务是否正常。

查看日志

# 查看 MCP Server 日志
kubectl logs -f deployment/mcp-server -n taiji-ai

# 查看 Data Ingestion 日志
kubectl logs -f deployment/data-ingestion -n taiji-ai

# 查看所有 Pod 日志
kubectl logs -f -l app=mcp-server -n taiji-ai

服务架构

Internet
   |
   v
[LoadBalancer] API Gateway (Nginx)
   |
   +---> MCP Server (3 replicas)
   +---> Data Ingestion (2 replicas)
   +---> LiteLLM Gateway (2 replicas)
   |
   v
[NATS] (消息队列)
   |
   v
[Azure PostgreSQL] (taiji.postgres.database.azure.com)
[Azure Redis] (taiji.southeastasia.redis.azure.net)

扩缩容

手动扩缩容

# 扩展 MCP Server 到 5 个副本
kubectl scale deployment mcp-server --replicas=5 -n taiji-ai

# 扩展 Data Ingestion 到 3 个副本
kubectl scale deployment data-ingestion --replicas=3 -n taiji-ai

自动扩缩容（HPA）

# 为 MCP Server 创建 HPA
kubectl autoscale deployment mcp-server \
  --cpu-percent=70 \
  --min=3 \
  --max=10 \
  -n taiji-ai

更新部署

更新镜像

# 1. 构建新镜像
docker build -t $ACR_NAME.azurecr.io/taiji-mcp-server:v1.1.0 ../services/mcp-server
docker push $ACR_NAME.azurecr.io/taiji-mcp-server:v1.1.0

# 2. 更新 Deployment
kubectl set image deployment/mcp-server \
  mcp-server=$ACR_NAME.azurecr.io/taiji-mcp-server:v1.1.0 \
  -n taiji-ai

# 3. 查看滚动更新状态
kubectl rollout status deployment/mcp-server -n taiji-ai

回滚

# 查看历史版本
kubectl rollout history deployment/mcp-server -n taiji-ai

# 回滚到上一个版本
kubectl rollout undo deployment/mcp-server -n taiji-ai

# 回滚到指定版本
kubectl rollout undo deployment/mcp-server --to-revision=2 -n taiji-ai

故障排查

Pod 无法启动

# 查看 Pod 详情
kubectl describe pod <pod-name> -n taiji-ai

# 查看事件
kubectl get events -n taiji-ai --sort-by='.lastTimestamp'

镜像拉取失败

# 检查 ACR Secret
kubectl get secret acr-secret -n taiji-ai

# 验证 ACR 登录
az acr login --name $ACR_NAME

数据库连接问题

# 检查 Secret 中的数据库 URL
kubectl get secret taiji-secrets -n taiji-ai -o yaml

# 测试数据库连接（在 Pod 内）
kubectl exec -it <pod-name> -n taiji-ai -- bash
# 然后测试数据库连接

监控

Prometheus

访问 Prometheus（需要端口转发）：

kubectl port-forward service/prometheus-service 9090:9090 -n taiji-ai

然后访问 http://localhost:9090

Grafana

访问 Grafana（需要端口转发）：

kubectl port-forward service/grafana-service 3000:3000 -n taiji-ai

然后访问 http://localhost:3000（用户名/密码: admin/admin）

清理

# 删除所有资源
kubectl delete namespace taiji-ai

# 或删除特定服务
kubectl delete -f mcp-server.yaml
kubectl delete -f data-ingestion.yaml
# ... 等等

注意事项

1. 数据库已更新为 taiji：确保 secrets.yaml 中的数据库连接字符串指向 taiji.postgres.database.azure.com
2. 不影响本地 Docker：此部署完全独立于本地 docker-compose 环境
3. 存储类：PVC 使用 managed-premium 存储类，确保 AKS 集群支持
4. 资源限制：根据实际需求调整各服务的资源请求和限制
5. 安全：生产环境建议使用 Azure Key Vault 管理密钥

支持

如有问题，请查看：

• Kubernetes 日志：kubectl logs -n taiji-ai
• Pod 事件：kubectl describe pod -n taiji-ai
• 服务状态：kubectl get all -n taiji-ai