# opsx-loki 部署到 Kubernetes

## 文件

| 文件 | 说明 |
|---|---|
| `namespace.yaml` | `log` 命名空间（已有可跳过） |
| `secret.example.yaml` | JWT/ENCRYPTION 密钥模板（建议用 `kubectl create secret` 命令创建，不要提交真实值） |
| `pvc.yaml` | 平台数据卷（30Gi，默认 StorageClass） |
| `deployment.yaml` | 平台本体，**单副本 + Recreate** |
| `service.yaml` | ClusterIP `opsx-loki:8080` |
| `ingress.yaml` | 可选，按云厂商的 ingressClass 调整 |

## 部署步骤

```bash
# 1) 密钥（只生成一次，之后复用；丢失会导致已保存的凭证无法解密）
kubectl -n log create secret generic opsxloki-secrets \
  --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \
  --from-literal=ENCRYPTION_KEY="$(openssl rand -hex 32)"

# 2) 数据卷 + 平台
kubectl apply -f kubernetes/namespace.yaml
kubectl apply -f kubernetes/pvc.yaml
# 修改 deployment.yaml 里的 image 为实际仓库地址后：
kubectl apply -f kubernetes/deployment.yaml
kubectl apply -f kubernetes/service.yaml

# 3) 可选：Ingress（不需要就跳过，继续走外部 WAF 回源）
kubectl apply -f kubernetes/ingress.yaml
```

## 持久化（重要）

- `/app/data` 挂 PVC，保存 `opsxloki.json`、`kubeconfigs/`、`known_hosts`。
- **必须 `replicas: 1` + `strategy: Recreate`**：JSON DB 是单写者；滚动更新时两个 Pod 同时挂同一个 RWO PVC 会互相覆盖。
- DB 写入本身是原子的（临时文件 + fsync + rename），容器被杀不会写坏文件。
- 备份建议用 CSI VolumeSnapshot（AWS EBS / 腾讯 CBS / 华为 EVS / 阿里云 ESSD 都支持同一套 `snapshot.storage.k8s.io` API）：

```yaml
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: opsxloki-data-20261025
  namespace: log
spec:
  volumeSnapshotClassName: <集群的 snapshotClass>
  source:
    persistentVolumeClaimName: opsxloki-data
```

## 多云兼容

| 项 | 做法 |
|---|---|
| 存储类 | `pvc.yaml` 不写 `storageClassName`，用集群默认 SC；没有默认 SC 时填对应云的 SC 名（AWS `gp3` / 腾讯 `cbs` / 华为 `csi-disk` / 阿里云 `alicloud-disk-essd`） |
| 镜像仓库 | `deployment.yaml` 的 `image` 填目标云可拉的仓库（Harbor / ACR / TCR / SWR） |
| Loki 存储 | 平台已支持 S3 / OSS / COS / OBS，均为 S3 兼容，无需云厂商 SDK |
| 查询链路 | 平台与 Loki 同集群时，数据源选「集群服务」（namespace `log`、service `loki`、port `3100`），无需 Ingress/WAF |

## 与外部实例的关系

平台的 JSON DB 单写者，**不要两个实例共用同一份数据卷**。要么：
- 集群内新实例 + 迁移旧 `opsxloki.json`（停旧实例后拷贝）；或
- 保留外部 229 实例做带外管理，集群内实例使用独立数据卷（两套数据）。

## 日志

- 平台**只写 stdout**（Go/GIN 默认），不写日志文件；`kubectl logs` / `docker logs` 可直接看，Pod 部署无需额外配置。
- Docker Compose：已配置 `json-file` 轮转 `max-size=50m`、`max-file=5`。
- Kubernetes：由 kubelet 统一轮转，节点级配置建议：
  ```yaml
  # /var/lib/kubelet/config.yaml
  containerLogMaxSize: 50Mi
  containerLogMaxFiles: 5
  ```
  也可以用 kubelet 启动参数 `--container-log-max-size=50Mi --container-log-max-files=5`。
- Loki / Promtail 同样输出到 stdout，由容器运行时轮转；不要在容器内写业务日志文件。
- 应用自身的部署日志写在 DB（`deployment_logs`），可在部署详情里查看，不占容器日志空间。