# cat-log

**Repository Path**: sunmingze123/cat-log

## Basic Information

- **Project Name**: cat-log
- **Description**: 用 DuckDB 分析 Java 微服务日志的本地工具。前端 + Node，零中间件，`pnpm dev` 起来就能用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cat-log

本地 Java 微服务日志分析工具。基于 DuckDB，前端 + Node，零中间件，`pnpm dev` 即可运行。

把下载到本机的日志一次性摄入 DuckDB，支持结构化检索、业务号链路视图、任意 SQL 查询。

## 快速开始

```bash
pnpm install
pnpm dev      # 后端 5178 + 前端 5179
pnpm start    # 生产：构建前端，单进程托管（5178）
```

首次启动若无 `catlog.config.json`，server 自动生成空配置。打开 http://127.0.0.1:5179 在「数据源」页接入日志。

## 添加日志

1. 打开 http://127.0.0.1:5179，进入「数据源」页。
2. 「添加本地」填日志根目录；或「添加远程」填 SSH 凭据。
3. 点「摄入未摄入/有更新」扫入 DuckDB。
4. 看板 / 检索 / 链路 / SQL 页面即可使用。

目录结构自动识别，服务名 / 级别 / 日期从路径推导：

```
<root>/[分组/]<服务>-log/[info|error]/<名字>.log.YYYY-MM-DD-<i>.log
```

无 `*-log` 目录时退化为文件名前缀作服务名；`.gz`/`.zip` 会被跳过。

## 配置

编辑根目录 `catlog.config.json`：

```json
{
  "logRoots": [{ "path": "D:/logs/prod", "label": "生产" }],
  "encoding": "auto",
  "dbPath": "data/catlog.duckdb",
  "port": 5178,
  "contextWindowSeconds": 2
}
```

完整示例见 `catlog.config.example.json`。含 SSH 密码等敏感字段请用 `${env:VAR}` 注入，或放到 `.gitignore` 忽略的 `catlog.config.local.json`。改完在「数据源」页点「重新加载配置」或重启。

## 远程日志

在 `logRoots` 的某根加 `remote` 即可经 SFTP 增量同步到本地缓存，再走正常扫描/摄入：

```json
{
  "path": "/home/webapp/logs",
  "remote": {
    "host": "10.0.0.5", "port": 22, "user": "logreader",
    "privateKeyPath": "~/.ssh/id_ed25519"
  }
}
```

认证三选一：`privateKeyPath` / `agent: true` / `password`（建议 `${env:SSH_PASSWORD}`）。支持 `jumpHost` 跳板机。首次全量，之后按 size:mtime 增量；rotate 删除的远程文件需手动清 `data/remote-cache/`。

## 页面

| 页面 | 用途 |
|---|---|
| 看板 | 日志量时间线、ERROR 分布、Top 异常、慢接口 |
| 日志检索 | 多维筛选 + 虚拟滚动，单行看完整堆栈 |
| 链路追踪 | 输入业务号拉跨服务时间线 |
| SQL | 只读 SQL + 模板 + 导出 CSV |
| 数据源 | 文件清单、摄入、实时进度 |

## 命令

| 命令 | 说明 |
|---|---|
| `pnpm dev` | 后端 + 前端 |
| `pnpm start` | 生产单进程 |

## 已知限制

- 链路为启发式推断，无业务号且不在同线程时间窗内的行会漏（彻底解法：Java 侧加 MDC traceId）。
- 同日志不同文件名重复下载会重复计数。
- 时间戳无时区，按墙上时钟处理。
- 单条消息上限 64KB、堆栈 32KB，超出截断；`.gz`/`.zip` 不解压。
- 自动检测只看前 200 行，混放不同格式需分别配 `logRoots`。
- grok 为纯 JS 实现，覆盖常用模式，不支持高级语法。

## 安全

- 服务仅监听 `127.0.0.1`，无鉴权，不要暴露到 `0.0.0.0` 或对外开放。
- SQL 页只读，但表函数仍可读本机文件，仅供本机单用户使用。

## 架构

日志采集的设计取舍（为什么不全学 Grafana Loki、为什么实时采集不下载到本地）见
[`docs/architecture.md`](./docs/architecture.md)。