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. 准备环境变量

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

```bash
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` 文件中的敏感信息：

```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 命令（推荐用于测试）

```bash
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（推荐用于生产环境）

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

# 创建 SecretProviderClass（参考 Azure 文档）
```

### 4. 运行部署脚本

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

或者手动执行步骤：

```bash
# 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 状态

```bash
kubectl get pods -n taiji-ai
```

所有 Pod 应该处于 `Running` 状态。

### 检查服务状态

```bash
kubectl get services -n taiji-ai
```

### 获取 API Gateway 外部 IP

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

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

### 查看日志

```bash
# 查看 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)
```

## 扩缩容

### 手动扩缩容

```bash
# 扩展 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）

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

## 更新部署

### 更新镜像

```bash
# 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
```

### 回滚

```bash
# 查看历史版本
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 无法启动

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

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

### 镜像拉取失败

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

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

### 数据库连接问题

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

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

## 监控

### Prometheus

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

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

然后访问 `http://localhost:9090`

### Grafana

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

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

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

## 清理

```bash
# 删除所有资源
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`