5f14174bb9
✨ 新增功能 - 完整的日志记录系统（6 种日志级别） - 日志配置功能（可通过 config.json 控制） - 性能监控装饰器和请求日志中间件 - 7 个管理工具脚本 - 完整的文档和使用指南 🛠️ 管理工具 - start-with-log.sh: 启动脚本（带日志） - stop-dashboard.sh: 停止脚本 - view-logs.sh: 日志查看器 - monitor-logs.sh: 实时监控工具（支持多种过滤器） - analyze-logs.sh: 日志分析工具（自动生成报告） - demo-logging.sh: 功能演示脚本 - test-logging-config.sh: 配置测试工具 📊 日志特性 - 支持 INFO/SUCCESS/WARN/ERROR/DEBUG/PERF 6 种级别 - 自动记录启动过程、API 请求、性能统计 - 缓存命中情况追踪 - 分步性能监控 - 智能过滤器 ⚙️ 配置功能 - 可控制是否启用日志（默认：true） - 可设置日志级别（默认：INFO） - 可控制文件/控制台输出 - 支持动态配置（重启生效） 📚 文档 - LOGGING_GUIDE.md: 完整使用指南 - LOGGING_CONFIG.md: 配置说明文档 - LOGGING_CONFIG_QUICK.md: 快速配置指南 - 多个中文说明文档 🔒 安全 - 添加 .gitignore 排除敏感信息 - config.json（含 Token）不提交 - 日志文件不提交 - 示例配置使用占位符 ✅ 测试 - 语法检查通过 - 功能完整性验证 - 配置控制测试通过 - 文档完整性检查 详见 CHANGELOG_v1.1.0.md Made-with: Cursor
384 lines
11 KiB
Markdown
384 lines
11 KiB
Markdown
# Dashboard 运行日志使用指南
|
||
|
||
## 📋 概述
|
||
|
||
Dashboard 现已集成完整的运行日志系统，可以实时监控：
|
||
- ✅ 启动状态和配置加载
|
||
- 📡 API 请求详情和耗时
|
||
- ⏱️ 各组件加载性能
|
||
- 💾 缓存使用情况
|
||
- 🐳 Docker 和 Gateway 状态
|
||
- ⚠️ 错误和警告信息
|
||
|
||
**日志功能默认开启**，可以通过 `config.json` 配置来控制日志行为。
|
||
|
||
## ⚙️ 日志配置
|
||
|
||
在 `config.json` 中添加 `dashboard.logging` 配置：
|
||
|
||
```json
|
||
{
|
||
"dashboard": {
|
||
"port": 3800,
|
||
"logging": {
|
||
"enabled": true, // 是否启用日志（默认：true）
|
||
"level": "INFO", // 日志级别：DEBUG/INFO/WARN/ERROR（默认：INFO）
|
||
"file": true, // 是否写入文件（默认：true）
|
||
"console": true // 是否输出到控制台（默认：true）
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 日志级别说明
|
||
|
||
- **DEBUG** - 最详细，包含所有调试信息（开发时使用）
|
||
- **INFO** - 一般信息，记录重要运行状态（生产推荐）⭐
|
||
- **WARN** - 警告信息，需要关注但不影响运行
|
||
- **ERROR** - 只记录错误信息
|
||
|
||
详细配置说明请查看 `LOGGING_CONFIG.md`
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 启动 Dashboard（带日志记录）
|
||
|
||
```bash
|
||
cd /Users/fang/Desktop/ai-team/dashboard
|
||
|
||
# 使用带日志的方式启动
|
||
./start-with-log.sh
|
||
```
|
||
|
||
启动成功后，你会看到类似输出：
|
||
```
|
||
✅ Dashboard 启动成功！
|
||
PID: 12345
|
||
访问: http://localhost:3800
|
||
|
||
💡 查看日志：
|
||
实时日志: tail -f logs/dashboard.log
|
||
错误日志: tail -f logs/dashboard-error.log
|
||
停止服务: ./stop-dashboard.sh
|
||
```
|
||
|
||
### 2. 实时监控运行日志
|
||
|
||
```bash
|
||
# 方式 1：查看所有日志
|
||
./monitor-logs.sh
|
||
|
||
# 方式 2：只看 API 请求
|
||
./monitor-logs.sh --api
|
||
|
||
# 方式 3：只看性能统计
|
||
./monitor-logs.sh --perf
|
||
|
||
# 方式 4：只看错误和警告
|
||
./monitor-logs.sh --error
|
||
```
|
||
|
||
### 3. 查看分析报告
|
||
|
||
```bash
|
||
# 生成完整的日志分析报告
|
||
./analyze-logs.sh
|
||
```
|
||
|
||
报告包含：
|
||
- 📊 基础统计（各级别日志数量）
|
||
- 🚀 启动信息和配置加载状态
|
||
- 📡 API 请求分布和频率
|
||
- ⏱️ 性能统计（平均/最大耗时）
|
||
- 💾 缓存命中率
|
||
- ⚠️ 错误和警告汇总
|
||
- 💡 优化建议
|
||
|
||
## 📊 日志内容详解
|
||
|
||
### 启动阶段日志
|
||
|
||
Dashboard 启动时会记录以下信息：
|
||
|
||
```
|
||
[2026-03-11 10:30:15.123] ℹ️ [INFO] [系统] 🦞 AI Team Dashboard 正在初始化...
|
||
[2026-03-11 10:30:15.125] ℹ️ [INFO] [系统] 操作系统: darwin 25.2.0
|
||
[2026-03-11 10:30:15.127] ℹ️ [INFO] [系统] Node.js: v20.11.0
|
||
[2026-03-11 10:30:15.129] ℹ️ [INFO] [系统] 工作目录: /Users/fang/Desktop/ai-team/dashboard
|
||
[2026-03-11 10:30:15.150] ℹ️ [INFO] [配置] 正在加载配置文件...
|
||
[2026-03-11 10:30:15.175] ⏱️ [PERF] [配置] 加载配置文件 (25ms)
|
||
[2026-03-11 10:30:15.180] ✅ [SUCCESS] [配置] 配置文件加载成功
|
||
[2026-03-11 10:30:15.200] ✅ [SUCCESS] [系统] 🦞 AI Team Dashboard 启动成功!
|
||
[2026-03-11 10:30:15.205] ✅ [SUCCESS] [系统] 访问地址: http://localhost:3800
|
||
```
|
||
|
||
### API 请求日志
|
||
|
||
每个 API 请求都会记录：
|
||
|
||
```
|
||
[2026-03-11 10:30:20.456] ℹ️ [INFO] [API] GET /api/monitor | {"status":200,"duration":"245ms","ip":"::1"}
|
||
[2026-03-11 10:30:25.678] ℹ️ [INFO] [API] GET /api/status | {"status":200,"duration":"512ms","ip":"::1"}
|
||
[2026-03-11 10:30:30.890] ℹ️ [INFO] [API] GET /api/bot/leader | {"status":200,"duration":"123ms","ip":"::1"}
|
||
```
|
||
|
||
### 性能监控日志
|
||
|
||
详细记录各组件的加载耗时：
|
||
|
||
```
|
||
# 监控数据获取
|
||
[2026-03-11 10:30:20.100] 🔍 [DEBUG] [监控] 开始获取监控数据
|
||
[2026-03-11 10:30:20.115] 🔍 [DEBUG] [监控] Gateway 状态获取完成 | {"duration":"15ms"}
|
||
[2026-03-11 10:30:20.123] 🔍 [DEBUG] [监控] Gateway 进程信息获取完成 | {"duration":"8ms"}
|
||
[2026-03-11 10:30:20.135] 🔍 [DEBUG] [监控] 日志获取完成 | {"count":60,"duration":"12ms"}
|
||
[2026-03-11 10:30:20.170] 🔍 [DEBUG] [监控] Docker 状态获取完成 | {"duration":"35ms"}
|
||
[2026-03-11 10:30:20.345] ⏱️ [PERF] [API] GET /api/monitor (245ms)
|
||
[2026-03-11 10:30:20.350] ℹ️ [INFO] [监控] 监控数据返回成功 | {"workers":2,"logs":20,"timeline":5,"gatewayStatus":"online"}
|
||
|
||
# GitHub 数据获取
|
||
[2026-03-11 10:30:25.100] ⏱️ [PERF] [GitHub] getGitHubIssues - 成功获取 15 个 Issues (234ms)
|
||
[2026-03-11 10:30:25.500] ⏱️ [PERF] [GitHub] getRepoCommits [owner/repo] - 成功获取 10 个 Commits (178ms)
|
||
|
||
# Docker 状态检查
|
||
[2026-03-11 10:30:30.100] ⏱️ [PERF] [Docker] getDockerStatus - 检查了 2 个容器 (45ms)
|
||
```
|
||
|
||
### 缓存日志
|
||
|
||
记录缓存命中情况，帮助优化性能：
|
||
|
||
```
|
||
[2026-03-11 10:30:35.123] 🔍 [DEBUG] [GitHub] Issues 使用缓存 | {"age":"5000ms"}
|
||
[2026-03-11 10:30:40.456] 🔍 [DEBUG] [GitHub] Commits 使用缓存 [owner/repo] | {"age":"10000ms"}
|
||
```
|
||
|
||
### 健康检查日志
|
||
|
||
定期检查服务状态：
|
||
|
||
```
|
||
# Gateway 健康检查通过
|
||
[2026-03-11 10:30:45.100] 🔍 [DEBUG] [Gateway] 健康检查通过 | {"latency":"15ms"}
|
||
|
||
# Gateway 健康检查失败
|
||
[2026-03-11 10:31:00.200] ⚠️ [WARN] [Gateway] 健康检查失败 | {"code":"000","latency":"30ms"}
|
||
```
|
||
|
||
### 错误和警告日志
|
||
|
||
```
|
||
# 警告
|
||
[2026-03-11 10:35:00.123] ⚠️ [WARN] [GitHub] Issues 获取失败，返回缓存 | {"repo":"owner/repo"}
|
||
[2026-03-11 10:35:05.456] ⚠️ [WARN] [Docker] Docker 状态获取失败或无容器运行
|
||
|
||
# 错误
|
||
[2026-03-11 10:40:00.789] ❌ [ERROR] [GitHub] Issues 解析失败 | {"error":"Unexpected token"}
|
||
[2026-03-11 10:40:05.012] ❌ [ERROR] [配置] 配置文件加载失败 | {"error":"ENOENT: no such file"}
|
||
```
|
||
|
||
## 🔍 常见使用场景
|
||
|
||
### 场景 1：排查启动失败
|
||
|
||
```bash
|
||
# 1. 清空旧日志
|
||
> logs/dashboard.log
|
||
> logs/dashboard-error.log
|
||
|
||
# 2. 启动服务
|
||
./start-with-log.sh
|
||
|
||
# 3. 如果启动失败，脚本会自动显示错误
|
||
# 或者手动查看错误日志
|
||
./view-logs.sh -e
|
||
```
|
||
|
||
### 场景 2：监控运行性能
|
||
|
||
```bash
|
||
# 打开三个终端
|
||
|
||
# 终端 1：监控所有日志
|
||
./monitor-logs.sh
|
||
|
||
# 终端 2：只监控性能
|
||
./monitor-logs.sh --perf
|
||
|
||
# 终端 3：只监控错误
|
||
./monitor-logs.sh --error
|
||
```
|
||
|
||
### 场景 3：分析慢请求
|
||
|
||
```bash
|
||
# 1. 查看分析报告
|
||
./analyze-logs.sh
|
||
|
||
# 2. 查找耗时超过 500ms 的请求
|
||
grep '\[PERF\]' logs/dashboard.log | grep -E '\([5-9][0-9]{2,}ms\)'
|
||
|
||
# 3. 统计各 API 平均耗时
|
||
grep '\[PERF\].*GET /api/monitor' logs/dashboard.log | \
|
||
grep -oE '\([0-9]+ms\)' | tr -d '()ms' | \
|
||
awk '{sum+=$1; count++} END {print "平均:", sum/count "ms"}'
|
||
```
|
||
|
||
### 场景 4：检查缓存效率
|
||
|
||
```bash
|
||
# 查看缓存命中次数
|
||
grep '使用缓存' logs/dashboard.log | wc -l
|
||
|
||
# 查看缓存详情
|
||
grep '使用缓存' logs/dashboard.log | tail -20
|
||
|
||
# 查看缓存未命中（直接获取）的情况
|
||
grep '\[PERF\].*getGitHubIssues' logs/dashboard.log
|
||
```
|
||
|
||
### 场景 5：监控 API 请求频率
|
||
|
||
```bash
|
||
# 实时监控 API 请求
|
||
./monitor-logs.sh --api
|
||
|
||
# 统计各 API 调用次数
|
||
grep '\[API\]' logs/dashboard.log | \
|
||
grep -oE 'GET /api/[^ ]+|POST /api/[^ ]+' | \
|
||
sort | uniq -c | sort -rn
|
||
|
||
# 查看最近 10 次请求
|
||
grep '\[API\]' logs/dashboard.log | tail -10
|
||
```
|
||
|
||
### 场景 6：排查 Docker 问题
|
||
|
||
```bash
|
||
# 只看 Docker 相关日志
|
||
./monitor-logs.sh --docker
|
||
|
||
# 查看 Docker 状态检查历史
|
||
grep '\[Docker\]' logs/dashboard.log
|
||
|
||
# 查看容器数量变化
|
||
grep 'getDockerStatus - 检查了' logs/dashboard.log
|
||
```
|
||
|
||
### 场景 7：检查 GitHub API 状态
|
||
|
||
```bash
|
||
# 只看 GitHub 相关日志
|
||
./monitor-logs.sh --github
|
||
|
||
# 查看 Issues 获取情况
|
||
grep 'getGitHubIssues' logs/dashboard.log
|
||
|
||
# 查看 Commits 获取情况
|
||
grep 'getRepoCommits' logs/dashboard.log
|
||
```
|
||
|
||
## 📈 性能优化指南
|
||
|
||
### 根据日志优化缓存
|
||
|
||
如果你看到大量的缓存未命中：
|
||
```bash
|
||
# 检查缓存命中率
|
||
CACHE_HITS=$(grep '使用缓存' logs/dashboard.log | wc -l)
|
||
API_CALLS=$(grep '\[PERF\].*get' logs/dashboard.log | wc -l)
|
||
echo "缓存命中率: $(echo "scale=2; $CACHE_HITS/$API_CALLS*100" | bc)%"
|
||
```
|
||
|
||
如果命中率低于 50%，可以考虑：
|
||
1. 增加 `server.js` 中的 `CACHE_TTL` 值（默认 30 秒）
|
||
2. 减少前端的刷新频率
|
||
|
||
### 根据日志优化请求
|
||
|
||
如果看到大量慢请求：
|
||
```bash
|
||
# 查找耗时超过 1 秒的请求
|
||
grep '\[PERF\]' logs/dashboard.log | grep -E '\([0-9]{4,}ms\)'
|
||
```
|
||
|
||
优化建议：
|
||
1. 减少单次请求的数据量（如 Issues limit）
|
||
2. 增加缓存时间
|
||
3. 考虑异步加载非关键数据
|
||
|
||
### 根据日志优化 Docker 检查
|
||
|
||
如果 Docker 检查频繁失败：
|
||
```bash
|
||
# 查看失败率
|
||
grep 'Docker 状态获取失败' logs/dashboard.log | wc -l
|
||
```
|
||
|
||
优化建议：
|
||
1. 检查 docker-compose.yml 位置
|
||
2. 确保 Docker 服务运行
|
||
3. 减少容器数量
|
||
|
||
## 🛠️ 工具命令速查
|
||
|
||
| 命令 | 功能 | 示例 |
|
||
|------|------|------|
|
||
| `./start-with-log.sh` | 启动 Dashboard（带日志） | - |
|
||
| `./stop-dashboard.sh` | 停止 Dashboard | - |
|
||
| `./monitor-logs.sh` | 实时监控所有日志 | - |
|
||
| `./monitor-logs.sh --api` | 只监控 API 请求 | - |
|
||
| `./monitor-logs.sh --perf` | 只监控性能数据 | - |
|
||
| `./monitor-logs.sh --error` | 只监控错误警告 | - |
|
||
| `./monitor-logs.sh --github` | 只监控 GitHub 相关 | - |
|
||
| `./monitor-logs.sh --docker` | 只监控 Docker 相关 | - |
|
||
| `./analyze-logs.sh` | 生成分析报告 | - |
|
||
| `./view-logs.sh -f` | 实时查看日志 | - |
|
||
| `./view-logs.sh -e` | 查看错误日志 | - |
|
||
|
||
## 📝 日志示例完整流程
|
||
|
||
从启动到处理请求的完整日志示例：
|
||
|
||
```
|
||
# 1. 系统初始化
|
||
[2026-03-11 10:30:15.123] ℹ️ [INFO] [系统] 🦞 AI Team Dashboard 正在初始化...
|
||
[2026-03-11 10:30:15.150] ⏱️ [PERF] [配置] 加载配置文件 (25ms)
|
||
[2026-03-11 10:30:15.200] ✅ [SUCCESS] [系统] 🦞 AI Team Dashboard 启动成功!
|
||
|
||
# 2. 第一个监控请求（无缓存）
|
||
[2026-03-11 10:30:20.100] 🔍 [DEBUG] [监控] 开始获取监控数据
|
||
[2026-03-11 10:30:20.334] ⏱️ [PERF] [GitHub] getGitHubIssues - 成功获取 15 个 Issues (234ms)
|
||
[2026-03-11 10:30:20.390] ⏱️ [PERF] [Docker] getDockerStatus - 检查了 2 个容器 (56ms)
|
||
[2026-03-11 10:30:20.456] ⏱️ [PERF] [API] GET /api/monitor (356ms)
|
||
|
||
# 3. 第二个监控请求（使用缓存，更快）
|
||
[2026-03-11 10:30:25.100] 🔍 [DEBUG] [监控] 开始获取监控数据
|
||
[2026-03-11 10:30:25.110] 🔍 [DEBUG] [GitHub] Issues 使用缓存 | {"age":"5010ms"}
|
||
[2026-03-11 10:30:25.166] ⏱️ [PERF] [Docker] getDockerStatus - 检查了 2 个容器 (56ms)
|
||
[2026-03-11 10:30:25.200] ⏱️ [PERF] [API] GET /api/monitor (100ms)
|
||
|
||
# 4. 状态总览请求
|
||
[2026-03-11 10:30:30.100] 🔍 [DEBUG] [状态] 开始获取总览数据
|
||
[2026-03-11 10:30:30.110] 🔍 [DEBUG] [GitHub] Issues 使用缓存 | {"age":"10010ms"}
|
||
[2026-03-11 10:30:30.612] ⏱️ [PERF] [API] GET /api/status (512ms)
|
||
```
|
||
|
||
## 💡 最佳实践
|
||
|
||
1. **启动时清空旧日志**：避免日志文件过大
|
||
2. **使用过滤功能**：只关注你需要的日志类型
|
||
3. **定期查看分析报告**：了解系统运行状况
|
||
4. **关注性能日志**：及时发现性能瓶颈
|
||
5. **保存重要日志**：在修复问题前备份相关日志
|
||
|
||
## 🎯 下一步
|
||
|
||
现在你可以：
|
||
1. 启动 Dashboard：`./start-with-log.sh`
|
||
2. 打开浏览器访问：`http://localhost:3800`
|
||
3. 同时监控日志：`./monitor-logs.sh --api`
|
||
4. 查看性能分析：`./analyze-logs.sh`
|
||
|
||
祝使用愉快！🦞
|