erichutchins/geoipsed
GitHub: erichutchins/geoipsed
基于 Rust 的高性能 IP 地理位置装饰工具，支持流式处理海量日志并实时补充城市、国家、ASN 等元数据。
Stars: 29 | Forks: 3
# geoipsed
_使用 Rust 编写的快速、内联 IPv4 和 IPv6 地址地理地理位置修饰工具_
IP 地理位置信息通过城市、国家、ASN 和时区元数据来丰富日志内容。`geoipsed` 会就地查找并修饰 IP 地址，同时保持现有上下文不变——非常适合事件响应和网络分析。
## 快速开始
```
cargo install geoipsed
echo "Connection from 81.2.69.205 to 175.16.199.37" | geoipsed
```
输出：
```
Connection from <81.2.69.205|AS0_|GB|London> to <175.16.199.37|AS0_|CN|Changchun>
```
## 功能
- 支持带有严格验证的 IPv4 和 IPv6
- 城市、国家、ASN、时区元数据
- 通过 `-t/--template` 实现灵活的模板化
- 内联修饰或 JSON 输出模式（`--tag`、`--tag-files`）
- 细粒度过滤：`--all`、`--no-private`、`--no-loopback`、`--no-broadcast`
- 通过 `-C/--color` 支持颜色显示
- 流式输入（stdin 或多个文件）
- 比 Python 实现快约 100 倍
## 数据库
支持 MaxMind（默认）、IP2Location 和 IPinfo MMDB 格式。使用 `-I` 或 `GEOIP_MMDB_DIR` 环境变量指定位置。
## 用法
```
geoipsed --help
Inline decoration of IPv4 and IPv6 address geolocations
Usage: geoipsed [OPTIONS] [FILE]...
Arguments:
[FILE]... Input file(s) to process. Leave empty or use "-" to read from stdin
Options:
-o, --only-matching Show only nonempty parts of lines that match
-C, --color Use markers to highlight the matching strings [default: auto] [possible values: always, never, auto]
-t, --template Specify the format of the IP address decoration. Use the --list-templates option to see which fields are available. Field names are enclosed in {}, for example "{field1} any fixed string {field2} & {field3}"
--tag Output matches as JSON with tag information for each line
--tag-files Output matches as JSON with tag information for entire files
--all Include all types of IP addresses in matches
--no-private Exclude private IP addresses from matches
--no-loopback Exclude loopback IP addresses from matches
--no-broadcast Exclude broadcast/link-local IP addresses from matches
--only-routable Only include internet-routable IP addresses (requires valid ASN entry)
--provider Specify the MMDB provider to use (default: maxmind) [default: maxmind]
-I Specify directory containing the MMDB database files [env: GEOIP_MMDB_DIR=]
--list-providers List available MMDB providers and their required files
-L, --list-templates Display a list of available template substitution parameters to use in --template format string
-h, --help Print help
-V, --version Print version
```
## 示例
```
# Decoration mode
geoipsed access.log
# 仅匹配的 IP（带 decoration）
geoipsed -o access.log
# 自定义 template
geoipsed -t "{ip} in {country_iso}" access.log
# Filter: 仅公开 IP
geoipsed --no-private --no-loopback --no-broadcast access.log
# Advanced: 带前后 decoration 的匹配范围的 JSON 输出
geoipsed --tag access.log
```
### 仅提取 IP
对于您只需要原始 IP 地址列表的场景（类似于 `grep -o`，但速度更快且带有 IP 验证），请使用独立的 `justips` 工具：
```
cargo install justips
justips access.log
```
`justips` 是提取引擎的一个专门的零依赖版本，在查找 IP 时比 `ripgrep` 快约 45%。
## 性能
`geoipsed` 针对连续 IP 提取进行了高度优化，甚至在此特定任务上超越了 `ripgrep` 本身。
基于 **1.7GB Suricata 日志**（1540 万行，3070 万个 IP 匹配）进行基准测试：
| 工具 | 模式 | 时间 | 吞吐量 | 加速比 |
| :--- | :--- | :---: | :---: | :---: |
| **`justips`** | **Parallel mmap + DFA** | **857ms** | **~2 GiB/s** | **7.2x** |
| `ripgrep` | `rg -ao` (v4/v6 regex) | 6.17s | ~275 MiB/s | 基准 |
| Python (`re`) | `IPRE.sub()` (基准) | 431s | ~4 MiB/s | 0.01x |
对于原始 IP 提取（无地理位置信息），请使用独立的 [`justips`](crates/justips/) 工具——它使用并行 mmap 处理，专为最大吞吐量而构建。
**为什么 DFA 这么快？** 虽然 `ripgrep` 是世界级的通用搜索工具，但 `geoipsed` 和 `justips` 使用了通过 `regex-automata` 生成的专门的编译时 DFA。这使得在扫描期间解析和验证每个 `IpAddr` 的速度比通用 regex 引擎匹配原始文本的速度更快。
## Workspace Crates
| Crate | 描述 |
| :--- | :--- |
| [`ip-extract`](crates/ip-extract/) | 零拷贝 IP 提取库——编译时 DFA、支持 defang、builder 模式 |
| [`justips`](crates/justips/) | 用于快速 IP 提取的独立 CLI——并行 mmap，内置去重（`-u`、`-U`） |
| [`ipextract`](crates/ipextract-py/) | Python 绑定（PyO3 + maturin）——稳定的 ABI，发布于 [PyPI](https://pypi.org/project/ipextract/) |
## 文档
完整文档、架构详情和基准测试可在 [GitHub Pages](https://erichutchins.github.io/geoipsed/) 获取。
## 贡献
请参阅 [CLAUDE.md](CLAUDE.md) 了解项目约定和编码模式。
标签：Docker 部署, IP地理定位, Rust, 命令行工具, 日志分析, 网络流量审计, 网络运维, 通知系统