feat: 添加 Dockerfile、docker-compose 及 K8s kustomize 部署文件

2026-06-15 16:49:35 +08:00
parent fd1bac551c
commit eeea55e9e4
18 changed files with 587 additions and 0 deletions
@@ -0,0 +1,118 @@
+# GraphRAG Studio — Kubernetes 部署指南
+
+## 目录结构
+
+```
+k8s/
+├── base/                              # 共享资源（所有环境通用）
+│   ├── kustomization.yaml
+│   ├── backend-deployment.yaml
+│   ├── backend-service.yaml
+│   ├── frontend-deployment.yaml
+│   ├── frontend-service.yaml
+│   └── persistent-volume-claims.yaml
+├── overlays/
+│   ├── test/                          # 测试环境
+│   │   ├── kustomization.yaml
+│   │   ├── namespace.yaml             # → graphrag-test
+│   │   └── ingress.yaml               # → test-graphrag.plfai.cn
+│   └── prod/                          # 生产环境
+│       ├── kustomization.yaml
+│       ├── namespace.yaml             # → graphrag-prod
+│       ├── replicas-patch.yaml        # → 后端 2 副本
+│       └── ingress.yaml               # → graphrag.plfai.cn
+└── README.md
+```
+
+## 环境差异
+
+| 项目 | test | prod |
+|------|------|------|
+| 命名空间 | `graphrag-test` | `graphrag-prod` |
+| 前端域名 | `test-graphrag.plfai.cn` | `graphrag.plfai.cn` |
+| 后端域名 | `test-graphrag-backend.plfai.cn` | `graphrag-backend.plfai.cn` |
+| 后端副本 | 1 | 2 |
+| 资源名前缀 | `test-` | `prod-` |
+| ConfigMap / Secret | 各自独立 | 各自独立 |
+
+## 架构
+
+```
+浏览器 → Ingress
+  ├── test-graphrag.plfai.cn        ──→  graphrag-test/frontend:80
+  ├── test-graphrag-backend.plfai.cn ──→  graphrag-test/backend:8000
+  ├── graphrag.plfai.cn             ──→  graphrag-prod/frontend:80
+  └── graphrag-backend.plfai.cn     ──→  graphrag-prod/backend:8000
+```
+
+## 部署
+
+### 1. 配置密钥
+
+```bash
+# 编辑 test 环境 Secret
+vim k8s/overlays/test/kustomization.yaml
+# 修改 secretGenerator.literals 中的实际 Key
+
+# 编辑 prod 环境 Secret
+vim k8s/overlays/prod/kustomization.yaml
+# 修改 secretGenerator.literals 中的实际 Key
+```
+
+### 2. 构建镜像
+
+```bash
+# 在项目根目录执行
+docker build -t graphrag-backend:latest  -f backend/Dockerfile  .
+docker build -t graphrag-frontend:latest -f frontend/Dockerfile .
+```
+
+### 3. 部署
+
+```bash
+# 部署测试环境
+kubectl apply -k k8s/overlays/test
+
+# 部署生产环境
+kubectl apply -k k8s/overlays/prod
+```
+
+### 4. 预览生成的 YAML（不实际部署）
+
+```bash
+kubectl kustomize k8s/overlays/test
+kubectl kustomize k8s/overlays/prod
+```
+
+### 5. 验证
+
+```bash
+# 检查所有 Pod
+kubectl -n graphrag-test get pods
+kubectl -n graphrag-prod get pods
+
+# 检查 Ingress
+kubectl -n graphrag-test get ingress
+kubectl -n graphrag-prod get ingress
+
+# 测试
+curl -s https://test-graphrag.plfai.cn                             # 前端
+curl -s https://test-graphrag-backend.plfai.cn/api/v1/health        # 后端
+# 生产
+curl -s https://graphrag.plfai.cn                                   # 前端
+curl -s https://graphrag-backend.plfai.cn/api/v1/health             # 后端
+```
+
+### 6. 删除
+
+```bash
+kubectl delete -k k8s/overlays/test
+kubectl delete -k k8s/overlays/prod
+```
+
+## 注意事项
+
+1. **Secret 安全**：Kustomize 的 `secretGenerator` 输出为 base64 编码，生产建议配合 External Secrets Operator 或 Sealed Secrets
+2. **PVC**：base 中 PVC 使用 `ReadWriteOnce`，prod 后端 2 副本需确保存储类支持，或改用对象存储
+3. **Ingress Controller**：集群需已安装 nginx-ingress-controller
+4. **TLS**：当前 Ingress 未配置 TLS，生产环境请添加 cert-manager 注解