# 商业 VPN 出口数据集
商业 VPN 出口数据集是一个关于商业 VPN 出口节点和提供商 IP 范围的标准化基础设施数据集。它发布 CSV、JSONL、TXT 和 MaxMind MMDB 格式的产物，可用于安全分析、滥用防护、欺诈/风险评分、速率限制和网络丰富。
## 概述
该仓库直接在 [`release/`](./release/) 下提供最新生成的数据集。
公开的输出旨在供运营使用：
- CSV/JSONL 格式中每个 `(IP, provider)` 占用一行
- 每个 TXT 文件包含一个特定于提供商的 IP 列表
- 兼容 MaxMind 的 MMDB 用于运行时查询
- 提供商级别的健康和数量趋势
- 来源状态和时效性元数据
- 机器可读和人类可读的质量报告
大型数据集文件作为产物发布在 `release/` 中；README 仅引用它们并记录其 schema。
## 仓库产物
### 数据集文件
| 路径 | 格式 | 描述 |
|---|---:|---|
| [`release/vpn.csv`](./release/vpn.csv) | CSV | 主要的 IP 级别数据集 |
| [`release/vpn.jsonl`](./release/vpn.jsonl) | JSONL | 与 CSV 逻辑行相同 |
| [`release/vpn.mmdb`](./release/vpn.mmdb) | MMDB | 兼容 MaxMind 的运行时查询数据库 |
| [`release/provider_ips/`](./release/provider_ips/) | TXT | 每个文件包含一个特定于提供商的 IP 列表 |
### 统计和报告
| 路径 | 格式 | 描述 |
|---|---:|---|
| [`release/provider_counts.csv`](./release/provider_counts.csv) | CSV | 按唯一 IP 数量排序的提供商摘要 |
| [`release/source_status.json`](./release/source_status.json) | JSON | 各来源的状态、错误、缓存状态和时效性 |
| [`release/provider_health.json`](./release/provider_health.json) | JSON | 提供商数量趋势、下降情况及健康状态 |
| [`release/quality_report.json`](./release/quality_report.json) | JSON | 机器可读的发布质量报告 |
| [`release/quality_report.txt`](./release/quality_report.txt) | TXT | 人类可读的质量摘要 |
| [`release/quality_history.jsonl`](./release/quality_history.jsonl) | JSONL | 跨构建的精简质量历史 |
| [`release/run_stats.json`](./release/run_stats.json) | JSON | 构建统计和差异元数据 |
## 输出目录
```
release/
├── provider_counts.csv
├── provider_health.json
├── provider_ips/
│ ├── AirVPN.txt
│ ├── CyberGhost.txt
│ ├── Mullvad.txt
│ ├── NordVPN.txt
│ ├── ProtonVPN.txt
│ └── ...
├── quality_history.jsonl
├── quality_report.json
├── quality_report.txt
├── run_stats.json
├── source_status.json
├── vpn.csv
├── vpn.jsonl
└── vpn.mmdb
```
当前的包体积足够小，适合正常的 Git 存储。MMDB 和 JSONL 文件是最大的产物；需要稳定生产部署的消费者应固定（pin）到特定的 commit hash。
## 快速开始
克隆仓库：
```
git clone https://github.com/ipanalytics/commercial-vpn-exit-dataset.git
cd commercial-vpn-exit-dataset
```
检查生成的报告：
```
cat release/quality_report.txt
head release/provider_counts.csv
```
使用 CSV 数据集：
```
head release/vpn.csv
```
使用特定于提供商的列表：
```
head release/provider_ips/ProtonVPN.txt
```
查询 JSONL 导出：
```
grep '"provider":"Mullvad"' release/vpn.jsonl | head
```
使用 MMDB 数据库：
```
mmdblookup --file release/vpn.mmdb --ip 1.2.3.4
```
## CSV Schema
`release/vpn.csv` 使用稳定的基于表头的 schema。
```
ip,source,provider,type,type_detail,country,city,asn,asn_org,network,is_exit_node,is_hosting,confidence
```
| 列名 | 描述 |
| -------------- | ----------------------------------------- |
| `ip` | IPv4 或 IPv6 地址 |
| `source` | 标准化的来源标识符 |
| `provider` | VPN 提供商名称 |
| `type` | 高级服务类型 |
| `type_detail` | 特定于提供商/来源的详细信息 |
| `country` | 地理位置 |
| `city` | 地理城市名称（如果有） |
| `asn` | 自治系统号 (Autonomous System Number) |
| `asn_org` | ASN 组织 |
| `network` | 匹配的网络前缀 |
| `is_exit_node` | 该 IP 是否被视为出口节点 |
| `is_hosting` | 托管/数据中心网络指示器 |
| `confidence` | 从 `0` 到 `100` 的置信度分数 |
消费者应使用列名而不是位置索引。
## JSONL Schema
`release/vpn.jsonl` 中每个数据集行包含一个 JSON 对象。
示例行：
```
{
"ip": "1.2.3.4",
"source": "provider_metadata",
"provider": "ProviderA",
"type": "vpn",
"type_detail": "commercial",
"country": "US",
"city": "Los Angeles",
"asn": 12345,
"asn_org": "Example ASN",
"network": "1.2.3.0/24",
"is_exit_node": true,
"is_hosting": true,
"confidence": 95
}
```
## MMDB 输出结构
`release/vpn.mmdb` 是一个兼容 MaxMind 的数据库，用于最长前缀匹配查询。它返回隐私、提供商、网络和风险上下文。
示例查询结果：
```
{
"matched_prefix": "1.2.3.4/32",
"privacy": {
"is_vpn": true,
"is_proxy": false,
"is_tor": false,
"is_relay": false,
"is_hosting": true,
"is_exit_node": true,
"vpn_provider": "ProviderA",
"privacy_service": "ProviderA",
"service_names": [
"ProviderA"
],
"service_types": [
"VPN"
],
"privacy_type": "vpn",
"privacy_type_detail": "commercial"
},
"network_context": {
"asn": 12345,
"as_org": "Example ASN",
"geo_country_code": "US",
"geo_city_name": "Los Angeles",
"registry_country_code": "US",
"connection_type": "hosting",
"asn_provider_count": 2,
"asn_service_names": [
"ProviderA",
"ProviderB"
],
"asn_ip_count": 42
},
"risk": {
"score": 65,
"level": "medium_high",
"reasons": [
"commercial_vpn",
"hosting_network"
]
},
"confidence": 95,
"observed_at": "2026-05-17T00:00:00Z"
}
```
### MMDB 字段
| 字段 | 描述 |
| --------------------------------------- | --------------------------------------- |
| `matched_prefix` | 查询匹配的前缀 |
| `privacy.is_vpn` | 商业 VPN 指示器 |
| `privacy.is_proxy` | Proxy 指示器 |
| `privacy.is_tor` | Tor 指示器 |
| `privacy.is_relay` | 中继/隐私网络指示器 |
| `privacy.is_hosting` | 托管/数据中心上下文 |
| `privacy.is_exit_node` | 出口节点分类 |
| `privacy.vpn_provider` | 主要 VPN 提供商 |
| `privacy.privacy_service` | 主要隐私服务名称 |
| `privacy.service_names` | 所有关联的服务名称 |
| `privacy.service_types` | 服务类型标签 |
| `privacy.privacy_type` | 高级隐私类型 |
| `privacy.privacy_type_detail` | 更具体的隐私类型 |
| `network_context.asn` | 自治系统号 (Autonomous System Number) |
| `network_context.as_org` | ASN 组织 |
| `network_context.geo_country_code` | GeoIP 国家代码 |
| `network_context.geo_city_name` | GeoIP 城市名称 |
| `network_context.registry_country_code` | 注册表国家代码 |
| `network_context.connection_type` | 网络连接类型 |
| `network_context.asn_provider_count` | 在 ASN 中观察到的 VPN 提供商数量 |
| `network_context.asn_service_names` | 在 ASN 中观察到的提供商名称 |
| `network_context.asn_ip_count` | ASN 中的数据集 IP 数量 |
| `risk.score` | 风险评分 |
| `risk.level` | 风险等级标签 |
| `risk.reasons` | 风险评分原因 |
| `confidence` | 置信度分数 |
| `observed_at` | 数据集观测时间戳 |
## 报告文件
### `provider_counts.csv`
按唯一 IP 数量排序的提供商摘要。
```
Provider,IPs
NordVPN,9417
WLVPN,3407
IPVanish,3389
Astrill,2723
CyberGhost,2685
```
### `source_status.json`
跟踪来源的健康和时效性。
典型字段：
```
{
"generated_at": "2026-06-20T15:07:00Z",
"sources": {
"source_name": {
"ok": true,
"cached": false,
"stale": false,
"error": null,
"rows": 1234,
"updated_at": "2026-06-20T15:07:00Z"
}
}
}
```
### `provider_health.json`
跟踪提供商级别的数量趋势和健康状态。
典型字段：
```
{
"generated_at": "2026-06-20T15:07:00Z",
"providers": {
"ProviderA": {
"ips": 1234,
"previous_ips": 1200,
"delta": 34,
"status": "ok",
"drop_percent": 0
}
}
}
```
### `quality_report.json`
机器可读的质量门输出。
典型字段：
```
{
"status": "pass",
"generated_at": "2026-06-20T15:07:00Z",
"checks": {
"csv_valid": true,
"jsonl_valid": true,
"mmdb_valid": true,
"provider_counts_valid": true,
"large_provider_drop": false
},
"warnings": [],
"errors": []
}
```
### `quality_report.txt`
人类可读的质量摘要。
```
Quality report: pass
Dataset rows: 28437
Providers: 80
Errors: 0
Warnings: 0
```
### `quality_history.jsonl`
仅追加的精简质量历史。
```
{"generated_at":"2026-06-20T15:07:00Z","status":"pass","rows":28437,"providers":80,"warnings":0,"errors":0}
```
### `run_stats.json`
构建级别的计数器和差异元数据。
典型字段：
```
{
"generated_at": "2026-06-20T15:07:00Z",
"rows": 28437,
"unique_ips": 28437,
"providers": 80,
"added": 120,
"removed": 45,
"changed": 18
}
```
## 提供商覆盖范围
该数据集目前包含商业 VPN 和隐私网络提供商，例如：
| 提供商 | IP 数 |
| ------------- | ------: |
| NordVPN | 9,417 |
| WLVPN | 3,407 |
| IPVanish | 3,389 |
| Astrill | 2,723 |
| CyberGhost | 2,685 |
| AirVPN | 2,024 |
| ProtonVPN | 1,568 |
| Sentinel dVPN | 1,207 |
| Mullvad | 1,145 |
| Windscribe | 1,020 |
完整的提供商列表生成于：
```
release/provider_counts.csv
```
## 用例
| 用例 | 示例 |
| ----------------- | ------------------------------------------------------------------- |
| 欺诈评分 | 为登录、注册、支付和账户事件添加 VPN 提供商上下文 |
| 滥用防护 | 对已知的商业 VPN 出口应用额外检查 |
| 速率限制 | 对高流量的 VPN 提供商进行流量整形 |
| WAF/CDN 丰富 | 在边缘使用 MMDB 查询为请求打标签 |
| 安全分析 | 使用提供商、ASN、地理位置和托管上下文丰富日志 |
| 威胁狩猎 | 将事件与已知的 VPN 出口网络相关联 |
| 数据工程 | 将 VPN 指标与遥测和 ASN 数据集进行连接 |
## 运维说明
VPN 基础设施频繁变动。由于服务器轮换、来源更新、临时来源故障或网络重新分配，提供商数量可能会发生波动。
建议的生产环境操作：
1. 将数据集拉取到预发（staging）路径。
2. 验证 `quality_report.json`。
3. 验证文件的可解析性。
4. 原子替换当前使用的数据集。
5. 重新加载依赖服务。
对于 MMDB 消费者，为了实现可重现的部署，建议固定（pin）到特定的 commit hash。
## 局限性
该数据集是一个丰富信号，而不是独立的执行决策。生产系统应将其与本地遥测、账户历史、行为信号、ASN 信誉和业务策略相结合使用。
一些 VPN 提供商使用共享的托管基础设施、轮换服务器或经销商网络。分类可能会滞后于提供商端的变化。
## 项目范围
范围内：
* 商业 VPN 出口节点
* 提供商级别的 IP 清单
* IP 到提供商的映射
* ASN 和网络上下文
* MMDB 运行时查询
* 质量报告
* 来源和提供商健康元数据
范围外：
* 用户归属
* 流量检查
* 凭据或私钥
* 特定于账户的 VPN 配置
* 主动攻击或服务中断
## 目录结构
```
.
├── release/
│ ├── provider_counts.csv
│ ├── provider_health.json
│ ├── provider_ips/
│ ├── quality_history.jsonl
│ ├── quality_report.json
│ ├── quality_report.txt
│ ├── run_stats.json
│ ├── source_status.json
│ ├── vpn.csv
│ ├── vpn.jsonl
│ └── vpn.mmdb
├── site/
│ └── banner.png
├── README.md
└── LICENSE
```
## 免责声明
本项目发布网络情报，用于防御性操作、分析、研究和基础设施丰富。提供商名称和商标归其各自所有者所有。