# EasyAI 本地 kind 部署指南

本目录用于在本机通过 kind 部署 EasyAI，验证 Kubernetes YAML 是否可以正常渲染、创建资源、拉起 Pod，并完成前端和核心接口访问。

本地部署会在 kind 集群中同时启动以下依赖：

| 依赖 | 说明 |
| --- | --- |
| MongoDB | 主服务本地业务数据，数据库名为 `aidraw` |
| Redis | 队列、缓存、WebSocket 集群状态 |
| RabbitMQ | 本地消息队列 |
| PostgreSQL/pgvector | Agent 治理和记忆服务数据库 |

本地数据使用 `emptyDir`，删除 Pod 或集群后数据可能丢失。本地部署只用于验证，不代表生产高可用方案。

## 1. 本机准备

以下命令均在仓库根目录执行。如果当前已经在仓库根目录，可以跳过这一步；如果当前在本 README 所在目录，执行：

```bash
cd ../../..
```

确认 Docker 正在运行：

```bash
docker version
```

确认已有 `kubectl`：

```bash
kubectl version --client
```

安装 kind：

```bash
brew install kind
```

确认 kind 可用：

```bash
kind version
```

建议本机至少预留：

| 资源 | 建议 |
| --- | --- |
| CPU | 4 核以上 |
| 内存 | 12 GB 以上 |
| 磁盘 | 20 GB 以上 |

如果本机是 Apple Silicon，且某些镜像没有 arm64 版本，可能出现 `ImagePullBackOff`、`exec format error` 或 Pod 无法启动。遇到这种情况，先查看失败镜像和 Pod 事件，生产环境请使用 amd64 节点池或多架构镜像。

## 2. 创建 kind 集群

如果本机还没有 `easyai` 集群，执行：

```bash
kind create cluster --name easyai
```

如果之前已经创建过同名集群，并且希望从干净环境重新部署，执行：

```bash
kind delete cluster --name easyai
kind create cluster --name easyai
```

切换到 kind 集群：

```bash
kubectl config use-context kind-easyai
```

确认当前 context 和节点：

```bash
kubectl config current-context
kubectl get nodes -o wide
```

当前 context 应该是：

```text
kind-easyai
```

## 3. 部署前检查

渲染本地 YAML：

```bash
kubectl kustomize k8s/overlays/local > /tmp/easyai-local.yaml
```

检查资源类型：

```bash
grep '^kind:' /tmp/easyai-local.yaml
```

准备 dry-run 需要的 namespace：

```bash
kubectl create namespace easyai-local --dry-run=client -o yaml | kubectl apply -f -
```

执行服务端 dry-run：

```bash
kubectl apply --dry-run=server -f /tmp/easyai-local.yaml
```

如果只想检查 YAML 是否能被本地解析，也可以执行：

```bash
kubectl apply --dry-run=client -f /tmp/easyai-local.yaml
```

## 4. 部署 EasyAI

执行部署：

```bash
kubectl apply -k k8s/overlays/local
```

查看 namespace：

```bash
kubectl get ns easyai-local
```

查看资源：

```bash
kubectl -n easyai-local get deploy,svc,pods
```

等待依赖和应用启动：

```bash
for d in mongo redis rabbitmq easyai-pgvector easyai-server easyai-web ws-gateway video-edit sandbox easyai-asg agent-memory; do
  kubectl -n easyai-local rollout status deploy/$d --timeout=15m
done
```

确认 Pod 状态：

```bash
kubectl -n easyai-local get pods -o wide
```

所有核心 Pod 都应进入 `Running`，并且 `READY` 数量正常。

## 5. 本地端口转发

本地前端配置使用 `127.0.0.1`，因此需要在本机打开端口转发。

建议打开 5 个终端窗口，并分别保持以下命令运行。

终端 1：

```bash
kubectl -n easyai-local port-forward svc/easyai-web 3010:3010
```

终端 2：

```bash
kubectl -n easyai-local port-forward svc/easyai-server 3001:3001
```

终端 3：

```bash
kubectl -n easyai-local port-forward svc/ws-gateway 3002:3002
```

终端 4：

```bash
kubectl -n easyai-local port-forward svc/easyai-asg 3003:3003
```

终端 5：

```bash
kubectl -n easyai-local port-forward svc/agent-memory 3004:3004
```

端口被占用时，先查看占用进程：

```bash
lsof -iTCP:3010 -sTCP:LISTEN
lsof -iTCP:3001 -sTCP:LISTEN
lsof -iTCP:3002 -sTCP:LISTEN
lsof -iTCP:3003 -sTCP:LISTEN
lsof -iTCP:3004 -sTCP:LISTEN
```

停止占用进程后，重新执行对应的 `port-forward`。

## 6. 访问验证

确认主服务：

```bash
curl -i http://127.0.0.1:3001/health
```

确认 ASG：

```bash
curl -i http://127.0.0.1:3003/health
```

确认 Agent Memory：

```bash
curl -i http://127.0.0.1:3004/health
```

打开前端：

```bash
open http://127.0.0.1:3010
```

