juwan-backend/deploy/example/OPERATOR-INSTALL-EXAMPLE.md

# Operator 安装与示例使用

本文档提供 Strimzi Operator 与 MongoDB Community Operator 的两种安装方式：

- Helm 安装
- kubectl 安装

> 示例资源文件位于 `deploy/example`，默认使用 `juwan` 命名空间。
> 请先确保你的 Operator 能 watch 到 `juwan`，否则请改 namespace 或调整 Operator watch 范围。

## 1) Strimzi Operator（Kafka）

### 1.1 使用 Helm 安装

```bash
kubectl create namespace kafka
helm repo add strimzi https://strimzi.io/charts/
helm repo update
helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator -n kafka
```

### 1.2 使用 kubectl 安装

```bash
kubectl create namespace kafka
kubectl apply -f https://strimzi.io/install/latest?namespace=kafka -n kafka
```

### 1.3 安装验证

```bash
kubectl get pods -n kafka
kubectl get crd | grep kafka.strimzi.io
```

### 1.4 应用 Kafka 示例

```bash
kubectl create namespace juwan
kubectl apply -f deploy/example/kafka-strimzi-example.yaml
kubectl get kafka,kafkatopic,kafkauser -n juwan
```

## 2) MongoDB Community Operator

### 2.1 使用 Helm 安装

```bash
kubectl create namespace mongodb
helm repo add mongodb https://mongodb.github.io/helm-charts
helm repo update
helm install mongodb-kubernetes-operator mongodb/community-operator -n mongodb
```

### 2.2 使用 kubectl 安装

```bash
kubectl create namespace mongodb
kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-kubernetes-operator/master/config/crd/bases/mongodbcommunity.mongodb.com_mongodbcommunity.yaml
kubectl apply -k https://github.com/mongodb/mongodb-kubernetes-operator/config/rbac/
kubectl apply -k https://github.com/mongodb/mongodb-kubernetes-operator/config/manager/
```

### 2.3 安装验证

```bash
kubectl get pods -n mongodb
kubectl get crd | grep mongodbcommunity.mongodb.com
```

### 2.4 应用 MongoDB 示例

```bash
kubectl create namespace juwan
kubectl apply -f deploy/example/mongodb-community-example.yaml
kubectl get mongodbcommunity -n juwan
```

## 3) MongoDB：哨兵集群与分片集群搭建

### 3.1 关于“哨兵集群”的说明

MongoDB 没有 Redis Sentinel 的独立哨兵组件。
MongoDB 的高可用由 **Replica Set（副本集）** 原生完成（自动主从切换、故障恢复）。

因此在 MongoDB 场景里，“哨兵集群”通常对应为“副本集高可用集群”。

### 3.2 MongoDB“哨兵等价”方案：副本集高可用

本仓库提供了高可用副本集 YAML：`deploy/example/mongodb-ha-replicaset-example.yaml`。

```bash
kubectl create namespace juwan
kubectl apply -f deploy/example/mongodb-ha-replicaset-example.yaml
kubectl get mongodbcommunity -n juwan
```

查看副本集状态（任选一个 Pod 进入）：

```bash
kubectl get pods -n juwan
kubectl exec -it -n juwan <mongodb-pod-name> -- mongosh --eval "rs.status()"
```

生产建议：

- 成员数保持奇数（3/5/7）
- 使用持久化卷（PVC），不要用临时盘
- 跨可用区调度（反亲和）
- 开启备份与监控

### 3.3 MongoDB 分片集群架构（Sharded Cluster）

分片集群由三层组成：

- Config Server ReplicaSet（保存分片元数据，建议 3 节点）
- Shard ReplicaSet（每个分片都是副本集，建议每分片 3 节点）
- Mongos（路由层，对业务暴露统一入口）

### 3.4 分片集群搭建步骤（kubectl 方式）

> 说明：MongoDB Community Operator 主要用于副本集管理。分片集群在社区实践中通常采用“手动编排（StatefulSet/Service）+ mongosh 初始化”。

