# nginx-log-analysis

**Repository Path**: ops-mx/nginx-log-analysis

## Basic Information

- **Project Name**: nginx-log-analysis
- **Description**: nginx-log-analysis SKILL
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nginx Log Analysis

Nginx 访问日志分析工具集，通过 Python 脚本提取关键运维指标，支持自然语言指令路由和多日志格式管理。

---

## 目录

- [技能概述](#技能概述)
- [核心功能](#核心功能)
- [目录结构](#目录结构)
- [环境要求](#环境要求)
- [日志格式配置管理](#日志格式配置管理)
- [使用方法](#使用方法)
- [分析功能详解](#分析功能详解)
- [常见问题与解决方案](#常见问题与解决方案)
- [注意事项与最佳实践](#注意事项与最佳实践)

---

## 技能概述

本技能通过 Qoder Agent 调用 `/nginx-log-analysis` 指令，自动分析 Nginx access log 文件，输出结构化 JSON 报告。

**核心特点：**
- 零外部依赖：仅使用 Python 标准库
- 自然语言驱动：用自然语言描述需求，自动路由到对应分析脚本
- 多格式支持：通过配置文件管理不同业务/环境的日志格式
- 模块化架构：单项分析按需加载，全量分析一次遍历

---

## 核心功能

| 功能 | 说明 |
|------|------|
| HTTP 状态码统计 | 200/404/500 等状态码分布，2xx/3xx/4xx/5xx 分类，错误率 |
| QPS 性能指标 | 平均 QPS、峰值 QPS 及时间点、每分钟 Top10、每小时分布 |
| User-Agent 分析 | UA 排行榜、独立 UA 数量统计 |
| 客户端分类 | 浏览器 / 移动端浏览器 / 命令行工具 / 爬虫 / 移动应用 各类占比 |
| HTTP 请求方法 | GET / POST / PUT / DELETE 等方法的数量与百分比 |
| IP 地址分析 | Top N 高频 IP、唯一 IP 数、疑似攻击源识别 |
| 响应体大小 | 总带宽、平均大小、P50/P95/P99 百分位、大小桶分布 |
| Referer 来源 | 直接访问 / 搜索引擎 / 社交媒体 / 外部站点分类 |
| 全量分析 | 一次遍历输出以上所有指标的完整报告 |

---

## 目录结构

```
nginx-log-analysis/
├── SKILL.md                               # 技能入口文件（Agent 读取）
├── README.md                              # 本文档
├── log-format/                            # 日志格式配置（用户维护）
│   ├── mse_production_log_main.conf       # 示例：MSE 生产环境 main 格式
│   └── mse_staging_log_json.conf          # 示例：MSE 预发环境 JSON 格式
└── scripts/                               # 分析脚本（系统维护）
    ├── log_parser.py                      # 共享解析模块
    ├── full_analysis.py                   # 全量分析入口
    ├── status_code_analyzer.py            # 状态码统计
    ├── qps_calculator.py                  # QPS 计算
    ├── user_agent_analyzer.py             # User-Agent 排行
    ├── client_type_analyzer.py            # 客户端分类
    ├── http_method_analyzer.py            # 请求方法分布
    ├── ip_analyzer.py                     # IP 分析
    ├── response_size_analyzer.py          # 响应体大小
    └── referer_analyzer.py                # Referer 来源
```

---

## 环境要求

- **Python 3.6+**（仅使用标准库，无需 pip install）
- **Qoder IDE**（通过 `/nginx-log-analysis` 指令调用）

---

## 日志格式配置管理

> **重要**：Nginx 日志格式因业务和环境而异，所有格式配置文件由用户负责维护。

### 配置文件位置

所有格式配置文件存放在 `log-format/` 目录下。

### 命名规范

推荐格式：`{业务线}_{环境}_{格式名}.conf`

| 文件名示例 | 含义 |
|-----------|------|
| `mse_production_log_main.conf` | MSE 生产环境 main 格式 |
| `mse_staging_log_json.conf` | MSE 预发环境 JSON 格式 |
| `gateway_production_log_combined.conf` | 网关生产环境 combined 格式 |
| `order_testing_log_custom.conf` | 订单服务测试环境自定义格式 |

### 配置文件内容

每个文件应包含完整的 nginx `log_format` 指令：

```nginx
# 文件: mse_production_log_main.conf
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';
```

```nginx
# 文件: mse_staging_log_json.conf
log_format json_log escape=json '{'
    '"time":"$time_iso8601",'
    '"remote_addr":"$remote_addr",'
    '"request":"$request",'
    '"status":$status,'
    '"body_bytes_sent":$body_bytes_sent,'
    '"request_time":$request_time'
'}';
```

### 新增格式步骤

1. 在 `log-format/` 目录下创建 `.conf` 文件，按命名规范命名
2. 写入对应的 `log_format` 指令
3. 下次分析时系统会自动列出该格式供选择

---

## 使用方法

### 通过 Qoder Agent 使用（推荐）

在 Qoder 中输入 `/nginx-log-analysis` 激活技能，然后用自然语言描述需求：

```
/ nginx-log-analysis

请分析 D:\logs\access.log，看看访问量最高的 IP 有哪些
```

Agent 会自动：
1. 确认日志文件存在
2. 列出 `log-format/` 下的可用格式供选择
3. 路由到 `ip_analyzer.py` 执行分析
4. 以表格形式展示结果

### 自然语言指令示例

| 你说 | Agent 执行 |
|------|-----------|
| "分析这个日志的整体情况" | `full_analysis.py` |
| "统计 4xx 和 5xx 错误率" | `status_code_analyzer.py` |
| "看看 QPS 峰值是多少" | `qps_calculator.py` |
| "哪些 IP 访问次数最多" | `ip_analyzer.py` |
| "流量来源是什么" | `referer_analyzer.py` |
| "有没有爬虫在访问" | `client_type_analyzer.py` |
| "响应体大小分布如何" | `response_size_analyzer.py` |

### 直接命令行调用

```bash
# 全量分析
python scripts/full_analysis.py /path/to/access.log --top 10

# 单项分析
python scripts/status_code_analyzer.py /path/to/access.log
python scripts/ip_analyzer.py /path/to/access.log --top 20
```

---

## 分析功能详解

### 1. 全量分析（full_analysis.py）

一次遍历日志文件，输出所有指标的完整报告。适用于首次分析或需要全面了解日志状况的场景。

**输出字段：**
```json
{
  "summary": { "total_requests", "unique_ips", "unique_user_agents", "time_range" },
  "qps": { "avg_qps", "peak_qps", "peak_qps_time", "per_hour_distribution" },
  "status_codes": { "by_code", "by_class", "error_rate_4xx", "error_rate_5xx" },
  "http_methods": { "GET": {"count", "pct"}, "POST": {...} },
  "top_ips": [{ "key": "IP", "count": N }],
  "suspicious_ips": [{ "ip", "count", "percentage" }],
  "client_types": { "browser": {"count", "pct"}, "crawler": {...} },
  "top_user_agents": [{ "key": "UA", "count": N }],
  "referer": { "by_type": {...}, "top_domains": [...] },
  "response_size": { "total_bandwidth", "avg_size", "p50", "p95", "p99" }
}
```

### 2. 状态码统计（status_code_analyzer.py）

统计 HTTP 响应状态码分布，按 2xx/3xx/4xx/5xx 分类，计算 4xx 和 5xx 错误率。

**关键指标：**
- 各状态码精确计数（200、301、404、500 等）
- 4xx 客户端错误率
- 5xx 服务端错误率

### 3. QPS 计算（qps_calculator.py）

计算每秒查询率（QPS）及时间维度分布。

**关键指标：**
- 平均 QPS = 总请求数 / 时间跨度（秒）
- 峰值 QPS：1 秒内最大请求数及对应时间
- 每分钟 Top 10  busiest minutes
- 每小时请求分布

### 4. 客户端分类（client_type_analyzer.py）

根据 User-Agent 自动分类为：
- `browser` — 桌面浏览器（Chrome/Firefox/Safari/Edge 等）
- `mobile_browser` — 移动端浏览器
- `cli_tool` — 命令行工具（curl/wget/python-requests 等）
- `crawler` — 爬虫（Googlebot/Baiduspider 等）
- `mobile_app` — 原生移动应用
- `unknown` — 无法识别

### 5. IP 分析（ip_analyzer.py）

统计 IP 访问频率，自动识别疑似攻击源。

**判定规则：**
- 单 IP 占比超过 5% → 标记为 high_percentage
- 单 IP 请求超过 1000 次 → 标记为 high_frequency

### 6. 响应体大小（response_size_analyzer.py）

分析 `body_bytes_sent` 字段的分布特征。

**关键指标：**
- 总带宽（自动转换为 KB/MB/GB）
- 平均响应体大小
- P50 / P95 / P99 百分位
- 按大小桶分布：<1KB、1-10KB、10-100KB、100KB-1MB、>1MB

### 7. Referer 来源（referer_analyzer.py）

分析流量来源，分类为：
- `direct` — 直接访问（无 Referer）
- `search_engine` — 搜索引擎（Google/Baidu/Bing 等）
- `social_media` — 社交媒体（Twitter/Weibo 等）
- `external_site` — 外部站点

同时统计 Top 来源域名排行。

---

## 常见问题与解决方案

### Q: 脚本执行报错 "No module named 'log_parser'"

**原因**：直接从其他目录运行脚本，Python 找不到同目录的 `log_parser.py`。

**解决**：使用完整路径运行：
```bash
python "D:\...\nginx-log-analysis\scripts\full_analysis.py" access.log
```

### Q: 日志解析结果为 0 条

**原因**：日志格式与 `log_parser.py` 中的正则不匹配。

**解决**：
1. 检查 `log-format/` 目录下是否有对应的格式配置
2. 如果没有，先添加正确的 `.conf` 文件
3. 重新选择正确的格式配置

### Q: 大文件分析很慢

**建议**：
- 日志文件 >100MB 时，先截取样本分析：
  ```bash
  head -n 100000 access.log > sample.log
  ```
- 或使用 `--top 5` 减少输出条目

### Q: 如何添加新的日志格式？

**步骤**：
1. 在 `log-format/` 目录下创建 `.conf` 文件
2. 按命名规范命名（如 `newbiz_production_log_custom.conf`）
3. 写入 `log_format` 指令
4. 下次分析时系统会自动列出该格式

### Q: 现有脚本不支持我的日志格式怎么办？

系统支持**动态脚本生成**：
1. 在 `log-format/` 中添加你的格式配置文件
2. 分析时选择该格式
3. 系统会自动根据格式生成适配的解析脚本

---

## 注意事项与最佳实践

### 日志格式配置

- 每个业务线/环境的日志格式应单独配置
- 格式文件命名要清晰，便于多人协作
- 定期检查 `log-format/` 目录，确保配置与实际 nginx 一致

### 性能建议

- 小文件（<10MB）：直接全量分析
- 中等文件（10-100MB）：全量分析可接受，可能需要数十秒
- 大文件（>100MB）：建议先截取样本（前 10 万行），再用样本分析
- 超大文件（>1GB）：建议先按时间段切割，再分段分析

### 安全注意事项

- 日志文件可能包含敏感信息（IP、URL 参数等），注意文件权限
- 分析结果中的 IP 地址排行可用于安全审计，但不应外泄
- 疑似攻击源识别仅供参考，需结合其他安全工具确认

### 最佳实践

1. **先做全量分析**：首次分析时使用 `full_analysis.py`，全面了解日志状况
2. **再深入单项**：根据全量分析结果，针对性地深入某项指标
3. **定期巡检**：建议定期（每周/每天）对关键业务日志做全量分析
4. **建立格式库**：将各业务线的日志格式统一维护在 `log-format/` 中
5. **保留分析记录**：将 JSON 输出保存为文件，便于历史对比