# 喵坤日志排查工具

**Repository Path**: lorock/miaokun-log

## Basic Information

- **Project Name**: 喵坤日志排查工具
- **Description**: 喵坤日志排查工具，轻量级、高性能日志检索与故障定位工具，支持 Java/Go/Python/Node.js 等多语言日志格式，命令行+Web 双端可用，百G大文件秒级响应，让线上排障快人一步。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="web/assets/logo.png" alt="喵坤® Logo" width="120" height="120">
</p>

# 🐾 喵坤<sup>®</sup> (MiaoKun)

**喵坤<sup>®</sup>在手，效率全有**

为开发者与运维人打造的轻量生产力工具品牌，专注解决技术人日常工作中的高频痛点。坚持「单文件、零依赖、开箱即用」的设计理念，拒绝复杂部署与冗余功能，让工具回归实用本质。

**喵坤<sup>®</sup>日志排查工具**  
轻量级、高性能日志检索与故障定位工具，支持 Java/Go/Python/Node.js 等多语言日志格式，命令行+Web 双端可用，百G大文件秒级响应，让线上排障快人一步。

---

## 核心优势

| 特性 | 价值 |
|------|------|
| 🚀 **极速搜索** | 基于 ripgrep 引擎，比传统 grep 快 5-10 倍，百G文件秒级响应 |
| 💨 **流式处理** | 实时输出，内存零溢出，轻松处理 100G+ 超大日志 |
| 🎨 **双端交互** | 命令行高效操作 + Web 可视化界面 |
| 📦 **零依赖部署** | 单二进制交付，前端资源内嵌 |
| 🧠 **智能缓存** | 自动解压并缓存 .gz 压缩日志 |
| 🔗 **全链路追踪** | 自动提取 traceId，跨文件追踪完整调用链 |
| ⏰ **精准过滤** | 时间窗口、日志级别、正则表达式多维度筛选 |
| 🔧 **灵活扩展** | 模块化架构，内置 jq 解析器 |
| 🔐 **多用户认证** | JWT + 多用户 + 角色权限 + SQLite 持久化，Docker 默认启用 |
| 📡 **实时跟踪** | 类 tail -f 实时跟随（基于成熟开源库），支持多文件合并流、logrotate 自动重开、异常多行合并 |
| 🔭 **Loki 数据源** | 接入 Grafana Loki 作为远程日志数据源，Go 后端封装 + 前端一键切换，本地功能零改动保留 |

---

## 适用场景

**适合人群**
- 后端开发者：快速定位代码异常与接口报错
- DevOps/SRE 工程师：生产环境日志排查与故障溯源
- 测试工程师：自动化测试日志分析与问题复现
- 所有需要频繁处理日志的技术人员

**不适用场景**
- 需要复杂日志可视化分析（推荐 ELK/Graylog）
- 实时告警触发与监控（推荐 Prometheus/Grafana）
- PB 级海量日志聚合分析（推荐专业大数据平台）

---

## 快速开始

### 前置依赖

```bash
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# CentOS/RHEL
sudo yum install ripgrep

# 其他系统：https://github.com/BurntSushi/ripgrep#installation
```

### 安装方式

```bash
# 方式1：源码安装
git clone https://gitee.com/lorock/miaokun-log.git
cd miaokun-log
make install

# 方式2：脚本安装
./scripts/install.sh
```

### 30秒上手

```bash
# 1. 列出默认路径下的日志文件
mk list

# 2. 搜索最近1天的 ERROR 日志
mk search "ERROR" --since 1 --level ERROR

# 3. 按 traceId 追踪完整调用链
mk trace abc123def456

# 4. 启动 Web 可视化服务（默认端口 9528）
mk serve
```

---

## 命令详解

### 全局选项

```bash
--no-banner   # 不显示启动 banner
--no-color    # 禁用彩色输出
--json        # 输出 JSON 格式
--jq 'xxx'    # 内置 jq 查询（配合 --json 使用）
--config      # 指定自定义配置文件（默认：$HOME/.miaokun-log.yaml）
```

### list - 列出日志文件

```bash
mk list                          # 列出默认路径日志
mk list /var/log/app             # 指定目录扫描
mk list --since 7                # 仅显示最近7天的文件
```

