427 lines
8.6 KiB
Markdown
427 lines
8.6 KiB
Markdown
# 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
|
||
```
|