初始化提交

2026-07-09 19:29:46 +08:00
commit 821ffe9e70
25 changed files with 2713 additions and 0 deletions
@@ -0,0 +1,426 @@
+# EasyAI 本地 kind 部署指南
+
+本目录用于在本机通过 kind 部署 EasyAI，验证 Kubernetes YAML 是否可以正常渲染、创建资源、拉起 Pod，并完成前端和核心接口访问。
+
+本地部署会在 kind 集群中同时启动以下依赖：
+
+| 依赖 | 说明 |
+| --- | --- |
+| MongoDB | 主服务本地业务数据 |
+| 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
+```