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
```bash
cd /Users/fang/Desktop/ai-team/dashboard
./start-with-log.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
```

## 📊 日志示例

### 启动日志
```
[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"}
```

## 🔍 常见使用场景

### 排查启动失败
```bash
# 1. 清空旧日志
> logs/dashboard.log
> logs/dashboard-error.log

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

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

### 监控运行性能
```bash
# 打开两个终端

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

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

### 分析慢请求
```bash
# 查看分析报告
./analyze-logs.sh

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

### 检查缓存效率
```bash
# 查看缓存命中情况
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` 了解更多使用技巧

祝使用愉快！🦞