### search - 日志搜索（别名：grep）

```bash
# 基础搜索
mk search "NullPointerException"                # 搜索关键词
mk search "WARN" /var/log/app                  # 指定目录

# 高级过滤
mk search "ERROR" --since 1                     # 最近1天
mk search "." --level ERROR                     # 指定级别
mk search "error" -i                            # 大小写不敏感
mk search "ERROR" --from "2026-06-01 10:00" --to "2026-06-01 12:00"  # 精确时间

# 结果增强
mk search "ERROR" -B 2 -A 2                     # 显示上下文
mk search "ERROR" --stats                       # 统计信息
mk search "ERROR" --count                       # 仅显示行数
mk search "ERROR" --json --jq '.[].message'     # 提取 JSON 字段
```

### trace - TraceId 全链路追踪

自动跨文件聚合同一 traceId 的所有日志，还原完整调用流程。

```bash
mk trace abc123def456                           # 全局追踪
mk trace 7a8b9c0d1e2f3a4b5c6d /var/log/app      # 指定目录
mk trace ABC123DEF -i                           # 大小写不敏感
```

### stats - 日志统计分析

```bash
mk stats                                        # 统计默认路径
mk stats /var/log/app                           # 指定目录
mk stats --since 7                              # 最近7天
```

### serve - 启动 Web 可视化服务

前端资源已内嵌二进制文件，单端口统一提供 API 与静态资源服务。

```bash
mk serve                        # 启动服务（默认端口 9528）
mk serve --port 8080            # 自定义端口
mk serve --auth=true            # 启用认证（也可在配置文件设置）
mk serve --auth=false           # 禁用认证
mk serve --admin-password=xxx   # 指定 admin 初始密码（首次启动生效）
mk serve --auth-db=/path/auth.db # 指定 SQLite 路径
mk serve -v                     # 显示 API 请求日志
mk serve -vv                    # 调试模式
```

### 本地验证（实时跟踪 / tail -f）

启动服务后，可用两种方式验证实时跟随：

**方式 A：curl 直连 SSE（最快，无需构建前端）**

```bash
mk serve --auth=false --port 9528          # 等健康检查通过
printf '2026-07-20 01:00:00 INFO  old 1\n' > /tmp/demo.log

# 终端 A：订阅实时流（macOS 务必加 poll:true 与 --noproxy）
curl -sN --noproxy '*' -X POST http://localhost:9528/api/v1/tail/stream \
  -H "Content-Type: application/json" \
  -d '{"files":["/tmp/demo.log"],"back_lines":2,"poll":true}'

# 终端 B：追加新行 → 终端 A 即时出现 match 事件
echo "2026-07-20 01:05:00 ERROR boom" >> /tmp/demo.log
```

**方式 B：浏览器真实体验**

```bash
cd web && npm run build          # 刷新 web/dist（或 make build 让二进制内嵌前端）
mk serve --auth=false --port 9528
# 打开 http://localhost:9528 → 📡 实时跟踪 Tab → 选文件 → 开始跟踪 → 另开终端追加行
```

> ⚠️ **macOS 本地调试建议开启轮询模式**：本机若在 macOS 上用浏览器或 curl 验证实时跟踪，因 `hpcloud/tail` 在 macOS（kqueue）下 `NOTE_WRITE` 仅可靠触发首次写入，可能只收到「开始跟踪后第一条」新日志，后续追加行会丢失。**请在实时跟踪面板的「轮询模式」开关打开（或 curl 加 `"poll":true`）** 即可稳定接收全部新增行。生产环境为 Linux（inotify），默认关闭轮询即可，无需手动开启。
>
> 另：若本机设置了 `http_proxy`，curl 验证时务必加 `--noproxy '*'`（或 `NO_PROXY=localhost`），否则 SSE 流会被代理缓冲吞掉；浏览器不受此影响。

### Docker 部署

```bash
# 一键启动全套（NATS + Ingest + Serve）
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f mk-serve

# 停止
docker compose down

# 重建镜像（更新代码后必须 --no-cache，因为 Dockerfile 在容器内构建前端）
docker compose build --no-cache mk-serve
```

**默认凭据**（Docker 镜像默认启用认证）：
- 用户名：`admin`
- 密码：`miaokun-admin`
- ⚠️ 首次登录后请在「👤 个人中心」修改密码

