taiji-AI-PAD/k8s/DEPLOYMENT_GUIDE.md

Taiji AI-PAD Kubernetes 部署指南

本文档说明如何将 Taiji AI-PAD 部署到不同的 AKS 环境。

环境概览

环境	AKS 集群	资源组	命名空间	数据库	Redis
测试	testagnet	taiji-ai-test	taiji-ai-test	taiji	testagnet.redis.cache.windows.net
生产	taiji-ai-pda	taiji-ai-pda	taiji-ai	taiji_prod	taiji2026.southeastasia.redis.azure.net

目录结构

k8s/
├── test/                    # 测试环境配置
│   ├── namespace.yaml       # 命名空间 (taiji-ai-test)
│   ├── configmap.yaml       # 配置映射
│   ├── secrets.yaml         # 密钥配置 (taiji 数据库, testagnet Redis)
│   ├── mcp-server.yaml      # MCP Server 部署
│   ├── data-ingestion.yaml  # Data Ingestion 部署
│   ├── nats.yaml            # NATS 消息队列
│   ├── api-gateway.yaml     # API Gateway (Nginx)
│   ├── monitoring.yaml      # Prometheus 监控
│   ├── ingress.yaml         # Ingress 配置
│   ├── deploy.sh            # Linux/Mac 部署脚本
│   └── deploy.bat           # Windows 部署脚本
│
├── prod/                    # 生产环境配置
│   ├── namespace.yaml       # 命名空间 (taiji-ai)
│   ├── configmap.yaml       # 配置映射
│   ├── secrets.yaml         # 密钥配置 (taiji_prod 数据库, taiji2026 Redis)
│   ├── mcp-server.yaml      # MCP Server 部署
│   ├── data-ingestion.yaml  # Data Ingestion 部署
│   ├── nats.yaml            # NATS 消息队列
│   ├── api-gateway.yaml     # API Gateway (Nginx)
│   ├── monitoring.yaml      # Prometheus 监控
│   ├── ingress.yaml         # Ingress 配置
│   ├── deploy.sh            # Linux/Mac 部署脚本
│   └── deploy.bat           # Windows 部署脚本
│
└── (旧配置文件 - 保留作为参考)

快速部署

前置条件

1. 安装 Azure CLI (az)
2. 安装 kubectl
3. 安装 Docker
4. 登录 Azure: az login

部署到测试环境 (testagnet)

Windows:

cd k8s\test
deploy.bat

Linux/Mac:

cd k8s/test
chmod +x deploy.sh
./deploy.sh

部署到生产环境 (taiji-ai-pda)

Windows:

cd k8s\prod
deploy.bat

Linux/Mac:

cd k8s/prod
chmod +x deploy.sh
./deploy.sh

⚠️ 警告: 生产环境部署需要确认，请谨慎操作！

手动部署步骤

如果需要手动部署，请按以下步骤操作：

1. 获取 AKS 凭据

测试环境:

az aks get-credentials --resource-group testagnet --name testagnet --overwrite-existing

生产环境:

az aks get-credentials --resource-group taiji-ai-pda --name taiji-ai-pda --overwrite-existing

2. 构建并推送镜像

# 登录 ACR
az acr login --name taiji

# 构建镜像
docker build -t taiji.azurecr.io/mcp-server:latest ./services/mcp-server/
docker build -t taiji.azurecr.io/data-ingestion:latest ./services/data-ingestion/

# 推送镜像
docker push taiji.azurecr.io/mcp-server:latest
docker push taiji.azurecr.io/data-ingestion:latest

3. 部署 Kubernetes 资源

测试环境:

kubectl apply -f k8s/test/namespace.yaml
kubectl apply -f k8s/test/secrets.yaml
kubectl apply -f k8s/test/configmap.yaml
kubectl apply -f k8s/test/nats.yaml
kubectl apply -f k8s/test/data-ingestion.yaml
kubectl apply -f k8s/test/mcp-server.yaml
kubectl apply -f k8s/test/ingress.yaml

生产环境:

kubectl apply -f k8s/prod/namespace.yaml
kubectl apply -f k8s/prod/secrets.yaml
kubectl apply -f k8s/prod/configmap.yaml
kubectl apply -f k8s/prod/nats.yaml
kubectl apply -f k8s/prod/data-ingestion.yaml
kubectl apply -f k8s/prod/mcp-server.yaml
kubectl apply -f k8s/prod/ingress.yaml

验证部署

查看 Pod 状态

测试环境:

kubectl get pods -n taiji-ai-test

生产环境:

kubectl get pods -n taiji-ai

查看服务

测试环境:

kubectl get svc -n taiji-ai-test

生产环境:

kubectl get svc -n taiji-ai

查看日志

# 测试环境
kubectl logs -f deployment/mcp-server -n taiji-ai-test

# 生产环境
kubectl logs -f deployment/mcp-server -n taiji-ai

配置差异

测试环境 vs 生产环境

配置项	测试环境	生产环境
APP_ENV	test	production
LOG_LEVEL	DEBUG	INFO
DEBUG	true	false
数据库	taiji	taiji_prod
Redis	testagnet.redis.cache.windows.net:6380	taiji2026.southeastasia.redis.azure.net:10000
MCP Server 副本数	1	2
HPA 最大副本数	3	10
PayPal 环境	sandbox	production
资源限制	较低	较高

故障排除

Pod 无法启动

1. 检查镜像是否存在:

   az acr repository show-tags --name taiji --repository mcp-server
   

2. 检查 ACR 拉取凭据:

   kubectl get secret acr-secret -n <namespace>
   

3. 查看 Pod 事件:

   kubectl describe pod <pod-name> -n <namespace>
   

数据库连接失败

1. 检查 Secret 配置:

   kubectl get secret taiji-secrets -n <namespace> -o yaml
   

2. 验证数据库连接字符串格式

Redis 连接失败

1. 确认 Redis 实例状态
2. 检查 SSL 配置是否正确
3. 验证密码是否正确

回滚

如需回滚到上一版本:

kubectl rollout undo deployment/mcp-server -n <namespace>
kubectl rollout undo deployment/data-ingestion -n <namespace>

联系方式

如有问题，请联系开发团队。