RumenDamyanov/nginx-torblocker
GitHub: RumenDamyanov/nginx-torblocker
一款轻量级 Nginx 动态模块，通过自动获取 Tor 出口节点列表实现对 Tor 流量的灵活封锁或放行。
Stars: 6 | Forks: 0
[](https://build.opensuse.org/package/show/home:rumenx/nginx-torblocker)
[](https://github.com/RumenDamyanov/nginx-torblocker/releases)
[](LICENSE.md)
[](https://build.opensuse.org/package/show/home:rumenx/nginx-torblocker)
# Nginx TorBlocker
一个灵活的 Nginx 模块，用于控制来自 Tor exit node 的访问 —— 封锁它们、仅允许它们，或者混合使用不同的策略。
## 功能
- **三种操作模式：**
- `torblock on` - 封锁 Tor exit node 流量
- `torblock off` - 允许所有流量（默认）
- `torblock only` - **仅**允许 Tor 流量（封锁 clearnet）
- **自动获取**来自 URL 的 Tor exit node 列表（无需 cron jobs！）
- 支持 **HTTPS** 安全获取列表（需要 nginx 支持 SSL）
- 可配置的更新间隔，用于自动刷新列表
- 易于配置并与 Nginx 集成
- 支持基于 location 和 server 的配置
- 可在不同的 vhost 和路径中混合使用策略
## 文档与支持
📖 **[完整文档](https://github.com/RumenDamyanov/nginx-torblocker/wiki)** - 包含全面的指南、教程和参考资料
### Wiki 文章快速链接
- 🏠 **[主页](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Home)** - 概述与入门指南
- 📦 **[安装指南](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Installation-Guide)** - 详细的安装步骤说明
- 🔨 **[从源码编译](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Building-from-Source)** - 自行编译该模块
- 📋 **[配置参考](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Configuration-Reference)** - 完整的指令文档
- ⚙️ **[基础配置](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Basic-Configuration)** - 简单的设置示例
- 🚀 **[高级配置](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Advanced-Configuration)** - 复杂的策略与模式
- 🔗 **[上下文层级](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Context-Hierarchy)** - 了解配置继承机制
- 🎯 **[特定站点拦截](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Site-Specific-Blocking)** - 针对特定站点的配置
- 🛣️ **[基于路径的拦截](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Path-Based-Blocking)** - 针对特定 URL 的规则
- 🌐 **[全服务器拦截](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Server-Wide-Blocking)** - 全局配置
- 🔀 **[混合策略](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Mixed-Policies)** - 结合不同的方法
- 📥 **[模块加载](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Module-Loading)** - 加载并初始化模块
- 🧪 **[测试流程](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Testing-Procedures)** - 验证功能与性能
- 🔧 **[故障排除指南](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Troubleshooting-Guide)** - 解决常见问题
- ⚡ **[性能调优](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Performance-Tuning)** - 针对您的环境进行优化
- 📊 **[监控与日志](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Monitoring-Logging)** - 可观测性与指标
- 🛠️ **[开发环境设置](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Development-Setup)** - 贡献与开发环境
## 仓库结构
- `src/` — Nginx 模块源代码
- `debian/` — 打包文件（用于构建 .deb 包）
- `conf/` — 示例配置
## 安装说明
### 包安装（推荐）
可以通过 [openSUSE Build Service](https://build.opensuse.org/package/show/home:rumenx/nginx-torblocker) 获取适用于多种 Linux 发行版的预编译包。
#### Debian / Ubuntu
```
# 添加 repository
echo "deb http://download.opensuse.org/repositories/home:/rumenx/xUbuntu_24.04/ /" | sudo tee /etc/apt/sources.list.d/nginx-torblocker.list
# 添加 repository key
curl -fsSL https://download.opensuse.org/repositories/home:/rumenx/xUbuntu_24.04/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/nginx-torblocker.gpg > /dev/null
# 更新并安装
sudo apt update
sudo apt install nginx-torblocker
```
**支持的版本：**
- Ubuntu 24.04 (Noble) - 使用 `xUbuntu_24.04`
- Ubuntu 22.04 (Jammy) - 使用 `xUbuntu_22.04`
- Debian 12 (Bookworm) - 使用 `Debian_12`
- Debian 13 (Trixie) - 使用 `Debian_13`
将上述命令中的 `xUbuntu_24.04` 替换为您的发行版版本。
#### Fedora
```
# 添加 repository
sudo dnf config-manager --add-repo https://download.opensuse.org/repositories/home:/rumenx/Fedora_41/home:rumenx.repo
# 安装 package
sudo dnf install nginx-torblocker
```
**支持的版本：**
- Fedora 42 - 使用 `Fedora_42`
- Fedora 41 - 使用 `Fedora_41`
- Fedora 40 - 使用 `Fedora_40`
#### openSUSE
```
# 添加 repository
sudo zypper addrepo https://download.opensuse.org/repositories/home:/rumenx/openSUSE_Tumbleweed/home:rumenx.repo
# 刷新 repositories
sudo zypper refresh
# 安装 package
sudo zypper install nginx-torblocker
```
**支持的版本：**
- openSUSE Tumbleweed - 使用 `openSUSE_Tumbleweed`
- openSUSE Leap 15.6 - 使用 `openSUSE_Leap_15.6`
- openSUSE Leap 16.0 - 使用 `openSUSE_Leap_16.0`
#### RHEL / CentOS / Rocky Linux / AlmaLinux
```
# 添加 repository（以 RHEL 9 为例）
sudo dnf config-manager --add-repo https://download.opensuse.org/repositories/home:/rumenx/RHEL_9/home:rumenx.repo
# 安装 package
sudo dnf install nginx-torblocker
```
**支持的版本：**
- RHEL/CentOS 9 - 使用 `RHEL_9`
- RHEL/CentOS 8 - 使用 `RHEL_8`
- RHEL/CentOS 7 - 使用 `RHEL_7`
### 安装后操作
安装该包后，模块将被安装到以下位置：
- **Debian/Ubuntu**：`/usr/lib/nginx/modules/ngx_http_torblocker_module.so`
- **Fedora/RHEL/openSUSE**：`/usr/lib64/nginx/modules/ngx_http_torblocker_module.so`
通过在 `/etc/nginx/nginx.conf` 的顶部添加以下内容来加载模块：
```
load_module modules/ngx_http_torblocker_module.so;
```
然后重启 nginx：
```
sudo systemctl restart nginx
```
## 快速构建说明
📖 **有关详细的构建说明和安装指南，请参阅 [从源码编译](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Building-from-Source) 和 [安装指南](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Installation-Guide) wiki 页面。**
💾 **[Releases 页面](https://github.com/RumenDamyanov/nginx-torblocker/releases) 提供了适用于 Ubuntu 22.04/24.04/25.04 及各种 Nginx 版本的预编译包。**
### 前置条件
- 系统**已安装 Nginx**
- 与已安装版本匹配的 **Nginx 源代码**
- **构建工具**：gcc, make, wget
- **开发库**：libpcre3-dev, zlib1g-dev
您可以在 Ubuntu/Debian 上安装前置条件：
```
sudo apt-get update
sudo apt-get install build-essential gcc libpcre3-dev zlib1g-dev wget
```
在 CentOS/RHEL 上：
```
sudo yum groupinstall "Development Tools"
sudo yum install pcre-devel zlib-devel wget
```
### 构建模块
1. 克隆此代码库：
git clone https://github.com/RumenDamyanov/nginx-torblocker.git
cd nginx-torblocker
2. 下载并解压与您版本匹配的 Nginx 源码：
# 首先检查您的 Nginx 版本
nginx -v
# 下载匹配的源码（以 1.26.0 为例）
wget https://nginx.org/download/nginx-1.26.0.tar.gz
tar xzf nginx-1.26.0.tar.gz
cd nginx-1.26.0
3. 配置并构建模块：
# 配置带有该模块的 Nginx
./configure --add-dynamic-module=../src
# 仅构建模块（而不是完整的 Nginx）
make modules
4. 安装模块：
# 复制到您的 Nginx 模块目录
sudo cp objs/ngx_http_torblocker_module.so /usr/lib/nginx/modules/
# 或者复制到自定义位置
sudo cp objs/ngx_http_torblocker_module.so /etc/nginx/modules/
### 在 Nginx 中加载模块
在您的 `nginx.conf` 顶部添加：
```
load_module modules/ngx_http_torblocker_module.so;
```
## 配置示例
查看 `conf/test.conf` 获取完整示例。基本用法：
```
http {
# Required: DNS resolver for fetching the Tor exit list
resolver 1.1.1.1 9.9.9.9;
# Enable Tor blocking (uses default URL and update interval)
torblock on;
}
```
该模块会从 Tor Project **自动获取** Tor exit node 列表 —— 无需 cron jobs 或外部脚本！
## 配置参考
📋 **有关完整的配置详情，请参阅 [配置参考](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Configuration-Reference) wiki 页面。**
### 指令
| 指令 | 上下文 | 默认值 | 描述 |
|-----------|---------|---------|-------------|
| `torblock` | http, server, location | `off` | 设置模式：`off`、`on` 或 `only` |
| `torblock_list_url` | http | `https://check.torproject.org/torbulkexitlist` | Tor exit node 列表的 URL |
| `torblock_update_interval` | http | `3600000` | 自动更新间隔，以毫秒为单位（1 小时） |
### 模式值
| 模式 | 行为 |
|------|----------|
| `off` | 允许所有流量（默认） |
| `on` | 封锁 Tor exit node 流量 |
| `only` | **仅**允许 Tor 流量，封锁 clearnet |
**注意事项：**
- 该模块需要在 http 块中配置 `resolver` 指令以进行 DNS 解析。为了更好的隐私，您也可以使用本地解析器，如 `127.0.0.53` (systemd-resolved) 或 `127.0.0.1` (dnsmasq/unbound)。
- **HTTPS 支持**：默认 URL 使用 HTTPS。如果您的 nginx 构建时没有包含 SSL 支持 (`--with-http_ssl_module`)，您可以改用 HTTP URL：`http://check.torproject.org/torbulkexitlist`
### 上下文层级
该模块支持具有继承关系的三个层级的配置：
- **HTTP 上下文**：所有服务器的全局默认设置
- **Server 上下文**：针对每个虚拟主机的设置
- **Location 上下文**：针对每个 URL 路径的设置
子上下文继承父上下文的配置，更具体的设置会覆盖通用的设置。
📖 **在 wiki 中了解更多关于 [上下文层级](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Context-Hierarchy) 的信息。**
## 使用示例
🚀 **有关高级配置示例，请参阅 [高级配置](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Advanced-Configuration) wiki 页面。**
### 基础配置
```
http {
resolver 1.1.1.1 9.9.9.9; # Required for DNS resolution
# Enable Tor blocking with automatic list updates
torblock on;
}
```
### 高级配置
```
http {
resolver 1.1.1.1 9.9.9.9 valid=300s;
resolver_timeout 5s;
# Optional: custom URL and update interval
torblock_list_url "https://check.torproject.org/torbulkexitlist";
torblock_update_interval 600000; # Update every 10 minutes
# Per-server configuration
server {
torblock off; # Disable for this server
location /api {
torblock on; # Re-enable for specific location
}
}
server {
server_name secure.example.com;
torblock on; # Enable for this server
location /public {
torblock off; # Allow Tor for public content
}
}
}
```
### 基于位置的选择性拦截
```
http {
resolver 1.1.1.1 9.9.9.9;
torblock off; # Default: allow Tor
server {
listen 80;
server_name example.com;
# Public content - Tor allowed
location / {
root /var/www/html;
}
# Admin area - block Tor
location /admin {
torblock on;
}
# API - block Tor
location /api {
torblock on;
}
}
}
```
### 结合全局、Server 和 Location 设置
您可以在不同层级启用或禁用该模块，以实现灵活的访问控制。例如：
```
http {
resolver 1.1.1.1 9.9.9.9;
torblock off; # Default: allow Tor everywhere
# Enable Tor blocking only for a specific vhost
server {
server_name sensitive.example.com;
torblock on; # Block Tor for this vhost
# But allow Tor for a specific location (e.g., public API)
location /public-api {
torblock off;
}
}
# Another vhost with default (Tor allowed)
server {
server_name open.example.com;
# torblock remains off
}
}
```
**使用场景：**
- 如果您想对站点的敏感部分（例如管理面板或私有内容）封锁 Tor，但允许 Tor 用户访问公共 API 或开放资源，此设置非常有用。您也可以在同一个 Nginx 实例中让某些 vhost 对 Tor 开放，而保护其他 vhost。
### 仅限 Tor 模式（专属 Tor 访问）
使用 `torblock only` 来**仅**允许 Tor 流量并封锁常规 (clearnet) 连接。这对于注重隐私的服务或 .onion 风格的 endpoint 非常有用。
```
http {
resolver 1.1.1.1 9.9.9.9;
# Privacy-focused service - Tor only
server {
listen 80;
server_name private.example.com;
torblock only; # Only Tor users can access
}
# Regular site - allow all
server {
listen 80;
server_name public.example.com;
torblock off; # Everyone can access
}
}
```
### 混合策略（封锁、允许、仅限 Tor）
结合所有三种模式以实现最大的灵活性：
```
http {
resolver 1.1.1.1 9.9.9.9;
torblock off; # Default: allow all traffic
server {
listen 80;
server_name example.com;
# Public pages - allow everyone
location / {
torblock off;
}
# Admin panel - block Tor users
location /admin {
torblock on;
}
# Whistleblower submission - Tor users only
location /secure-submit {
torblock only;
}
}
}
```
**`torblock only` 的使用场景：**
- 举报人或匿名提交门户
- 注重隐私的通信 endpoint
- 测试 Tor 可访问性
- 只能匿名访问的服务
## 故障排除
🔧 **有关全面的故障排除指南，请参阅：**
- **[故障排除指南](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Troubleshooting-Guide)** - 详细的诊断流程和解决方案
- **[测试流程](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Testing-Procedures)** - 验证您的配置和性能
- **[性能调优](https://github.com/RumenDamyanov/nginx-torblocker/wiki/Performance-Tuning)** - 针对您的环境进行优化
### 常见问题
#### 模块加载失败
```
nginx: [emerg] dlopen() "/usr/lib/nginx/modules/ngx_http_torblocker_module.so" failed
```
**解决方案：**
- 确保模块是基于您正在运行的相同 Nginx 版本构建的
- 检查文件权限：`chmod 644 /usr/lib/nginx/modules/ngx_http_torblocker_module.so`
- 验证您的 `load_module` 指令中的模块路径是否正确
#### 配置测试失败
```
nginx: [emerg] unknown directive "torblock"
```
**解决方案：**
- 确保 `load_module` 指令位于 `nginx.conf` 的顶部（在任何 `http` 块之前）
- 验证模块文件存在且可读
- 检查 Nginx 错误日志以获取详细的错误信息
#### 模块版本不匹配
```
nginx: [emerg] module "/usr/lib/nginx/modules/ngx_http_torblocker_module.so" version 1024000 instead of 1026000
```
**解决方案：**
- 针对您确切的 Nginx 版本重新构建模块
- 使用 `nginx -v` 下载正确的 Nginx 源码版本
### 性能考量
- **内存使用**：该模块会在内存中维护 Tor exit node 列表
- **更新频率**：默认 1 小时的更新在时效性和性能之间取得了平衡
- **请求开销**：影响极小 —— 每次请求仅进行简单的 IP 查找
- **并发请求**：该模块对于多 worker 配置是线程安全的
### 调试
在 Nginx 中启用调试日志：
```
error_log /var/log/nginx/debug.log debug;
```
检查模块特定的消息：
```
grep torblock /var/log/nginx/error.log
```
## 背景与灵感
该模块的灵感来源于我 20 多年前开发的一个名为 [AntiTor](https://github.com/RumenDamyanov/antitor) 的 PHP 脚本，该脚本成功封锁了 Web 服务器的 Tor 访问。最初的脚本很有效，但适用范围有限。
-torblocker 模块将这一概念带入了现代，并进行了几项关键改进：
- **原生性能**：在 Nginx 层级而非 PHP 应用层运行
- **精细化控制**：可以按虚拟主机或 location 启用/禁用拦截
- **选择性访问**：在封锁敏感区域的同时，允许 Tor 访问公共资源
- **多站点支持**：在同一服务器上为多个站点提供不同的策略
- **自动更新**：无需人工干预即可保持 Tor exit node 列表最新
这种改进的方法允许实现原始脚本无法实现的复杂访问控制策略，使其适用于不同站点可能有不同安全要求的复杂托管环境。
## 二进制包与发行
### 官方发行版
预编译二进制文件的主要分发渠道是 [GitHub Releases 页面](https://github.com/RumenDamyanov/nginx-torblocker/releases)，它提供：
- 适用于 Ubuntu 22.04 LTS (jammy)、24.04 LTS (noble) 和 25.04 (plucky) 的**二进制包**
- **多种架构**：amd64 和 arm64
- **多个 nginx 版本**：兼容 nginx 1.26.x 和 1.27.x 系列
- **Debian 软件包 (.deb)**：可通过 `dpkg` 进行本地安装
### PPA 状态
实验性的 Ubuntu PPA **不再受支持**并已停止维护。它从来都不是官方的分发渠道，而且在生产环境中被证明是不可靠的。
### 未来计划
我们计划建立一个自托管的 apt 仓库，以提供已签名、可重现的构建版本，而不受第三方托管的限制。此仓库将托管我们项目的多个软件包，并将目标定为：
- Ubuntu 24.04 LTS (noble) 及更新版本
- Ubuntu 25.04 (plucky) 及更新版本
目前，请使用官方的 GitHub Releases 或从源码进行编译。
## 相关项目
我们维护的其他 nginx 动态模块：
| 模块 | 描述 | GitHub | OBS |
|--------|-------------|--------|-----|
| **nginx-gone** | 为永久移除的 URI 返回 HTTP 410 Gone | [GitHub](https://github.com/RumenDamyanov/nginx-gone) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-gone) |
| **nginx-cf-realip** | 自动获取 Cloudflare edge IP 列表，用于恢复真实客户端 IP | [GitHub](https://github.com/RumenDamyanov/nginx-cf-realip) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-cf-realip) |
| **nginx-waf** | 基于 IP/CIDR 的访问控制，支持命名列表和基于标签的组织 | [GitHub](https://github.com/RumenDamyanov/nginx-waf) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-waf) |
| **nginx-waf-api** | 用于动态管理 nginx-waf IP 列表的 REST API daemon | [GitHub](https://github.com/RumenDamyanov/nginx-waf-api) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-waf-api) |
| **nginx-waf-feeds** | nginx-waf 的自动威胁情报源更新器 | [GitHub](https://github.com/RumenDamyanov/nginx-waf-feeds) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-waf-feeds) |
| **nginx-waf-ui** | nginx-waf 的 Web 管理界面 | [GitHub](https://github.com/RumenDamyanov/nginx-waf-ui) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-waf-ui) |
| **nginx-waf-lua** | nginx-waf 的 OpenResty/Lua 集成 | [GitHub](https://github.com/RumenDamyanov/nginx-waf-lua) | [OBS](https://build.opensuse.org/package/show/home:rumenx/nginx-waf-lua) |
### Apache HTTP Server 版本
所有模块也适用于 Apache httpd：
| 模块 | 描述 | GitHub | OBS |
|--------|-------------|--------|-----|
| **apache-torblocker** | 控制来自 Tor exit node 的访问 | [GitHub](https://github.com/RumenDamyanov/apache-torblocker) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-torblocker) |
| **apache-gone** | 为永久移除的 URI 返回 HTTP 410 Gone | [GitHub](https://github.com/RumenDamyanov/apache-gone) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-gone) |
| **apache-cf-realip** | 通过 `mod_remoteip` 恢复 Cloudflare 真实 IP | [GitHub](https://github.com/RumenDamyanov/apache-cf-realip) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-cf-realip) |
| **apache-waf** | 带有命名列表的基于 IP/CIDR 的访问控制 | [GitHub](https://github.com/RumenDamyanov/apache-waf) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-waf) |
| **apache-waf-api** | 用于动态 WAF IP 列表管理的 REST API | [GitHub](https://github.com/RumenDamyanov/apache-waf-api) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-waf-api) |
| **apache-waf-feeds** | apache-waf 的自动威胁情报源更新器 | [GitHub](https://github.com/RumenDamyanov/apache-waf-feeds) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-waf-feeds) |
| **apache-waf-ui** | apache-waf 的 Web 管理界面 | [GitHub](https://github.com/RumenDamyanov/apache-waf-ui) | [OBS](https://build.opensuse.org/package/show/home:rumenx/apache-waf-ui) |
## 贡献
我们欢迎您的贡献！请参阅我们的[贡献指南](CONTRIBUTING.md)获取有关以下内容的详细信息：
- 设置开发环境
- 编码规范与最佳实践
- 测试流程
- Pull request 流程
参与之前，请务必阅读我们的[行为准则](CODE_OF_CONDUCT.md)。
🗣️ **加入讨论**：使用我们的[社区讨论区](https://github.com/RumenDamyanov/nginx-torblocker/discussions)来：
- 提出新功能或改进建议
- 分享您的使用场景和配置
- 获取有关开发设置的帮助
- 与其他贡献者和用户交流
## 安全
安全对我们至关重要。如果您发现安全漏洞，请参阅我们的[安全政策](SECURITY.md)了解如何负责任地报告它。
## 资金支持
如果您觉得这个项目有用，请考虑支持它的开发。有关赞助和捐款的信息，请参阅 [FUNDING.md](FUNDING.md)。
## 许可证
BSD 许可证。请参阅 [LICENSE.md](LICENSE.md)。
标签：Nginx, Streamlit, Tor代理, 动态模块, 客户端加密, 流量过滤, 网络安全, 访问控制, 隐私保护