feat(site): homepage 落地页 + docsify 用户手册文档站(/docs /homepage 随二进制发布)

- homepage/:品牌落地页(Hero/特性/快速开始),参考 opsxapi 站点风格,绿色品牌系 - docs/:docsify 文档站 + user-guide 十篇手册(安装/向导/采集/查询/分析/告警/授权/备份/FAQ) - 后端 serveStaticDir 挂载 /docs 与 /homepage(可执行文件相对定位,独立于前端 dist)
2026-10-29 14:04:24 +08:00
1 parent b8d08ef6d1
commit 3ea7f2dcc6
@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>LokiStack 用户手册</title>
+<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='14' fill='%23059669'/%3E%3Ctext x='32' y='44' font-size='34' font-weight='800' fill='%23fff' text-anchor='middle' font-family='sans-serif'%3EL%3C/text%3E%3C/svg%3E">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
+<style>
+  :root { --theme-color: #059669; --base-font-size: 15px; }
+  body { font-family: -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif; }
+</style>
+</head>
+<body>
+<div id="app"></div>
+<script>
+  window.$docsify = {
+    name: 'LokiStack 用户手册',
+    repo: 'https://gitea.91ai.io/rlwj-lab/LokiStack',
+    homepage: 'user-guide/README.md',
+    loadSidebar: 'user-guide/_sidebar.md',
+    loadNavbar: false,
+    search: { placeholder: '搜索手册', noData: '没有匹配结果' },
+    subMaxLevel: 3,
+  };
+</script>
+<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+</body>
+</html>
@@ -0,0 +1,15 @@
+# LokiStack 用户手册
+
+LokiStack 把 Grafana Loki 日志聚合的部署、采集、查询、分析与告警收进一个平台:向导式部署到 Kubernetes 集群或裸金属主机,内置中文/英文界面,单二进制交付。
+
+## 平台能做什么
+
+- **部署 Loki**:三步向导(环境与目标 → 存储 → 部署与采集),支持 Kubernetes(YAML 直发)、裸金属二进制、主机 Docker 三种模式,不需要在平台所在机器安装 kubectl 或 Helm。
+- **采集日志**:Promtail / Fluent Bit 采集策略可视化配置,命名空间多选、app 标签来源四级回退、敏感路径拦截。
+- **查询与分析**:LogQL 高亮补全、快捷查询、Live Tail;分析页自动聚合日志量、错误与 Ingress 访问指标。
+- **告警**:内置九条应用日志规则,绑定默认通道后填入飞书 Webhook 即可接收;支持冷却与风暴抑制。
+- **运维底座**:凭证加密存储、操作审计、备份恢复、Prometheus 自监控指标。
+
+## 下一步
+
+阅读[安装与启动](install.md),或直接进入[部署向导](wizard.md)。
@@ -0,0 +1,10 @@
+- [开始](README.md)
+- [安装与启动](install.md)
+- [部署向导](wizard.md)
+- [日志采集](collectors.md)
+- [日志查询](query.md)
+- [日志分析](analysis.md)
+- [告警通知](alerts.md)
+- [查询授权](access.md)
+- [备份与恢复](backup.md)
+- [常见问题](faq.md)
@@ -0,0 +1,10 @@
+# 查询授权
+
+管理员在「日志查询 → 查询授权」用策略组控制普通用户可见的日志范围:
+
+- 策略组 = 数据源 + 允许的标签范围(命名空间 / App / Pod,均精确匹配,未选不限) + 关联用户。
+- 同一用户在同一数据源只能属于一个策略组;已在其他组的用户置灰。
+- 支持快捷的「所有人」策略(默认策略的常用形态)。
+- 授权在服务端强制执行:普通用户的查询必须以流选择器开头,策略标签自动合并,无法越权。
+
+用户管理(仅管理员)支持创建/重置密码/批量删除;LDAP 用户可在系统设置接入后导入。
@@ -0,0 +1,24 @@
+# 告警通知
+
+「日志告警」页(`/alerts`)管理规则、通知通道与发送历史。
+
+## 快速开始
+
+1. 在「通知通道」中编辑默认通道,填入飞书群机器人 Webhook 并启用。
+2. 内置九条规则默认启用并已绑定默认通道,命中阈值即发送到群。
+
+## 规则
+
+- 查询为 LogQL 日志流匹配;窗口(分钟)、阈值(条数)、冷却(分钟)三要素。
+- 内置规则已排除 Loki 自身日志(app=loki),避免告警查询日志造成自我误报。
+- 模板按钮一键填充常用规则(命名空间错误 / Ingress 4xx5xx / FATAL 等)。
+
+## 通道与发送历史
+
+- 通道支持飞书 Webhook(可选签名);可建多通道对应不同告警群。
+- 发送历史记录每次触发的命中数、投递结果与失败原因;保留天数在「系统设置 → 日志保留时间」调整。
+
+## 防刷屏机制
+
+- 单规则冷却(默认 ≥ 2 小时);全平台每小时发送上限(风暴抑制)。
+- 通道未配置/未启用时命中只记入历史,不影响规则评估。
@@ -0,0 +1,13 @@
+# 日志分析
+
+「日志分析」页(`/analysis`,管理员)自动聚合日志指标,无需手动查询:
+
+- **统计卡**:日志总量、错误行数、告警行数、活跃应用
+- **趋势折线**:总量 / 错误 / 告警随时间分布
+- **命名空间分布**:环形图
+- **应用流图**:Top 10 应用日志量堆叠
+- **每日日志量**:近 7 天按日聚合(独立于时间范围筛选)
+- **应用排行**:Top 10 应用,支持跳转查询页
+- **Ingress 访问分析**:自动识别 ingress-nginx 访问日志,PV/UV、状态码、慢请求与接口排行;未安装 ingress-nginx 时自动折叠
+
+时间范围与数据源在页面顶部切换;指标查询经服务端聚合,开销远低于拉取原始日志。
@@ -0,0 +1,23 @@
+# 备份与恢复
+
+平台状态集中在单个 JSON 文件(`$DATA_DIR/lokistack.json`),备份恢复围绕它展开。
+
+## 备份
+
+- 手动:「系统设置 → 备份」立即创建(写入 `$DATA_DIR/backups/`)。
+- 脚本:`./run.sh backup` 或 `make` 内相应目标,适合 cron 定时。
+
+## 恢复
+
+1. 上传统计备份或选择已有备份,校验后暂存。
+2. 点击应用:平台先把当前库留档(`.before-restore.*`),替换后立即在内存生效,随后建议重启进程。
+3. 恢复文件损坏时平台拒绝应用并提示。
+
+## 数据文件保护
+
+- 启动时若数据文件解析失败,原文件会以 `.corrupt-<时间戳>` 留档后再以空库启动,绝不覆盖可恢复数据。
+- 历史命名数据文件(opsxloki.json / lokideploy.json)在启动时自动升级为 lokistack.json。
+
+## 自监控
+
+`/api/v1/metrics` 输出 Prometheus 指标(HTTP、DB 落盘、告警引擎、Go runtime);「平台监控」页(`/monitor`,管理员)提供可视化快照。
@@ -0,0 +1,18 @@
+# 日志采集
+
+「日志采集」页管理采集策略:主机采集(Promtail)与集群采集(DaemonSet / Fluent Bit Sidecar)。
+
+## 采集范围
+
+- **集群采集**:命名空间多选(默认全集群);app 标签按 `app.kubernetes.io/name → app → controller 名 → pod 名` 四级回退,可自定义来源标签与 app 白名单收敛日志量。
+- **主机采集**:填写业务日志路径(glob 通配,如 `/var/log/app/*.log`);系统日志自动探测(syslog / messages)。
+- 敏感路径(/etc/shadow、私钥、/proc 等)会被平台拦截,防止主机凭据进入日志平台。
+
+## 编辑与下发
+
+保存后点击「部署」下发到目标;「预览 YAML」可先核对将生成的 promtail 配置。修改后同样以「部署」生效。
+
+## 排查
+
+- 采集器卡片可看运行状态与日志(主机 docker logs / journalctl,集群 Pod 日志)。
+- 常见问题:目标命名空间无工作负载(app 候选为空)、路径无写入权限、Loki 端点不可达。
@@ -0,0 +1,29 @@
+# 常见问题
+
+## 登录后看不到「部署向导」「用户管理」等菜单?
+
+这些页面仅管理员可见。普通用户默认只有日志查询与日志告警;查询范围由策略组控制(见[查询授权](access.md))。
+
+## 部署的 Loki 怎么访问?必须配 Ingress 吗?
+
+集群内部署经 API Server Service Proxy 查询,不需要 Ingress。跨集群 / 公网查询才需要为 Loki 暴露域名后在「数据源管理」用 URL 直连关联。
+
+## 「停止部署」会删掉日志数据吗?
+
+不会。停止只回收工作负载;数据卷(PVC / 主机数据目录)保留,重新启动即可恢复。仅显式删除部署记录不影响远端资源,卸载需按页面指引执行。
+
+## 告警一直不发送?
+
+按顺序检查:通道是否启用、Webhook 是否正确(通道页有测试)、规则是否启用且命中阈值、发送历史里是否有「冷却抑制」或失败原因。通道未就绪时历史会明确记录失败原因。
+
+## 忘记管理员密码?
+
+管理员可在「用户管理」重置任意账号密码;若唯一管理员丢失密码,参考仓库 README 的离线重置说明。
+
+## 平台可以多实例部署吗?
+
+不可以。JSON 文件存储为单实例设计(防抖串行落盘),水平扩展会互相覆盖;需要高可用时用单实例 + 备份策略。
+
+## 升级安全吗?
+
+配置与数据向后兼容,结构变更按 schema 版本自动迁移;建议升级前在「系统设置」创建一次备份。
@@ -0,0 +1,44 @@
+# 安装与启动
+
+## 环境要求
+
+- 平台自身:任意 Linux / macOS(Go 1.24 构建或直接使用发布二进制),内存 ≥ 256MB
+- 目标 Kubernetes 集群:≥ 1.20;或裸金属 Linux 主机(SSH 可达)
+- 端口:平台默认 8080;Loki 默认 3100
+
+## 必备环境变量
+
+平台启动强制要求两个密钥(长度均需 ≥ 32 字符):
+
+```bash
+export JWT_SECRET=$(openssl rand -hex 32)
+export ENCRYPTION_KEY=$(openssl rand -hex 32)   # 凭证加密密钥,丢失将无法解密已存凭证
+```
+
+## 方式一:开发模式
+
+```bash
+./run.sh        # 同时拉起前端(:3000)与后端(:8080),自动注入开发密钥
+```
+
+## 方式二:生产 Docker
+
+```bash
+make secrets    # 生成 ./secrets/*.txt
+docker compose -f docker-compose.prod.yml up -d
+```
+
+## 方式三:单二进制
+
+```bash
+bash build.sh   # 产物 backend/bin/lokistack(前端已内嵌)
+export JWT_SECRET=... ENCRYPTION_KEY=... DATA_DIR=/data
+./lokistack
+```
+
+首次启动会自动创建管理员账号,初始密码写入 `$DATA_DIR/initial-admin-password.txt`,请立即修改。
+
+## 数据与升级
+
+- 全部状态存储在 `$DATA_DIR/lokistack.json`(JSON 文件,无外部数据库依赖,单实例运行)
+- 升级:替换二进制后重启即可;历史命名数据文件(opsxloki.json / lokideploy.json)会在启动时自动迁移
@@ -0,0 +1,20 @@
+# 日志查询
+
+「日志查询」页(`/logs`)按 LogQL 与时间范围检索日志。
+
+## 查询方式
+
+- **LogQL 编辑器**:语法高亮与标签/管道补全;回车执行。
+- **快捷查询**:选择命名空间缩小范围后,选中 App / Pod 即自动填入并执行;Ingress 访问日志按钮在选择 ingress 命名空间或 app 时出现。
+- **Label 浏览器**:按标签与值点选构建查询;点结果行的标签值可快速加过滤。
+- **Live Tail**:3 秒轮询最近 5 分钟,编辑查询自动防抖后切换。
+
+## 结果区
+
+- 顶部时间线展示整个查询范围的日志量,拖选高峰时段自动重查。
+- 原始日志支持关键字高亮、标签过滤、查看上下文(前后 N 行)。
+- 翻页向后游标推进,每页最多 1000 条。
+
+## 数据源
+
+「数据源管理」维护 Loki 连接:平台部署自动注册(随部署托管),也可手动添加 URL 直连或集群 Service 数据源,支持 Basic / Bearer / 自定义 Header 认证与连接测试。
@@ -0,0 +1,27 @@
+# 部署向导
+
+部署向导(`/wizard`)三步完成 Loki 上线:环境与目标 → 存储 → 部署 Loki 与采集。
+
+## 第一步:环境与目标
+
+- **Kubernetes 集群**:粘贴 kubeconfig,或按页面给出的 RBAC 脚本在集群执行一次后粘贴 ServiceAccount 长期 Token。平台经 API Server 操作集群,无需安装 kubectl/Helm。
+- **裸金属主机**:填写 SSH 地址与凭证(密码或私钥,AES-GCM 加密存储)。适合二进制或 Docker 模式。
+
+创建后平台自动验证连通性;Kubernetes 资源默认落在 `log` 命名空间(可改)。
+
+## 第二步:准备存储
+
+推荐对象存储(MinIO / RustFS / S3 / OSS):多副本与数据保留更可靠,创建时可用「测试连接」验证凭证并自动建桶;跳过则使用本地磁盘。
+
+## 第三步:部署与采集
+
+- 选择目标、Loki 版本(支持 2.8+ / 3.x)、保留天数与资源规格,点击部署。
+- 部署成功后平台自动注册同名数据源,日志查询页立即可用;按提示添加采集策略(见[日志采集](collectors.md))。
+
+## 三种部署模式
+
+| 模式 | 适用 | 说明 |
+| --- | --- | --- |
+| k8s-yaml | Kubernetes | StatefulSet + SSA 直发,平台全托管 |
+| host-binary | 裸金属 | SSH 安装二进制 + systemd 托管 |
+| host-docker | 裸金属 | Docker 容器运行,自动目录迁移 |