# 日志分析 Runbook

**用途**: 排查系统问题、分析故障原因

**适用场景**: 服务异常、用户投诉、安全审计

---

## 日志位置

```
# Docker 环境
docker-compose logs -f app          # 实时查看
docker-compose logs app > app.log   # 导出日志

# 本地环境
./logs/app.log                      # 本地日志文件
./logs/access.log                   # 访问日志
```

---

## 日志格式

系统使用结构化日志格式：

```
2026-04-11 10:30:45 [API] 2026-04-11 10:30:45 POST /api/v1/auth/login | status: 200 | latency: 45.2ms | ip: 192.168.1.100 | user_id: 123 | trace_id: abc123
```

**字段说明**:
- `timestamp` - 请求时间
- `method` - HTTP 方法
- `path` - 请求路径
- `status` - HTTP 状态码
- `latency` - 响应延迟
- `ip` - 客户端 IP
- `user_id` - 用户 ID（未登录为 `<nil>`）
- `trace_id` - 请求追踪 ID

---

## 常见问题排查

### 1. 服务无法访问

```bash
# 检查服务状态
docker-compose ps

# 查看最近错误日志
docker-compose logs --tail=100 app | grep -i error

# 检查端口监听
netstat -tlnp | grep 8080
```

### 2. 登录失败

```bash
# 搜索登录相关日志
docker-compose logs --tail=500 app | grep -i "login\|auth"

# 检查具体错误
docker-compose logs --tail=500 app | grep "status: 401\|status: 403"

# 检查密码验证日志
docker-compose logs --tail=500 app | grep -i "password\|verify"
```

### 3. API 响应慢

```bash
# 搜索慢请求（latency > 1s）
docker-compose logs --tail=1000 app | grep -E "latency: [0-9]+\.[0-9]+s|latency: [2-9][0-9]+ms"

# 分析慢请求模式
docker-compose logs app | grep "latency" | awk -F'latency: ' '{print $2}' | awk '{sum+=$1; count++} END {print "平均延迟:", sum/count "ms"}'
```

### 4. 数据库错误

```bash
# 搜索数据库相关错误
docker-compose logs --tail=500 app | grep -i "sql\|database\|sqlite"

# 检查数据库文件
ls -la data/*.db
sqlite3 data/user_management.db "PRAGMA integrity_check;"
```

### 5. 内存/资源问题

```bash
# 检查容器资源使用
docker stats --no-stream

# 查看内存相关日志
docker-compose logs --tail=500 app | grep -i "memory\|oom\|alloc"

# 检查 goroutine 数量
docker-compose logs --tail=500 app | grep -i "goroutine"
```

---

## 日志分析命令

### 常用 grep 命令

```bash
# 搜索错误日志
docker-compose logs app | grep -i error

# 搜索特定用户的操作
docker-compose logs app | grep "user_id: 123"

# 搜索特定时间段的日志
docker-compose logs --since="2026-04-11T10:00:00" app

# 搜索特定 trace_id
docker-compose logs app | grep "trace_id: abc123"

# 统计各状态码出现次数
docker-compose logs app | grep -oE "status: [0-9]+" | sort | uniq -c
```

### 日志统计脚本

```bash
#!/bin/bash
# 日志统计脚本

echo "=== 请求统计 ==="
docker-compose logs app | grep -c "POST\|GET\|PUT\|DELETE"

echo "=== 状态码分布 ==="
docker-compose logs app | grep -oE "status: [0-9]+" | sort | uniq -c

echo "=== 慢请求 (>1s) ==="
docker-compose logs app | grep -E "latency: [2-9][0-9]+ms|latency: [0-9]+\.[0-9]+s" | wc -l

echo "=== 错误请求 ==="
docker-compose logs app | grep -i "error\|fail\|panic" | wc -l
```

---

## 日志级别

| 级别 | 关键词 | 含义 |
|-----|-------|-----|
| DEBUG | `DEBUG` | 调试信息 |
| INFO | `INFO` | 正常信息 |
| WARN | `WARN` | 警告信息 |
| ERROR | `ERROR` | 错误信息 |

```bash
# 设置日志级别（通过配置或环境变量）
# 生产环境建议: INFO 或 WARN
# 开发环境: DEBUG

docker-compose logs --tail=100 app | grep -E "DEBUG|INFO|WARN|ERROR"
```

---

## 安全审计

### 1. 查找异常登录尝试

```bash
# 查找失败的登录
docker-compose logs app | grep "status: 401"

# 查找异地登录（同一用户不同 IP）
docker-compose logs app | grep "user_id: " | awk '{print $NF}' | sort | uniq -c | sort -rn | head -10
```

### 2. 查找敏感操作

```bash
# 查找密码修改
docker-compose logs app | grep -i "password\|change"

# 查找权限变更
docker-compose logs app | grep -i "role\|permission\|admin"

# 查找数据导出
docker-compose logs app | grep -i "export\|download"
```

### 3. 查找恶意请求

```bash
# 查找 SQL 注入尝试
docker-compose logs app | grep -i "sql\|union\|select\|drop"

# 查找 XSS 尝试
docker-compose logs app | grep -i "<script\|javascript:"
```

---

## 相关文档

- [服务启动](./01-服务启动.md) - 启动时的日志检查
- [服务停止](./02-服务停止.md) - 故障时保存日志

---

**维护日期**: 2026-04-11
**下次审查**: 每月检查一次
