ai-team-dashboard/dashboard/日志功能更新说明.md

Dashboard 运行日志功能更新

🎉 更新内容

已为 AI Team Dashboard 添加完整的运行日志监控系统，实现从启动到运行的全过程可观测性。

✨ 新增功能

1. 📝 详细的日志记录

日志级别

• INFO (ℹ️ 青色) - 一般信息，记录系统运行状态
• SUCCESS (✅ 绿色) - 成功操作
• WARN (⚠️ 黄色) - 警告信息
• ERROR (❌ 红色) - 错误信息
• DEBUG (🔍 灰色) - 调试信息，详细的运行细节
• PERF (⏱️ 紫色) - 性能监控，记录各操作的耗时

记录内容

• ✅ 系统初始化过程
• ✅ 配置文件加载（包含耗时）
• ✅ Bot 配置初始化
• ✅ API 请求详情（路径、耗时、状态码、IP）
• ✅ 各组件性能监控：
  • Gateway 状态检查
  • Docker 状态获取
  • GitHub Issues 获取
  • GitHub Commits 获取
  • 日志加载
  • 数据组装
• ✅ 缓存命中情况
• ✅ 错误和警告详情
• ✅ 优雅退出和异常捕获

2. 🛠️ 管理工具

start-with-log.sh - 启动脚本

• 自动检查配置文件
• 后台启动并记录日志
• 显示启动状态和访问地址
• 启动失败时显示错误信息

stop-dashboard.sh - 停止脚本

• 安全停止服务
• 清理 PID 文件
• 支持强制停止

view-logs.sh - 日志查看器

• 查看最近 N 行日志
• 实时跟踪日志
• 查看错误日志
• 支持多种显示模式

monitor-logs.sh - 实时监控工具（⭐ 推荐）

• 实时监控所有日志
• 过滤功能：
  • --api - 只看 API 请求
  • --perf - 只看性能统计
  • --error - 只看错误和警告
  • --github - 只看 GitHub 相关
  • --docker - 只看 Docker 相关
  • --system - 只看系统日志
  • --config - 只看配置日志
• 支持历史查看和自定义行数

analyze-logs.sh - 日志分析工具（⭐ 推荐）

自动生成详细的分析报告：

• 📊 基础统计（各级别日志数量）
• 🚀 启动信息
• 📡 API 请求统计和分布
• ⏱️ 性能统计（平均耗时、最大耗时）
• 💾 缓存使用统计
• ⚠️ 错误和警告汇总
• 🐳 Docker 和 Gateway 状态
• 💡 自动优化建议

3. 📄 完整文档

• logs/README.md - 日志说明文档
• LOGGING_GUIDE.md - 使用指南和最佳实践

📦 文件清单

修改的文件

• server.js - 添加完整的日志系统
  • 日志工具函数
  • 请求日志中间件
  • 各 API 路由的性能监控
  • 数据获取函数的日志记录
  • 启动和退出的日志记录

新增的文件

dashboard/
├── start-with-log.sh       # 启动脚本（带日志）
├── stop-dashboard.sh        # 停止脚本
├── view-logs.sh             # 日志查看器
├── monitor-logs.sh          # 实时监控工具 ⭐
├── analyze-logs.sh          # 日志分析工具 ⭐
├── LOGGING_GUIDE.md         # 使用指南
└── logs/
    ├── README.md            # 日志说明
    ├── dashboard.log        # 运行日志（自动创建）
    ├── dashboard-error.log  # 错误日志（自动创建）
    └── dashboard.pid        # 进程 ID（自动创建）

🚀 快速开始

1. 启动 Dashboard

cd /Users/fang/Desktop/ai-team/dashboard
./start-with-log.sh

2. 实时监控

# 方式 1：查看所有日志
./monitor-logs.sh

# 方式 2：只看 API 请求
./monitor-logs.sh --api

# 方式 3：只看性能统计
./monitor-logs.sh --perf

# 方式 4：只看错误
./monitor-logs.sh --error

3. 查看分析报告

./analyze-logs.sh

📊 日志示例

启动日志

