LokiStack/README.md

# LokiStack — Loki 日志管理平台

一个轻量级的 **Gin + React + JSON 文件存储** 单体平台:通过 kubeconfig 或 SSH 把 Grafana Loki
部署到 Kubernetes 集群或裸金属主机,并内置日志采集管理、LogQL 查询与告警。单体二进制约 13MB,零外部依赖。

> 面向 AI 编码代理:`CLAUDE.md` / `AGENTS.md` 记录了架构约定与常用命令,两份内容一致,修改其一请同步另一份。

## 功能特性

- **Kubernetes 集群管理** — kubeconfig/Token 接入,自动校验连通性,节点与工作负载概览
- **SSH 主机管理** — 密码或密钥认证,主机信息探测
- **存储配置** — S3、OSS、COS、OBS、MinIO、RustFS 等对象存储后端
- **一键部署 Loki** — `k8s-yaml` / `host-binary` / `host-docker` 三种模式,部署日志实时查看
- **日志采集器** — 主机 Promtail、Kubernetes DaemonSet、Fluent Bit Sidecar,采集命名空间与 app 标签可配
- **内置日志查询** — LogQL 高亮补全、直方图、标签过滤、Live Tail,无需 Grafana
- **日志告警** — 告警规则 + 飞书(Lark)卡片通知
- **用户与 LDAP** — 两级用户角色(admin/普通),支持 LDAP 对接与导入
- **安全** — Argon2 密码哈希、AES-GCM(HKDF 派生)凭证加密、JWT 鉴权、非 root 容器

---

## 快速开始

### 前置条件

- Docker Engine 24.0+ 与 Docker Compose v2+
- `openssl`(生成密钥)

> 镜像内置全部依赖(Kubernetes 操作走 client-go 直连 API Server),宿主机**无需**安装 `kubectl` / `helm`。

### 1. 一条命令启动

```bash
docker compose up -d
docker compose ps        # 等待 healthy
```

未显式提供密钥时容器自动生成随机 `JWT_SECRET` / `ENCRYPTION_KEY` 并持久化到数据卷(`$DATA_DIR/.secrets.env`),重启不变;生产环境可显式指定或使用 `docker-compose.prod.yml` 密钥文件。

未设置这两个变量时容器会**拒绝启动**,避免不安全的默认部署。

打开 `http://localhost:8080`,管理员初始密码见下一步。

### 2. 获取管理员初始密码

首次启动生成**随机密码**(不再是固定 `admin123`),同时打印到启动日志并写入数据卷
`/app/data/initial-admin-password.txt`(权限 `0600`)。**日志只打印一次,文件才是可靠来源**:

```bash
# Docker Compose
docker compose exec lokistack cat /app/data/initial-admin-password.txt

# Kubernetes
kubectl -n log exec deploy/lokistack -- cat /app/data/initial-admin-password.txt
```

- admin 首次修改密码后,该文件**自动删除**。
- 想自己指定密码:启动前设置环境变量 `ADMIN_INIT_PASSWORD`(设置后不生成随机密码、不写文件)。

### 3. 健康检查

```bash
curl http://localhost:8080/api/v1/health        # 应用级
docker inspect --format='{{.State.Health.Status}}' lokistack   # 容器级,期望 healthy
```

---

## 生产部署

推荐使用带密钥文件与 nginx 负载均衡的 `docker-compose.prod.yml`:

```bash
mkdir -p secrets
openssl rand -hex 32 > secrets/jwt_secret.txt
openssl rand -hex 32 > secrets/encryption_key.txt
chmod 600 secrets/*.txt
docker compose -f docker-compose.prod.yml up -d
```

**上线前清单**:

- [ ] 两个密钥均为密码学随机、>= 32 字节,存于 Docker Secrets 或外部保险柜(而非 env 文件)
- [ ] `.env` 与 `secrets/` 已加入 `.gitignore`
- [ ] kubeconfig 与 SSH 密钥以只读方式挂载(`:ro`)
- [ ] 健康检查通过、日志轮转与资源限制已配置(compose 默认已含)

---

## 从源码构建与开发

```bash
bash build.sh        # 构建单体二进制 frontend/dist + backend/bin/lokistack
./run.sh             # 本地一键起前后端(自动注入开发用密钥)
```

开发模式(热重载,两个终端):

```bash
cd backend && go run .     # :8080;直接 go run 需先 export 两个密钥,否则拒绝启动
cd frontend && npm install && npm run dev   # :3000,/api 代理到 :8080
```

测试与 lint:

```bash
cd backend && go test ./...
cd frontend && npm run lint
```

---

## 架构

```
前端(React 19 + TypeScript + Tailwind)   [开发 :3000 / 生产由 Go 直接服务 :8080]
    |  HTTP/REST + JWT Bearer
后端(Go + Gin)[:8080]
    +---> JSON 文件数据库($DATA_DIR/lokistack.json,自动兼容历史数据文件)
    +---> client-go 直连 Kubernetes API Server(kubeconfig 认证)
    +---> SSH(golang.org/x/crypto/ssh)
    +---> Loki 部署器(YAML 清单 / 二进制 + systemd / Docker)
```