认证数据库持久化在 `mk-auth` 卷（`/var/lib/miaokun/auth.db`），重启不丢失密码。

**Web 界面功能**
- 实时日志搜索（支持正则表达式）
- 搜索摘要工具栏（匹配数、文件数、ERROR/WARN、耗时、扫描进度）
- 结果内搜索（Ctrl+F，高亮 + 键盘导航）
- 搜索历史（localStorage 持久化，点击快捷填充，保存完整筛选参数）
- 导出功能（TXT / JSON / CSV / Markdown 四种格式）
- 复制功能（复制全部 + 悬停复制单条）
- 按日志级别一键过滤
- 精确时间范围筛选与多目录切换
- TraceId 跨文件全链路追踪
- 搜索结果自动高亮（关键词紫色高亮）
- 文件浏览功能（支持目录导航，面包屑路径返回）
- 上下文行显示/隐藏控制（默认前 3 / 后 5，仅限关键词所在文件）
- JSON 格式化显示（自动识别并美化）
- 长日志折叠（超过 500 字符自动折叠，动态行高计算）
- 时间戳识别显示（可点击跳转）
- 时间戳跳转（日期选择器 + 首条/±10分钟/末条 快捷按钮）
- 文件分组可折叠
- 动态虚拟滚动（基于内容字符数动态计算高度，ResizeObserver 监控容器）
- 「滚动到最新」悬浮按钮，快速定位最新日志
- 键盘快捷键（Ctrl+F 搜索、Ctrl+G 下一个、Esc 清空）
- 流式搜索进度指示（扫描中 X/Y 绿色脉冲徽章）
- 空状态三态区分（加载中 / 无结果 / 未开始）
- 登录认证（JWT Token + Refresh Token，自动刷新，401 中文友好提示）
- 多用户 + 角色权限（admin/user/viewer，权限矩阵可扩展）
- 用户中心（👤 个人中心：查看个人信息、修改密码，改密成功自动登出）
- 用户管理（⚙️ admin 专属：创建/删除用户、重置密码、修改角色）
- 认证可配置（配置文件 `auth.enabled` 控制，Docker 默认启用，本地默认关闭）
- 实时跟踪（📡 独立 Tab：选日志源/目录、正则过滤、初始行数、轮询开关；合并多文件流 + 多文件子标签 + 文件色标 + 仅看某文件；切到搜索时自动暂停保留、切回自动恢复；logrotate 自动重开；后端带 500ms 安全网轮询兜底，确保增量不丢）
- Loki 数据源（🔭 Header 分段控件一键切换：结构化表单自动映射 LogQL + 高级区「原始 LogQL」专家模式 + 实时跟踪 query_range 轮询；本地/远程双数据源并存，前端组件完全复用）
- 空目录友好提示（非空模态框消失）
- 搜索结果内存溢出防护（上限 50000 条，超限自动丢弃最早部分）
- XSS 安全防护（用户输入文本渲染前 HTML 转义）

**核心 API**

| 接口 | 用途 | 认证 |
|------|------|------|
| GET /api/v1/health | 健康检查 | 公开 |
| GET /api/v1/version | 获取版本号 | 公开 |
| GET /api/v1/auth/config | 查询认证是否启用（前端决定是否显示登录页） | 公开 |
| POST /api/v1/auth/login | 用户登录（返回 JWT Token） | 公开 |
| POST /api/v1/auth/refresh | 刷新 Token（401 自动刷新失败后才登出） | 公开 |
| POST /api/v1/auth/logout | 用户登出 | 公开 |
| GET /api/v1/auth/me | 获取当前用户信息 | ✅ |
| POST /api/v1/auth/change-password | 修改自己的密码 | ✅ |
| GET /api/v1/auth/users | 用户列表（admin） | ✅ admin |
| POST /api/v1/auth/users | 创建用户（admin） | ✅ admin |
| DELETE /api/v1/auth/users/{id} | 删除用户（admin） | ✅ admin |
| POST /api/v1/auth/users/{id}/reset-password | 重置密码（admin） | ✅ admin |
| PUT /api/v1/auth/users/{id}/roles | 修改角色（admin） | ✅ admin |
| GET /api/v1/files | 获取日志文件列表 | ✅ |
| GET /api/v1/files/list | 文件浏览（支持目录导航 + 分页，空目录返回 data: []） | ✅ |
| POST /api/v1/search/stream | SSE 流式搜索 | ✅ |
| POST /api/v1/tail/stream | 实时跟踪（tail -f，SSE 持续推送新增行，支持多文件 / 正则过滤 / from_start） | ✅ |
| POST /api/v1/search | 同步搜索（返回 JSON 数组） | ✅ |
| POST /api/v1/cluster | 异常聚类（按堆栈签名归并 Top N） | ✅ |
| GET /api/v1/sources | 获取来源（node/app/type 三维筛选，支持 Loki 标签采样） | ✅ |
| POST /api/v1/trace | TraceId 全链路追踪 | ✅ |
| POST /api/v1/stats | 日志级别与文件分布统计 | ✅ |
| POST /api/v1/ingest | HTTP 日志接收（单条/数组，可选 Token） | 公开 |

