8.6 KiB
EasyAI 本地 kind 部署指南
本目录用于在本机通过 kind 部署 EasyAI，验证 Kubernetes YAML 是否可以正常渲染、创建资源、拉起 Pod，并完成前端和核心接口访问。
本地部署会在 kind 集群中同时启动以下依赖：
| 依赖 | 说明 |
|---|---|
| MongoDB | 主服务本地业务数据 |
| Redis | 队列、缓存、WebSocket 集群状态 |
| RabbitMQ | 本地消息队列 |
| PostgreSQL/pgvector | Agent 治理和记忆服务数据库 |
本地数据使用 emptyDir，删除 Pod 或集群后数据可能丢失。本地部署只用于验证，不代表生产高可用方案。
1. 本机准备
以下命令均在仓库根目录执行。如果当前已经在仓库根目录，可以跳过这一步；如果当前在本 README 所在目录，执行：
cd ../../..
确认 Docker 正在运行：
docker version
确认已有 kubectl：
kubectl version --client
安装 kind：
brew install kind
确认 kind 可用：
kind version
建议本机至少预留：
| 资源 | 建议 |
|---|---|
| CPU | 4 核以上 |
| 内存 | 12 GB 以上 |
| 磁盘 | 20 GB 以上 |
如果本机是 Apple Silicon，且某些镜像没有 arm64 版本，可能出现 ImagePullBackOff、exec format error 或 Pod 无法启动。遇到这种情况，先查看失败镜像和 Pod 事件，生产环境请使用 amd64 节点池或多架构镜像。
2. 创建 kind 集群
如果本机还没有 easyai 集群，执行：
kind create cluster --name easyai
如果之前已经创建过同名集群，并且希望从干净环境重新部署，执行：
kind delete cluster --name easyai
kind create cluster --name easyai
切换到 kind 集群：
kubectl config use-context kind-easyai
确认当前 context 和节点：
kubectl config current-context
kubectl get nodes -o wide
当前 context 应该是：
kind-easyai
3. 部署前检查
渲染本地 YAML：
kubectl kustomize k8s/overlays/local > /tmp/easyai-local.yaml
检查资源类型：
grep '^kind:' /tmp/easyai-local.yaml
准备 dry-run 需要的 namespace：
kubectl create namespace easyai-local --dry-run=client -o yaml | kubectl apply -f -
执行服务端 dry-run：
kubectl apply --dry-run=server -f /tmp/easyai-local.yaml
如果只想检查 YAML 是否能被本地解析，也可以执行：
kubectl apply --dry-run=client -f /tmp/easyai-local.yaml
4. 部署 EasyAI
执行部署：
kubectl apply -k k8s/overlays/local
查看 namespace：
kubectl get ns easyai-local
查看资源：
kubectl -n easyai-local get deploy,svc,pods
等待依赖和应用启动：
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 状态：
kubectl -n easyai-local get pods -o wide
所有核心 Pod 都应进入 Running，并且 READY 数量正常。
5. 本地端口转发
本地前端配置使用 127.0.0.1，因此需要在本机打开端口转发。
建议打开 5 个终端窗口，并分别保持以下命令运行。
终端 1：
kubectl -n easyai-local port-forward svc/easyai-web 3010:3010
终端 2：
kubectl -n easyai-local port-forward svc/easyai-server 3001:3001
终端 3：
kubectl -n easyai-local port-forward svc/ws-gateway 3002:3002
终端 4：
kubectl -n easyai-local port-forward svc/easyai-asg 3003:3003
终端 5：
kubectl -n easyai-local port-forward svc/agent-memory 3004:3004
端口被占用时，先查看占用进程：
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. 访问验证
确认主服务：
curl -i http://127.0.0.1:3001/health
确认 ASG：
curl -i http://127.0.0.1:3003/health
确认 Agent Memory：
curl -i http://127.0.0.1:3004/health
打开前端：
open http://127.0.0.1:3010
本地默认管理员账号：
admin / 123456
如果页面可以打开，但接口失败，请先确认 3001、3002、3003、3004 的 port-forward 仍在运行。
7. 查看状态和日志
查看 Service：
kubectl -n easyai-local get svc
查看 Endpoints：
kubectl -n easyai-local get endpoints easyai-web easyai-server ws-gateway easyai-asg agent-memory mongo redis rabbitmq easyai-pgvector
查看应用日志：
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
查看集群事件：
kubectl -n easyai-local get events --sort-by=.lastTimestamp | tail -80
8. 更新本地部署
如果代码仓库或镜像更新后需要重新部署，执行：
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：
kubectl config get-contexts
kubectl config current-context
切换回本地 kind 集群：
kubectl config use-context kind-easyai
Pod 一直 Pending
查看原因：
kubectl -n easyai-local describe pod <PodName>
常见原因：
- 本机 CPU 或内存不足。
- Docker 没有足够可用资源。
- 镜像架构和本机架构不匹配。
ImagePullBackOff
查看具体镜像：
kubectl -n easyai-local get pod <PodName> -o jsonpath='{.spec.containers[*].image}'
查看事件：
kubectl -n easyai-local describe pod <PodName>
常见原因：
- 本机网络无法访问
registry.cn-shanghai.aliyuncs.com。 - 镜像 tag 不存在。
- 镜像没有当前 CPU 架构版本。
CrashLoopBackOff
查看日志：
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：
kubectl -n easyai-local rollout restart deploy/easyai-server deploy/easyai-asg deploy/agent-memory
easyai-server Mongo 认证失败
如果 easyai-server 日志出现：
MongoServerError: Authentication failed
UserNotFound: Could not find user "username" for db "admin"
通常是 MongoDB 首次初始化账号过程中被重启，导致 /data/db 已经非空但 root 用户没有创建完成。本地 overlay 使用 emptyDir，可以直接重建 Mongo Pod，让它按当前 Secret 重新初始化：
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：
kubectl -n easyai-local get endpoints easyai-web easyai-server ws-gateway easyai-asg agent-memory
前端打开但接口不通
确认所有 port-forward 正在运行：
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
重新验证接口：
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 本地部署：
kubectl delete -k k8s/overlays/local
如果不再需要本地 kind 集群：
kind delete cluster --name easyai