# 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 注解