taiji-AI-PAD/k8s/DEPLOYMENT_CHECKLIST.md

AKS 部署检查清单

部署前准备

• Azure CLI 已安装并登录 (az login)
• kubectl 已安装
• Docker 已安装
• AKS 集群已创建
• Azure Container Registry (ACR) 已创建
• 已获取 ACR 名称、AKS 资源组名称、AKS 集群名称

配置更新

• 更新 secrets.yaml 中的数据库连接字符串（已改为 taiji.postgres.database.azure.com）
• 更新 secrets.yaml 中的 Redis 连接字符串
• 更新 secrets.yaml 中的所有 API 密钥（OpenRouter, RapidAPI 等）
• 确认数据库用户名和密码正确

部署步骤

方式 1: 使用自动化脚本（推荐）

cd k8s
./deploy.sh <ACR_NAME> <AKS_RESOURCE_GROUP> <AKS_CLUSTER_NAME>

方式 2: 手动部署

1. 获取 AKS 凭据

   az aks get-credentials --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME>
   

2. 创建命名空间

   kubectl apply -f namespace.yaml
   

3. 创建 Secret

   # 方式 A: 使用 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
   

4. 构建并推送 Docker 镜像

   ACR_NAME="your-acr-name"
   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
   
   docker build -t $ACR_NAME.azurecr.io/taiji-data-ingestion:latest ../services/data-ingestion
   docker push $ACR_NAME.azurecr.io/taiji-data-ingestion:latest
   
   docker build -t $ACR_NAME.azurecr.io/taiji-litellm-gateway:latest ../services/model-gateway
   docker push $ACR_NAME.azurecr.io/taiji-litellm-gateway:latest
   

5. 更新 Deployment 文件中的 ACR 名称

   sed -i "s/YOUR_ACR_NAME/$ACR_NAME/g" litellm-gateway.yaml
   sed -i "s/YOUR_ACR_NAME/$ACR_NAME/g" data-ingestion.yaml
   sed -i "s/YOUR_ACR_NAME/$ACR_NAME/g" mcp-server.yaml
   

6. 创建 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
   

7. 应用 ConfigMap

   kubectl apply -f configmap.yaml
   

8. 部署服务（按依赖顺序）

   kubectl apply -f nats.yaml
   kubectl wait --for=condition=available --timeout=300s deployment/nats -n taiji-ai
   
   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
• 检查服务状态：kubectl get services -n taiji-ai
• 获取 API Gateway 外部 IP：kubectl get service api-gateway-service -n taiji-ai
• 测试健康检查：curl http://<EXTERNAL-IP>/health
• 查看日志确认无错误：kubectl logs -f deployment/mcp-server -n taiji-ai

重要提示

1. 数据库已更新为 taiji：确保所有配置指向 taiji.postgres.database.azure.com
2. 不影响本地 Docker：此部署完全独立，不会影响本地运行的 docker-compose 环境
3. 存储类：确保 AKS 集群支持 managed-premium 存储类
4. 资源限制：根据实际需求调整各服务的资源请求和限制

故障排查

如果遇到问题：

1. 查看 Pod 详情：kubectl describe pod <pod-name> -n taiji-ai
2. 查看事件：kubectl get events -n taiji-ai --sort-by='.lastTimestamp'
3. 查看日志：kubectl logs <pod-name> -n taiji-ai
4. 检查 Secret：kubectl get secret taiji-secrets -n taiji-ai -o yaml

下一步

部署成功后：

• 配置域名和 SSL 证书（如需要）
• 设置监控告警
• 配置自动扩缩容（HPA）
• 设置备份策略