本地默认管理员账号：

```text
admin / 123456
```

如果页面可以打开，但接口失败，请先确认 `3001`、`3002`、`3003`、`3004` 的 `port-forward` 仍在运行。

## 7. 查看状态和日志

查看 Service：

```bash
kubectl -n easyai-local get svc
```

查看 Endpoints：

```bash
kubectl -n easyai-local get endpoints easyai-web easyai-server ws-gateway easyai-asg agent-memory mongo redis rabbitmq easyai-pgvector
```

查看应用日志：

```bash
kubectl -n easyai-local logs deploy/easyai-server --tail=200
kubectl -n easyai-local logs deploy/ws-gateway --tail=200
kubectl -n easyai-local logs deploy/easyai-asg --tail=200
kubectl -n easyai-local logs deploy/agent-memory --tail=200
```

查看集群事件：

```bash
kubectl -n easyai-local get events --sort-by=.lastTimestamp | tail -80
```

## 8. 更新本地部署

如果代码仓库或镜像更新后需要重新部署，执行：

```bash
git pull
kubectl apply -k k8s/overlays/local

kubectl -n easyai-local rollout restart \
  deploy/easyai-web \
  deploy/easyai-server \
  deploy/ws-gateway \
  deploy/video-edit \
  deploy/sandbox \
  deploy/easyai-asg \
  deploy/agent-memory

for d in easyai-server easyai-web ws-gateway video-edit sandbox easyai-asg agent-memory; do
  kubectl -n easyai-local rollout status deploy/$d --timeout=15m
done
```

说明：应用镜像使用 `latest`，远端镜像更新后需要 `rollout restart` 才会重新创建 Pod 并拉取镜像。

## 9. 常见问题

### kubectl 连接不到集群

检查 context：

```bash
kubectl config get-contexts
kubectl config current-context
```

切换回本地 kind 集群：

```bash
kubectl config use-context kind-easyai
```

### Pod 一直 Pending

查看原因：

```bash
kubectl -n easyai-local describe pod <PodName>
```

常见原因：

- 本机 CPU 或内存不足。
- Docker 没有足够可用资源。
- 镜像架构和本机架构不匹配。

### ImagePullBackOff

查看具体镜像：

```bash
kubectl -n easyai-local get pod <PodName> -o jsonpath='{.spec.containers[*].image}'
```

查看事件：

```bash
kubectl -n easyai-local describe pod <PodName>
```

常见原因：

- 本机网络无法访问 `registry.cn-shanghai.aliyuncs.com`。
- 镜像 tag 不存在。
- 镜像没有当前 CPU 架构版本。

### CrashLoopBackOff

查看日志：

```bash
kubectl -n easyai-local logs <PodName> --all-containers --previous --tail=200
kubectl -n easyai-local logs <PodName> --all-containers --tail=200
```

常见原因：

- 依赖服务还没 Ready。
- MongoDB、Redis、RabbitMQ 或 PostgreSQL 初始化较慢。
- 镜像启动时执行数据库迁移失败。

可以先等依赖 Ready，再重启应用 Pod：

```bash
kubectl -n easyai-local rollout restart deploy/easyai-server deploy/easyai-asg deploy/agent-memory
```

### easyai-server Mongo 认证失败

如果 `easyai-server` 日志出现：

```text
MongoServerError: Authentication failed
UserNotFound: Could not find user "username" for db "admin"
```

通常是 MongoDB 首次初始化账号过程中被重启，导致 `/data/db` 已经非空但 root 用户没有创建完成。本地 overlay 使用 `emptyDir`，可以直接重建 Mongo Pod，让它按当前 Secret 重新初始化：

```bash
kubectl -n easyai-local delete pod -l app.kubernetes.io/name=mongo
kubectl -n easyai-local wait --for=condition=Ready pod -l app.kubernetes.io/name=mongo --timeout=5m
kubectl -n easyai-local rollout restart deploy/easyai-server deploy/easyai-web
```

### 端口转发断开

`kubectl port-forward` 会受到本地网络、终端关闭和 Pod 重启影响，断开后重新执行即可。

如果重新执行仍失败，先确认 Service 有 endpoints：

```bash
kubectl -n easyai-local get endpoints easyai-web easyai-server ws-gateway easyai-asg agent-memory
```

### 前端打开但接口不通

确认所有 `port-forward` 正在运行：

```bash
lsof -iTCP:3010 -sTCP:LISTEN
lsof -iTCP:3001 -sTCP:LISTEN
lsof -iTCP:3002 -sTCP:LISTEN
lsof -iTCP:3003 -sTCP:LISTEN
lsof -iTCP:3004 -sTCP:LISTEN
```

重新验证接口：

```bash
curl -i http://127.0.0.1:3001/health
curl -i http://127.0.0.1:3003/health
curl -i http://127.0.0.1:3004/health
```

## 10. 清理本地环境

删除 EasyAI 本地部署：

```bash
kubectl delete -k k8s/overlays/local
```

如果不再需要本地 kind 集群：

```bash
kind delete cluster --name easyai
```