agent_management/ARM64_BUILD_GUIDE.md

# Agent Manager ARM64 构建和部署指南

本文档说明如何在 ARM64 架构的 AKS 集群上构建和部署 Agent Manager 项目。

## 前置要求

1. **Docker** (支持 buildx)
2. **kubectl** (已配置连接到 AKS 集群)
3. **Azure CLI** (已登录)
4. **Azure Container Registry (ACR)** 访问权限

## 快速开始

### 方法 1: 使用快速构建脚本（推荐）

```bash
# 一键构建并部署
./build-and-deploy-arm64.sh
```

### 方法 2: 使用完整部署脚本

```bash
# 构建镜像并部署
./scripts/deploy-to-k8s-arm64.sh

# 或跳过构建，仅部署
./scripts/deploy-to-k8s-arm64.sh --skip-build
```

## 详细步骤

### 1. 配置 Docker Buildx

确保 Docker Buildx 已启用并配置：

```bash
# 检查 buildx
docker buildx version

# 创建 ARM64 builder（如果不存在）
docker buildx create --name arm64-builder --use --driver docker-container
docker buildx inspect --bootstrap
```

### 2. 登录 Azure Container Registry

```bash
ACR_NAME="agnettaiji"
az acr login --name ${ACR_NAME}
```

### 3. 构建 ARM64 镜像

```bash
ACR_NAME="agnettaiji"
IMAGE_NAME="agent-manager"
IMAGE_TAG="latest-arm64"
FULL_IMAGE_NAME="${ACR_NAME}.azurecr.io/${IMAGE_NAME}:${IMAGE_TAG}"

docker buildx build \
    --platform linux/arm64 \
    -f Dockerfile \
    -t ${FULL_IMAGE_NAME} \
    --push \
    .
```

### 4. 部署到 Kubernetes

确保 AKS 集群中有 ARM64 节点：

```bash
# 检查节点架构
kubectl get nodes -o wide

# 查看节点标签
kubectl get nodes --show-labels | grep arch
```

部署应用：

```bash
# 创建命名空间（如果不存在）
kubectl apply -f k8s/agent-manager-namespace.yaml

# 创建 ACR Secret（用于拉取镜像）
ACR_NAME="agnettaiji"
ACR_USERNAME=$(az acr credential show --name ${ACR_NAME} --query username -o tsv)
ACR_PASSWORD=$(az acr credential show --name ${ACR_NAME} --query passwords[0].value -o tsv)

kubectl create secret docker-registry acr-secret \
    --namespace=agent-manager \
    --docker-server=${ACR_NAME}.azurecr.io \
    --docker-username=${ACR_USERNAME} \
    --docker-password=${ACR_PASSWORD} \
    --dry-run=client -o yaml | kubectl apply -f -

# 部署应用
kubectl apply -f k8s/agent-manager-deployment.yaml
kubectl apply -f k8s/agent-manager-service.yaml
```

### 5. 验证部署

```bash
# 查看 Pod 状态
kubectl get pods -n agent-manager -o wide

# 查看 Pod 详细信息（确认调度到 ARM64 节点）
kubectl describe pod -n agent-manager -l app=agent-manager

# 查看日志
kubectl logs -n agent-manager -l app=agent-manager -f

# 查看服务
kubectl get svc -n agent-manager
```

## 配置说明

### 镜像配置

- **镜像仓库**: `agnettaiji.azurecr.io`
- **镜像名称**: `agent-manager`
- **ARM64 标签**: `latest-arm64`

### 节点选择器

部署配置中已设置节点选择器，确保 Pod 调度到 ARM64 节点：

```yaml
nodeSelector:
  kubernetes.io/arch: arm64
```

### 资源限制

默认资源配置：
- **请求**: CPU 200m, 内存 256Mi
- **限制**: CPU 500m, 内存 512Mi

可根据需要调整 `k8s/agent-manager-deployment.yaml` 中的资源配置。

## 故障排查

### 问题 1: 镜像拉取失败

**症状**: Pod 状态为 `ImagePullBackOff`

**解决**:
1. 检查 ACR Secret 是否正确创建
2. 确认 ACR 已附加到 AKS: `az aks update --name <aks-name> --resource-group <rg> --attach-acr <acr-name>`
3. 检查镜像标签是否正确

### 问题 2: Pod 无法调度

**症状**: Pod 状态为 `Pending`

**解决**:
1. 检查集群中是否有 ARM64 节点: `kubectl get nodes -l kubernetes.io/arch=arm64`
2. 检查节点选择器配置是否正确
3. 如果节点有污点，需要配置相应的容忍度

### 问题 3: 构建失败

**症状**: `docker buildx build` 失败

**解决**:
1. 确保 Docker Buildx 已正确安装和配置
2. 检查网络连接（推送镜像需要）
3. 确认 ACR 登录状态: `az acr login --name <acr-name>`

## 更新部署

更新镜像后，需要重启 Pod 以使用新镜像：

```bash
# 方法 1: 删除 Pod（Deployment 会自动创建新的）
kubectl delete pod -n agent-manager -l app=agent-manager

# 方法 2: 滚动更新
kubectl rollout restart deployment/agent-manager -n agent-manager

# 方法 3: 更新镜像标签
kubectl set image deployment/agent-manager \
    agent-manager=agnettaiji.azurecr.io/agent-manager:latest-arm64 \
    -n agent-manager
```

## 相关文件

- `Dockerfile` - Docker 镜像构建文件
- `k8s/agent-manager-deployment.yaml` - Kubernetes 部署配置
- `k8s/agent-manager-service.yaml` - Kubernetes 服务配置
- `scripts/deploy-to-k8s-arm64.sh` - 完整部署脚本
- `build-and-deploy-arm64.sh` - 快速构建和部署脚本