v6ole
220 lines
7.1 KiB
Markdown
220 lines
7.1 KiB
Markdown
# 🐝 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
|