admin
347f9dcae5
后端域名 (-backend.plfai.cn) 不需要前端，location / 应直接代理到 backend:8000， 否则 /docs /redoc /openapi.json 被错误转发到前端 nginx 导致 504。
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. 配置密钥
# 编辑 test 环境 Secret
vim k8s/overlays/test/kustomization.yaml
# 修改 secretGenerator.literals 中的实际 Key
# 编辑 prod 环境 Secret
vim k8s/overlays/prod/kustomization.yaml
# 修改 secretGenerator.literals 中的实际 Key
2. 构建镜像
# 在项目根目录执行
docker build -t graphrag-backend:latest -f backend/Dockerfile .
docker build -t graphrag-frontend:latest -f frontend/Dockerfile .
3. 部署
# 部署测试环境
kubectl apply -k k8s/overlays/test
# 部署生产环境
kubectl apply -k k8s/overlays/prod
4. 预览生成的 YAML（不实际部署）
kubectl kustomize k8s/overlays/test
kubectl kustomize k8s/overlays/prod
5. 验证
# 检查所有 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. 删除
kubectl delete -k k8s/overlays/test
kubectl delete -k k8s/overlays/prod
注意事项
- Secret 安全：Kustomize 的
secretGenerator输出为 base64 编码，生产建议配合 External Secrets Operator 或 Sealed Secrets - PVC：base 中 PVC 使用
ReadWriteOnce，prod 后端 2 副本需确保存储类支持，或改用对象存储 - Ingress Controller：集群需已安装 nginx-ingress-controller
- TLS：当前 Ingress 未配置 TLS，生产环境请添加 cert-manager 注解