[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.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 启动成功!

API 请求日志

[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.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}
[2026-03-11 10:30:20.456] ℹ️ [INFO] [API] GET /api/monitor | {"status":200,"duration":"245ms"}

性能统计日志

[2026-03-11 10:30:25.334] ⏱️ [PERF] [GitHub] getGitHubIssues - 成功获取 15 个 Issues (234ms)
[2026-03-11 10:30:25.512] ⏱️ [PERF] [GitHub] getRepoCommits [owner/repo] - 成功获取 10 个 Commits (178ms)
[2026-03-11 10:30:25.557] ⏱️ [PERF] [Docker] getDockerStatus - 检查了 2 个容器 (45ms)

缓存日志

[2026-03-11 10:30:30.123] 🔍 [DEBUG] [GitHub] Issues 使用缓存 | {"age":"5000ms"}
[2026-03-11 10:30:35.456] 🔍 [DEBUG] [GitHub] Commits 使用缓存 [owner/repo] | {"age":"10000ms"}

🔍 常见使用场景

排查启动失败

# 1. 清空旧日志
> logs/dashboard.log
> logs/dashboard-error.log

# 2. 启动服务
./start-with-log.sh

# 3. 查看错误（如果启动失败）
./view-logs.sh -e

监控运行性能

# 打开两个终端

# 终端 1：监控 API 请求
./monitor-logs.sh --api

# 终端 2：监控性能统计
./monitor-logs.sh --perf

分析慢请求

# 查看分析报告
./analyze-logs.sh

# 查找耗时超过 500ms 的操作
grep '\[PERF\]' logs/dashboard.log | grep -E '\([5-9][0-9]{2,}ms\)'

检查缓存效率

# 查看缓存命中情况
grep '使用缓存' logs/dashboard.log | wc -l

# 查看详细信息
./analyze-logs.sh

💡 优化建议

根据日志优化性能

1. 如果 API 响应慢

   • 查看 ./analyze-logs.sh 中的性能统计
   • 增加缓存时间（修改 server.js 中的 CACHE_TTL）
   • 减少单次请求的数据量

2. 如果缓存命中率低

   • 查看 ./analyze-logs.sh 中的缓存统计
   • 增加缓存过期时间
   • 检查前端刷新频率

3. 如果 Docker 检查失败

   • 使用 ./monitor-logs.sh --docker 监控
   • 检查 Docker 服务状态
   • 验证 docker-compose.yml 位置

4. 如果 Gateway 健康检查失败

   • 使用 ./monitor-logs.sh --error 查看警告
   • 检查 OpenClaw 服务状态
   • 访问 http://127.0.0.1:18789/healthz 测试

📈 性能指标说明

Dashboard 会自动监控以下性能指标：

API 响应时间

• GET /api/monitor - 监控页面数据
• GET /api/status - 总览页面数据
• GET /api/bot/:id - Bot 详情
• GET /api/bot/:id/logs - Bot 日志

数据加载时间

• 配置文件加载
• GitHub Issues 获取
• GitHub Commits 获取
• Docker 状态检查
• Gateway 健康检查

组件级性能

每个 API 请求都会分解为多个子操作并记录耗时：

GET /api/monitor (总耗时: 245ms)
├─ Gateway 状态: 15ms
├─ Gateway 进程: 8ms
├─ 日志获取: 12ms
└─ Docker 状态: 35ms

🎯 预期效果

使用新的日志系统，您可以：

1. 实时了解系统状态

   • 启动是否正常
   • 配置加载是否成功
   • 各组件运行状态

2. 精确定位性能瓶颈

   • 哪个 API 最慢
   • 哪个组件耗时最长
   • 缓存效率如何

3. 快速排查问题

   • 启动失败原因
   • 运行时错误详情
   • Docker/Gateway 状态异常

4. 数据驱动优化

   • 基于真实数据调整缓存策略
   • 识别慢查询并优化
   • 发现异常访问模式

📚 相关文档

• LOGGING_GUIDE.md - 详细使用指南
• logs/README.md - 日志文件说明
• 各脚本文件使用 -h 或 --help 查看帮助

🔄 后续优化方向

可以考虑进一步添加：

• 日志自动轮转（避免文件过大）
• 日志上传到远程服务器
• Webhook 通知（错误告警）
• 性能趋势分析
• 慢查询自动优化建议

✅ 测试确认

已完成：

• ✅ 语法检查通过
• ✅ 所有脚本可执行权限已设置
• ✅ 文档完整性检查
• ✅ 功能完整性确认

🎉 完成！

现在您可以：

1. 使用 ./start-with-log.sh 启动 Dashboard
2. 使用 ./monitor-logs.sh 实时监控运行日志
3. 使用 ./analyze-logs.sh 查看性能分析报告
4. 参考 LOGGING_GUIDE.md 了解更多使用技巧

祝使用愉快！🦞