故障排除

使用 kafka-log-analyzer 时的常见错误及解决方案。

错误码参考

错误码	描述	常见原因
INVALID_INPUT	缺少或无效的输入参数	必填字段未提供
FILE_NOT_FOUND	日志文件不存在	文件路径错误或权限不足
PROMETHEUS_UNAVAILABLE	无法连接 Prometheus	URL 不正确或服务未运行
LOKI_UNAVAILABLE	无法连接 Loki	URL 不正确或服务未运行
HOOK_ERROR	Hook 服务器操作失败	端口冲突或 Webhook 配置错误
PUSH_ERROR	推送通知失败	Webhook URL 无效或目标不可达
JIRA_ERROR	JIRA 集成失败	JIRA URL/Token 不正确
DATABASE_ERROR	SQLite 操作失败	存储目录不可写

Python 依赖问题

kafka-log-analyzer 需要 Python 3.8+ 来执行日志分析。

找不到 Python

Error: Python script failed: python3: command not found

解决方案：

1. 安装 Python 3.8+：

   # macOS
   brew install python3
   
   # Ubuntu/Debian
   sudo apt install python3
   
   # RHEL/CentOS
   sudo yum install python3

2. 或设置 pythonLocation 环境变量指向自定义安装路径：

   export pythonLocation=/path/to/python/installation

Python 版本不正确

Error: Python script failed: SyntaxError: invalid syntax

解决方案： 确认安装了 Python 3.8+：

python3 --version
# 应显示 3.8.x 或更高版本

连接故障排除

Prometheus 连接失败

WARN: Prometheus unavailable: fetch failed

检查清单：

1. 确认 Prometheus 正在运行：

   curl http://localhost:9090/-/healthy

2. 检查 PROMETHEUS_URL 环境变量：

   echo $PROMETHEUS_URL
   # 应为 http://prometheus-server:9090 格式

3. 确保分析器主机到 Prometheus 的网络连通性。

Loki 连接失败

WARN: Loki unavailable: Invalid URL

检查清单：

1. 确认 Loki 正在运行：

   curl http://localhost:3100/ready

2. 检查 LOKI_URL 环境变量：

   echo $LOKI_URL
   # 应为 http://loki-server:3100 格式

Webhook 推送失败

Error: Webhook URL validation failed: URL must start with https://

或：

Error: Webhook URL validation failed: URL resolves to private IP range

检查清单：

1. Webhook URL 必须使用 https://（不支持 http://）。
2. URL 不能解析到私有 IP 地址范围（127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16）。
3. 验证 FEISHU_WEBHOOK_URL 或 SLACK_WEBHOOK_URL 环境变量。

文件分析问题

文件未找到

Error: File not found: /path/to/server.log

解决方案：

1. 确认文件存在：

   ls -la /path/to/server.log

2. 使用绝对路径避免歧义。

3. 确保路径不包含 ../（路径遍历已被安全策略阻止）。

分析结果为空

如果 analyze_log 返回零个事件：

1. 检查日志格式是否匹配预期模式（文本或 JSON Kafka 日志）。
2. 验证日志文件包含 Kafka 相关条目。
3. 使用 --debug 标志获取详细解析信息：

   npx kafka-log-analyze analyze server.log --debug

路径遍历错误

Error: Invalid path: path traversal detected

解决方案： 使用不含 ../ 序列的直接路径。分析器出于安全原因阻止路径遍历。

存储问题

SQLite 数据库错误

Error: DATABASE_ERROR: unable to open database file

检查清单：

1. 检查 SQLITE_PATH 环境变量：

   echo $SQLITE_PATH
   # 默认: ./storage/kafka-analyzer.db

2. 确保存储目录可写：

   mkdir -p ./storage
   chmod 755 ./storage

3. 如果不需要持久化，分析器可以在无存储模式下继续工作。

Hook 服务器问题

端口已被占用

Error: HOOK_ERROR: listen EADDRINUSE: address already in use :::3000

解决方案： 使用其他端口：

npx kafka-log-analyze hooks --port 3001

或设置 PAGERDUTY_WEBHOOK_PORT 环境变量。

Hook 未触发分析

1. 确认 Hook 服务器正在运行：

   curl http://localhost:3000/hooks/health

2. 检查 Webhook 负载是否匹配预期格式（Grafana 统一告警或 PagerDuty Events API v2）。

3. 检查去重设置 — TTL 窗口内的告警会被抑制：

   HOOK_DEDUP_WINDOW_MS=30000  # 默认 30 秒