本仓库提供了分片集群基础编排 YAML：`deploy/example/mongodb-sharded-cluster-example.yaml`。

```bash
kubectl create namespace juwan
kubectl apply -f deploy/example/mongodb-sharded-cluster-example.yaml
kubectl get pods,svc -n juwan
```

1) 部署 Config Server 副本集（3 节点）

- 使用 StatefulSet + Headless Service 部署 `mongod --configsvr --replSet cfg-rs`

1) 部署 Shard 副本集（例如 `shard1-rs`、`shard2-rs`，每个 3 节点）

- 使用 StatefulSet + Headless Service 部署 `mongod --shardsvr --replSet <shard-rs-name>`

1) 部署 Mongos 路由层

- Deployment 部署 `mongos --configdb cfg-rs/<cfg-0>:27019,<cfg-1>:27019,<cfg-2>:27019`

1) 初始化各副本集

```bash
# 初始化 Config Server RS
kubectl exec -it -n juwan <cfg-pod-0> -- mongosh --port 27019 --eval 'rs.initiate({_id:"cfg-rs",configsvr:true,members:[{_id:0,host:"cfg-0.cfg-svc.juwan.svc.cluster.local:27019"},{_id:1,host:"cfg-1.cfg-svc.juwan.svc.cluster.local:27019"},{_id:2,host:"cfg-2.cfg-svc.juwan.svc.cluster.local:27019"}]})'

# 初始化 shard1 RS
kubectl exec -it -n juwan <shard1-pod-0> -- mongosh --port 27018 --eval 'rs.initiate({_id:"shard1-rs",members:[{_id:0,host:"shard1-0.shard1-svc.juwan.svc.cluster.local:27018"},{_id:1,host:"shard1-1.shard1-svc.juwan.svc.cluster.local:27018"},{_id:2,host:"shard1-2.shard1-svc.juwan.svc.cluster.local:27018"}]})'

# 初始化 shard2 RS
kubectl exec -it -n juwan <shard2-pod-0> -- mongosh --port 27018 --eval 'rs.initiate({_id:"shard2-rs",members:[{_id:0,host:"shard2-0.shard2-svc.juwan.svc.cluster.local:27018"},{_id:1,host:"shard2-1.shard2-svc.juwan.svc.cluster.local:27018"},{_id:2,host:"shard2-2.shard2-svc.juwan.svc.cluster.local:27018"}]})'
```

1) 通过 Mongos 注册分片并启用分片

```bash
kubectl exec -it -n juwan <mongos-pod-name> -- mongosh --port 27017 --eval 'sh.addShard("shard1-rs/shard1-0.shard1-svc.juwan.svc.cluster.local:27018,shard1-1.shard1-svc.juwan.svc.cluster.local:27018,shard1-2.shard1-svc.juwan.svc.cluster.local:27018")'
kubectl exec -it -n juwan <mongos-pod-name> -- mongosh --port 27017 --eval 'sh.addShard("shard2-rs/shard2-0.shard2-svc.juwan.svc.cluster.local:27018,shard2-1.shard2-svc.juwan.svc.cluster.local:27018,shard2-2.shard2-svc.juwan.svc.cluster.local:27018")'
kubectl exec -it -n juwan <mongos-pod-name> -- mongosh --port 27017 --eval 'sh.enableSharding("appdb")'
kubectl exec -it -n juwan <mongos-pod-name> -- mongosh --port 27017 --eval 'sh.shardCollection("appdb.user_events", {"userId": "hashed"})'
```

1) 验证分片状态

```bash
kubectl exec -it -n juwan <mongos-pod-name> -- mongosh --port 27017 --eval 'sh.status()'
```

## 4) 卸载（可选）

### Strimzi（Helm 安装场景）

```bash
helm uninstall strimzi-kafka-operator -n kafka
```

### MongoDB Operator（Helm 安装场景）

```bash
helm uninstall mongodb-kubernetes-operator -n mongodb
```