**API 响应格式约定**
- 成功: `{ "success": true, "data": [...], "pagination": {...} }`
- 失败: `{ "success": false, "error": { "code": "ERROR_CODE", "message": "中文错误描述" } }`
- **重要**: `data` 字段为空时返回 `[]`（空数组），**绝不返回 `null`**，避免前端 `v-if` 条件判断异常
- 所有错误信息均为**中文**（如「请先登录后再操作」、「您没有执行此操作的权限」等）

---

## 配置说明

配置文件路径：`$HOME/.miaokun-log.yaml`（**注意文件名带前导点 `.`**，与 `--config` 帮助文案一致），可通过 `--config` 指定自定义路径。未显式传 `--config` 时自动在 `$HOME/.config`、`$HOME`、工作目录下查找此文件。

```yaml
# 日志搜索根目录
default_paths:
  - /var/log
  - /opt/logs
  - /var/log/app

# 搜索时间范围（天）
since_days: 7

# 缓存目录（自动解压 .gz 日志）
cache_dir: /tmp/miaokun-cache

# 认证配置（可选，默认关闭）
auth:
  enabled: false                    # 是否启用认证
  jwt_secret: "your-secret-here"     # JWT 签名密钥（至少 16 字符）
  access_token_ttl: "24h"            # 访问令牌有效期
  refresh_token_ttl: "168h"          # 刷新令牌有效期（默认 7 天）
  db_path: "/var/lib/miaokun/auth.db" # SQLite 数据库路径（用户/密码持久化）
  # 首次启动初始化用户（表为空时生效，已有用户时忽略——保留运行时改过的密码）
  initial_users:
    - username: admin
      password: change-me-now        # 首次登录后请立即修改
      roles: [admin]
```

**认证机制说明**：
- 采用**混合存储方案**：配置文件 `initial_users` 仅在 SQLite 表为空时初始化，之后密码以 SQLite 为准
- 用户在 UI 修改密码后，容器重启不会丢失（SQLite 持久化，配合 Docker 卷 `mk-auth`）
- 角色体系：`admin`（全部权限）/ `user`（搜索+查看）/ `viewer`（只读），支持扩展
- 命令行 flag 可覆盖配置：`mk serve --auth=true --admin-password=xxx --auth-db=/path/auth.db`

示例配置：`.miaokun-log.example.yaml`

### 接入 Loki 数据源（可选）

除本地文件外，Miaokun 还支持把 **Loki** 作为数据源，后端用 Go 封装 Loki HTTP API，前端组件完全复用（搜索 / 实时跟踪 / 聚类 / 来源筛选零改动）。

```yaml
# 全局默认数据源：local（默认）或 loki；前端也可在「📁本地 / 🔭Loki」控件逐会话切换
datasource: local

loki:
  base_url: http://localhost:3100      # Loki HTTP API 地址
  tenant: ""                           # 可选 X-Scope-OrgID（多租户）
  username: ""                         # 可选 Basic Auth
  password: ""
  poll_interval_seconds: 2             # 实时跟踪轮询间隔（秒）
```