- 请求流转:**router → middleware(JWT)→ controller → service → repository(JsonDB)**。
- 数据层为单 JSON 文件 + 内存结构:防抖原子写(临时文件 → fsync → rename)、优雅关停按序落盘,
  因此**只能单实例运行**。新增数据库代码写到 `repository`(旧副本 `models/db.go` 待清理)。
- 所有响应为 `{ code, message, data }`;**禁止**直接返回原始 model,必须经 `SanitizedJSON` 脱敏
  (剔除密码、kubeconfig、私钥、token)。
- 密码 Argon2 哈希;凭证 AES-GCM 加密,密钥由 `ENCRYPTION_KEY` 经 HKDF 派生(>= 32 字节)。
- 更细的分层与约定见 `CLAUDE.md` / `AGENTS.md` 与 `docs/web-ui-guide/`。

### 部署模式

| 模式 | 目标 | 说明 |
|------|------|------|
| `k8s-yaml` | Kubernetes 集群 | 原生清单(StatefulSet/ConfigMap/Service,PVC 持久化) |
| `host-binary` | Linux 主机 | SSH 部署二进制 + systemd |
| `host-docker` | Linux 主机 | SSH 拉起 Loki 容器,配置与数据落在主机固定目录 |

### 存储后端

| 类型 | Endpoint 示例 |
|------|---------------|
| S3 | `s3.amazonaws.com` |
| OSS | `oss-cn-hangzhou.aliyuncs.com` |
| MinIO | `http://minio:9000` |
| RustFS | `http://rustfs:8080` |

---

## API 接口

Base URL `/api/v1`,除登录/健康外均需 JWT。代表性接口(完整列表见 `backend/routers/router.go`):

| 方法 | 接口 | 说明 |
|------|------|------|
| POST | `/auth/login` | 登录,返回 access + refresh token |
| GET/POST | `/clusters`、`/hosts`、`/storages` | 集群 / 主机 / 存储配置管理(含 `:id` 增删改) |
| POST | `/clusters/:id/validate`、`/hosts/:id/validate` | 连通性校验 |
| GET/POST | `/deployments`、`/collectors` | Loki 部署与采集策略管理 |
| POST | `/deployments/:id/deploy|stop|restart` | 部署生命周期 |
| POST | `/deployments/:id/retention` | 修改日志保留期并应用 |
| GET | `/deployments/:id/logs`、`/deployments/stats` | 部署日志 / 统计 |
| POST | `/logs/query|histogram|labels` | 内置日志查询(代理关联的 Loki) |
| GET/POST | `/users`、`/settings/ldap/*` | 用户管理与 LDAP 对接(仅 admin) |

---

## 环境变量

### 必需

| 变量 | 说明 |
|------|------|
| `JWT_SECRET` | JWT 签名密钥,>= 32 字符 |
| `ENCRYPTION_KEY` | AES 凭证加密密钥,>= 32 字节 |

### 可选

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SERVER_PORT` | `8080` | HTTP 端口 |
| `DATA_DIR` | `/app/data` | 数据目录 |
| `ADMIN_INIT_PASSWORD` | 随机生成 | 指定管理员初始密码 |
| `KUBECONFIG` | `/home/lokistack/.kube/config` | 容器内 kubeconfig 路径 |

支持 Docker Secrets 文件注入:`JWT_SECRET_FILE` / `ENCRYPTION_KEY_FILE` 指向 secret 文件路径即可
(用法见 `docker-compose.prod.yml` 与 `docker-entrypoint.sh`)。

---

## 安全

- **鉴权**:JWT(access 2h + refresh 7 天轮换);改密/重置密码递增 `TokenVersion`,旧 token 立即失效。
- **用户体系**:两级角色(admin/普通),用户管理仅 admin;登录接口带 IP 限流。
- **容器**:非 root 用户(`lokistack:1000`)、`no-new-privileges`、丢弃全部多余 capabilities、
  资源限制(CPU 2 核 / 内存 512MB / PIDs 100 上限)与日志轮转。
- **密钥**:绝不提交版本控制;生产用 Docker Secrets 或密钥保险柜;轮换用 `openssl rand -hex 32`。

---

## 故障排查

**容器立即退出** — 多为密钥缺失。`docker compose logs` 应有
`Missing required security environment variables`;设置两个密钥后重启。

**健康检查失败** — `docker inspect --format='{{.State.Health}}' lokistack` 查状态,
`docker compose logs --tail=50` 查原因。

**kubeconfig 不可访问** — 核对宿主侧权限(`chmod 600 ~/.kube/config`)与挂载路径:
`docker exec lokistack ls -la /home/lokistack/.kube/`。

---

## 许可证

MIT License