opsx
5e59347c40
=== 0. 【严重】修复上一版引入的死锁（平台写路径全卡死）===
上一版把保留期读取写成 `GetRetentionSettings()`（内部 db.RLock()），
却在 `db.Lock()` 已持有的情况下调用（recordDelivery / RecordAudit 的裁剪路径）。
Go 的 sync.RWMutex **不可重入** → 第一次写投递历史/审计日志就永久死锁。
现象：登录 28 秒返回空（登录也要写审计）、所有写接口挂住。
go build / go vet / 之前的单测（不触发写路径）全都查不出来。
修法：
- 拆出 retentionFromDBLocked(db) / alertDeliveryRetentionLocked(db) /
auditLogRetentionLocked(db)，调用方已持锁时用无锁版本
- upsertSettingLocked 里**不能**用 db.NextID()（内部 d.mu.Lock()，同样死锁），
改为锁内自算 max(id)+1
- 新增 retention_test.go：持写锁调用裁剪函数，2 秒超时未返回即判死锁
实测修复后：登录 103ms（原 28000ms）、panic/deadlock 命中 0。
=== 1. 平台数据保留期可配（系统设置 → 通用配置 → 日志保留时间）===
新增 GET/PUT /api/v1/settings/retention：
alertDeliveryDays 告警发送历史保留天数，默认 7（原写死"最近 50 条"）
auditLogDays 审计日志保留天数，默认 90（原写死常量）
保存后立即按新策略裁剪一次，不必等下次触发。
校验：发送历史 1~365 天、审计 1~3650 天，超出返回明确中文原因（不是 500）。
注意与「Loki 日志保留期」区分：那个是部署级配置（组件部署 → 保留策略）。
=== 2. 发送历史：50 条硬上限 → 保留 7 天 ===
后端 Deliveries 接口原来写死 `len(out) < 50`，现在按保留期取（响应上限 500 可调），
标题改为「发送历史（保留 N 天）」，N 从设置里读。
=== 3. 菜单「日志服务」→「组件部署」===
=== 4. 分析页：去掉「全部命名空间」+ 改手动刷新 ===
- 移除「全部命名空间」选项：{namespace=~".+"} 要扫全集群（约 370GB/天），
一次分析几十秒，得不偿失；历史值 __all__ 也会被忽略并回退到策略/第一个 ns
- 筛选改为「选择值 / 已生效值」分离：切换命名空间或时间范围**不再自动查询**，
只把刷新按钮点亮并提示「筛选条件已改，点刷新生效」；
点一次才应用并取数。
原因：一次分析要跑多条 count_over_time，切一下下拉就重查一轮，
快速连点会把 Loki 打满（并发护栏 429），还拖慢别人。
=== 实测（9739c7c092e7）===
登录 103ms / token 273 字符
GET retention → {alertDeliveryDays:7, auditLogDays:90}
PUT 0 天 → 400「告警发送历史保留天数需在 1~365 之间」
平台日志 panic/deadlock 命中 0
go test ./... 全绿（含 2 个新死锁回归用例）
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. 生成密钥并启动
export JWT_SECRET=$(openssl rand -hex 32) # >= 32 字符
export ENCRYPTION_KEY=$(openssl rand -hex 32) # >= 32 字节
docker compose up -d
docker compose ps # 等待 healthy
未设置这两个变量时容器会拒绝启动,避免不安全的默认部署。
打开 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