- 前端顶部「📁本地 / 🔭Loki」分段控件切换数据源；切换即重新拉取来源、刷新搜索。
- Loki 模式：结构化表单自动映射为 LogQL（级别→标签、关键词→行过滤器、来源→app/node 标签）；高级区可展开「原始 LogQL」直接粘贴查询。
- 实时跟踪在 Loki 模式下以**轮询 `query_range`** 实现（非 WebSocket），跨平台稳定。
- 环境变量覆盖：`MIAOKUN_DATASOURCE` / `MIAOKUN_LOKI_URL` / `MIAOKUN_LOKI_TENANT` / `MIAOKUN_LOKI_USERNAME` / `MIAOKUN_LOKI_PASSWORD` / `MIAOKUN_LOKI_POLL_INTERVAL`。

---

## 项目结构

```
miaokun-log/
├── cmd/mk/                    # 主程序入口（serve / ingest 子命令）
├── internal/                  # 核心业务逻辑
│   ├── auth/                 # 认证模块（JWT + 多用户 + 角色 + SQLite 存储）
│   │   ├── jwt.go            # JWT 管理 + AuthConfig + 角色权限矩阵
│   │   ├── handlers.go       # HTTP 处理器（登录/登出/改密/用户 CRUD）
│   │   ├── store_sqlite.go   # SQLite 用户存储（modernc.org/sqlite，纯 Go 无 cgo）
│   │   ├── store_memory.go   # 内存用户存储（测试用）
│   │   └── store_sqlite_test.go
│   ├── config/               # 配置管理（含 auth 段）
│   ├── discover/             # 日志文件发现
│   ├── cache/                # 压缩文件缓存
│   ├── parser/               # 日志格式解析（JSON/logback/log4j2/JUL/纯文本）
│   ├── searcher/             # 流式搜索核心（解析接入 + 字段过滤 + 多机筛选）
│   ├── server/               # HTTP 服务器（路由 + 优雅关闭 + 前端嵌入）
│   ├── ingest/               # 多机日志采集（NATS JetStream + HTTP 接收）
│   ├── timefilter/           # 时间过滤
│   └── trace/                # TraceId 链路追踪
├── pkg/types/                 # 公共类型定义（LogMatch、SearchRequest 等）
├── web/                      # 前端代码（Vue3 + Vite + Element Plus）
│   ├── src/
│   │   ├── components/       # Vue 组件（LogRowCard、UserCenter、UserManagement 等）
│   │   ├── composables/      # 组合式函数（useAuth、useLogStream、useFileList）
│   │   ├── types/           # TypeScript 类型（auth.ts、index.ts）
│   │   └── utils/           # 工具函数（logContent.ts）
│   └── dist/                 # 构建产物（内嵌到 Go 二进制）
├── deploy/docker/             # Docker 配置（miaokun-log.yaml）
├── scripts/                   # 辅助脚本（e2e 测试、Docker 重建、NATS 发布）
├── Dockerfile                 # 多阶段构建（node 编译前端 + debian-slim 运行）
├── docker-compose.yml         # 编排（mk-nats / mk-ingest / mk-serve）
└── Makefile                  # 编译构建规则
```

---

## 品牌理念

- **轻量至上**：单二进制文件，无运行时依赖
- **性能优先**：高性能引擎，极致响应速度与资源效率
- **开箱即用**：默认配置覆盖绝大多数场景
- **持续进化**：围绕技术人工作流，打造一站式生产力工具箱

---

## 更多资源

- 📖 [CHANGELOG.md](./CHANGELOG.md)
- 🐛 [Gitee Issues](https://gitee.com/lorock/miaokun-log/issues)
- 📦 [Gitee Releases](https://gitee.com/lorock/miaokun-log/releases)
- 💬 加入微信群/QQ群获取技术支持

---

## 知识产权

**商标信息**  
喵坤® 已获得中华人民共和国国家知识产权局商标注册证（第78682220号），核定使用商品/服务项目（国际分类：9），有效期至2034年11月06日。

**版权信息**  
喵坤Logo作品已获得中华人民共和国国家版权局著作权登记（国作登字-2024-F-00181372），著作权人：徐保金，创作完成日期：2024年05月07日。

---

**喵坤<sup>®</sup>，让技术人的工作更轻松**

## 📜 许可证

本项目采用 MIT 开源协议。详见 [LICENSE](LICENSE) 文件。