user-system/docs/runbooks/04-日志分析.md

日志分析 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. 服务无法访问

# 检查服务状态
docker-compose ps

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

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

2. 登录失败

# 搜索登录相关日志
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 响应慢

# 搜索慢请求（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. 数据库错误

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

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

5. 内存/资源问题

# 检查容器资源使用
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 命令

# 搜索错误日志
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

日志统计脚本

#!/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	错误信息

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

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

---

安全审计

1. 查找异常登录尝试

# 查找失败的登录
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. 查找敏感操作

# 查找密码修改
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. 查找恶意请求

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

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

---

相关文档

• 服务启动 - 启动时的日志检查
• 服务停止 - 故障时保存日志

---

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