LogHive/README.md

🐝 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（推荐）

# 克隆项目
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

本地开发

# 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

# 注册项目
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

# 安装 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 集成（零代码改动）

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 推送日志

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