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. 一键安装(Linux 服务器,推荐)

bash -c "$(curl -fsSL https://gitea.91ai.io/rlwj-lab/LokiStack/raw/main/scripts/quick_start.sh)"

自动下载对应架构(x86_64/arm64)的发布包,生成随机密钥并注册 systemd 服务(开机自启);重复执行即升级(数据自动备份)。安装完成后终端直接打印访问地址与初始密码。

2. Docker 一条命令

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)。日志只打印一次,文件才是可靠来源:

# 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. 健康检查

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

---

生产部署

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

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 build.sh        # 构建单体二进制 frontend/dist + backend/bin/lokistack
./run.sh             # 本地一键起前后端(自动注入开发用密钥)

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

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

测试与 lint:

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
POST	/deployments/:id/retention	修改日志保留期并应用
GET	/deployments/:id/logs、/deployments/stats	部署日志 / 统计
POST	`/logs/query	histogram
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