Initial commit: LogHive centralized log management system
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
v6ole
@@ -0,0 +1,219 @@
|
||||
# 🐝 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
|
||||
Reference in New Issue
Block a user