# 🐝 LogHive — 集中式日志管理系统

LogHive 是一个集中式的日志管理系统，可以从你的多个 Python 项目中收集日志，并提供搜索、分析和告警能力。

## 架构概览

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Python 项目  │    │  Python 项目  │    │  Python 项目  │
│  (LogHive SDK)│    │  (LogHive SDK)│    │  (LogHive SDK)│
└──────┬───────┘    └──────┬───────┘    └──────┬───────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │ HTTPS / REST API
                           ▼
                  ┌─────────────────┐
                  │  LogHive Backend │
                  │     (FastAPI)    │
                  └────────┬─────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │    ES    │  │PostgreSQL│  │  Redis   │
      │ 日志存储  │  │ 元数据   │  │ 队列/缓存 │
      └──────────┘  └──────────┘  └──────────┘
                           │
                    ┌──────┴──────┐
                    ▼             ▼
              ┌─────────┐  ┌──────────┐
              │ Celery  │  │  Vue 3   │
              │ 异步任务 │  │  前端    │
              └─────────┘  └──────────┘
```

## 功能特性

- **📥 日志收集** — 通过 REST API 接收 JSON 结构化日志，支持同步/异步客户端
- **🔍 全文检索** — 基于 Elasticsearch，支持按项目、级别、关键词、Trace ID、时间范围过滤
- **📊 统计分析** — 错误率趋势、级别分布、TOP N 错误、时序图表
- **🔔 告警规则** — 可配置的阈值告警，支持飞书/钉钉通知
- **🔗 链路追踪** — 通过 Trace ID 关联同一请求的跨模块日志
- **🐍 Python SDK** — 一行代码集成到现有项目，支持标准 logging handler
- **🔄 前后端分离** — FastAPI 后端 + Vue 3 前端

## 快速启动

### 前置条件

- Docker & Docker Compose
- Python 3.10+（本地开发）

### 使用 Docker Compose（推荐）

```bash
# 克隆项目
cd LogHive

# 启动所有服务
docker compose up -d

# 检查状态
docker compose ps
```

启动后访问：
- **前端**：http://localhost:3000
- **API**：http://localhost:8000
- **API 健康检查**：http://localhost:8000/api/health
- **Kibana**：http://localhost:5601

### 本地开发

```bash
# 1. 启动依赖服务
docker compose up -d postgres elasticsearch redis

# 2. 启动后端
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# 3. 启动前端
cd frontend
npm install
npm run dev
```

## 项目结构

```
LogHive/
├── backend/                    # FastAPI 后端
│   ├── app/
│   │   ├── api/                # API 路由
│   │   │   ├── logs.py         # 日志收录 & 查询
│   │   │   ├── projects.py     # 项目管理
│   │   │   ├── alerts.py       # 告警管理
│   │   │   └── dashboard.py    # 仪表盘
│   │   ├── models/             # SQLAlchemy 模型
│   │   ├── schemas/            # Pydantic 数据模型
│   │   ├── services/           # 业务逻辑层
│   │   ├── core/               # 认证 & 工具
│   │   ├── config.py           # 配置
│   │   ├── database.py         # 数据库连接
│   │   └── main.py             # 入口
│   ├── celery_worker/          # Celery 异步任务
│   ├── requirements.txt
│   └── Dockerfile
├── client/                     # Python SDK
│   ├── loghive_client/
│   │   ├── client.py           # 同步客户端
│   │   ├── async_client.py     # 异步客户端
│   │   └── handler.py          # logging 集成
│   ├── setup.py
│   └── README.md
├── frontend/                   # Vue 3 前端
│   ├── src/
│   │   ├── api/                # API 调用层
│   │   ├── router/             # 路由
│   │   └── views/              # 页面
│   ├── package.json
│   ├── vite.config.js
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md
```

## 使用指南

### 1. 创建项目 & 获取 API Key

```bash
# 注册项目
curl -X POST http://localhost:8000/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "description": "我的 Python 应用"}'

# 获取 API Key（在响应的 api_key 字段）
```

### 2. 在你的项目中使用 SDK

```python
# 安装 SDK
# pip install loghive-client

from loghive_client import LogHiveLogger

logger = LogHiveLogger(
    project="my-app",
    api_key="your-api-key",
    endpoint="http://localhost:8000",
)

logger.info("服务启动成功", extra={"port": 8080})
logger.error("数据库连接超时", exc_info=True)
```

### 3. 标准 logging 集成（零代码改动）

```python
import logging
from loghive_client import LogHiveHandler

handler = LogHiveHandler("my-app", "api-key", "http://localhost:8000")
logging.getLogger().addHandler(handler)

# 所有现有的日志调用自动转发到 LogHive
logging.info("这条日志也会发送到 LogHive")
```

### 4. 直接通过 API 推送日志

```bash
curl -X POST http://localhost:8000/api/logs/ingest \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "entries": [
      {
        "level": "info",
        "message": "Hello from my app!",
        "logger": "myapp.server",
        "extra": {"user_id": 42}
      }
    ]
  }'
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | FastAPI (Python 3.12) |
| 日志存储 | Elasticsearch 8.x |
| 元数据存储 | PostgreSQL 16 / TimescaleDB |
| 消息队列 | Redis 7 |
| 异步任务 | Celery |
| 前端 | Vue 3 + Element Plus + ECharts |
| 部署 | Docker Compose |

## 配置

通过环境变量配置，详见 `.env.example`。主要配置项：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET_KEY` | — | JWT 密钥（生产必改） |
| `ES_HOST` | localhost | Elasticsearch 地址 |
| `DATABASE_URL` | — | PostgreSQL 连接串 |
| `LOG_RETENTION_DAYS` | 30 | 日志保留天数 |
| `FEISHU_WEBHOOK_URL` | — | 飞书机器人 Webhook |

## License

MIT