r3bo0tbx1/tor-guard-relay

## 🚀 这是什么？ **Tor Guard Relay** 是一个可用于生产环境、具备自我修复能力的 Tor 中继容器，专为希望安全高效地为 Tor 网络做出贡献的隐私倡导者而设计。 ### 为什么选择这个项目？ - 🛡️ **安全第一** - 加固的 Alpine Linux，非 root 用户运行，最小化端口暴露 - 🪶 **非常轻量** - 超精简的 16.8 MB 镜像 - 🎯 **简单易用** - 一条命令即可部署，只需极少的配置 - 📊 **可观测性** - 6 个仅依赖 busybox 的诊断工具和 JSON 健康 API - 🌉 **多模式** - 支持 guard、exit 和 bridge (obfs4) 中继 - 🔄 **全自动化** - 每周安全重建，随时可供 CI/CD 使用 - 📚 **文档齐全** - 提供涵盖部署、监控、备份等方面的详尽指南 - 🏗️ **多架构** - 原生支持 AMD64 和 ARM64（如 Raspberry Pi、AWS Graviton 等） ### 🌐 实时生产网络 **久经生产环境考验。** 在线查看：**[relays.brokenbotnet.com](https://relays.brokenbotnet.com/)** 🌉 **Bridges** (Obfs4) • 🛡️ **Middle/Guard** • 🚪 **Exit** 遍布 **15 个国家** ## 🔒 安全模型 ### 端口暴露策略 - **9001** ORPort，公开 - **9002** 用于 bridge 模式的 obfs4 - DirPort，默认**禁用 (0)** ### 环境变量 - `TOR_ORPORT` 默认为 9001 - `TOR_OBFS4_PORT` 默认为 9002 - `TOR_DIRPORT` 默认为 0（禁用） 诊断仅通过 `docker exec` 运行，不暴露任何监控端口。 最小化攻击面，镜像大小约 16.8 MB。 ## ⚡ 快速开始 ### 系统要求 | 组件 | 最低要求 | 推荐配置 | |----------|----------|-------------| | CPU | 1 核 | 2+ 核 | | RAM | 512 MB | 1 GB+ | | 硬盘 | 10 GB | 20 GB+ SSD | | 带宽 | 10 Mbps | 100+ Mbps | | 在线率 | 95% | 99% | | Docker | 20.10+ | 最新版 | **支持的架构：** AMD64, ARM64 ### 网络安全说明 ⚠️ **端口暴露：** - **Guard/Middle/Exit：** 端口 9001 (ORPort) 应可公开访问 - **Bridge：** 端口 9001 (ORPort) 和 9002 (obfs4) 应可公开访问 - **无监控端口** - 所有诊断仅通过 `docker exec` 命令进行 - 使用 `--network host` 以获得最佳的 IPv6 支持（Tor 推荐做法） ### 交互式快速开始（推荐初学者使用） **🚀 试试我们的交互式安装脚本：** ``` # 下载并运行 quick-start 脚本 curl -fsSL https://raw.githubusercontent.com/r3bo0tbx1/tor-guard-relay/main/scripts/quick-start.sh -o quick-start.sh chmod +x quick-start.sh && sh ./quick-start.sh ``` 该脚本将会： - ✅ 引导您选择中继类型（guard、exit、bridge） - ✅ 在验证后收集所需信息 - ✅ 生成部署命令或 docker-compose.yml - ✅ 提供后续步骤和监控指导 ### 手动部署 **第 1 步：** 创建您的中继配置（或使用我们的[示例](examples/relay-guard.conf)）： ``` mkdir -p ~/tor-relay && cd ~/tor-relay && curl -o relay.conf https://raw.githubusercontent.com/r3bo0tbx1/tor-guard-relay/refs/heads/main/examples/relay-guard.conf && nano relay.conf ``` **第 2 步：** 运行（通过 Docker Hub） ``` docker run -d \ --name tor-relay \ --restart unless-stopped \ --network host \ --security-opt no-new-privileges:true \ -v $(pwd)/relay.conf:/etc/tor/torrc:ro \ -v tor-guard-data:/var/lib/tor \ -v tor-guard-logs:/var/log/tor \ r3bo0tbx1/onion-relay:latest ``` **第 3 步：** 验证其是否正在运行： ``` # 检查状态 docker exec tor-relay status # 查看 fingerprint docker exec tor-relay fingerprint # 查看日志 docker logs -f tor-relay ``` **大功告成！** 您的中继将在 10-30 分钟内完成引导，并在 1-2 小时内出现在 [Tor Metrics](https://metrics.torproject.org/rs.html) 上。 ## 🎯 选择版本 我们提供 **两种构建版本**，以匹配您的风险承受能力和需求： ### Stable 版本（推荐） **基础：** Alpine 3.24.1 | **推荐用于：** 生产环境中继 - ✅ 经过实战检验的 Alpine 稳定版 - ✅ 每周自动重建，包含最新安全补丁 - ✅ 具备久经考验的稳定性，适合长期运行的中继 - ✅ 在 **Docker Hub** 和 **GHCR** 上均可用 ``` # 从 Docker Hub 拉取（最简单） docker pull r3bo0tbx1/onion-relay:latest docker pull r3bo0tbx1/onion-relay:2.0.0 # 从 GHCR 拉取 docker pull ghcr.io/r3bo0tbx1/onion-relay:latest docker pull ghcr.io/r3bo0tbx1/onion-relay:2.0.0 ``` ### Edge 版本（仅用于测试） **基础：** Alpine edge | **推荐用于：** 测试、安全研究 - ⚡ 最前沿的 Alpine 软件包（更快获取安全更新） - ⚡ 第一时间获取最新的 Tor 和 obfs4 版本 - ⚡ **更频繁的重建** - 每 3 天 + 每周一次（更新速度比 stable 快约 2-3 倍） - ⚠️ **不建议用于生产环境** - 稳定性较差，可能存在破坏性更新 - 📦 在 Docker Hub 和 GHCR 上均可用 ``` # 从 Docker Hub 拉取 docker pull r3bo0tbx1/onion-relay:edge # 从 GHCR 拉取 docker pull ghcr.io/r3bo0tbx1/onion-relay:edge docker pull ghcr.io/r3bo0tbx1/onion-relay:2.0.0-edge ``` **何时使用 edge 版本：** - 🔬 在稳定版发布前测试新的 Tor 功能 - 🛡️ 需要最新软件包的安全研究 - 🧪 非生产环境的测试环境 - 🚀 愿意承担潜在不稳定性的早期尝鲜者 ## 🏗️ 部署方式 选择适合您工作流的方式。 | 方式 | 最适合 | 指南 | |--------|----------|--------| | 🐳 Docker CLI | 快速测试 | [指南](docs/DEPLOYMENT.md#method-1-docker-cli) | | 📦 Docker Compose | 生产环境 | [指南](docs/DEPLOYMENT.md#method-2-docker-compose) | | ☁️ Cosmos Cloud | 基于界面的部署 | [指南](docs/DEPLOYMENT.md#method-3-cosmos-cloud) | | 🎛️ Portainer | Web UI | [指南](docs/DEPLOYMENT.md#method-4-portainer) | **刚接触 Docker？** 试试由 [azukaar](https://github.com/azukaar) 开发的 [Cosmos Cloud](https://cosmos-cloud.io/) —— 一个华丽且可自托管的 Docker 管理平台。 ### 多中继设置 需要运行多个中继？我们为您准备了模板： - **Docker Compose：** [docker-compose-multi-relay.yml](https://github.com/r3bo0tbx1/tor-guard-relay/blob/main/templates/docker-compose/docker-compose-multi-relay.yml) - 3 个中继设置 - **Cosmos Cloud：** [cosmos-compose-multi-relay.json](https://github.com/r3bo0tbx1/tor-guard-relay/blob/main/templates/cosmos-compose/cosmos-compose-multi-relay.json) - 多中继堆栈 完整说明请参阅[部署指南](docs/DEPLOYMENT.md)。 ## 🔧 诊断工具 内置了六个仅依赖 busybox 的诊断工具。 | 工具 | 用途 | 用法 | |------|---------|--------| | status | 完整健康报告 | `docker exec tor-relay status` | | health | JSON 健康信息 | `docker exec tor-relay health` | | fingerprint | 显示指纹 | `docker exec tor-relay fingerprint` | | bridge-line | obfs4 桥接行 | `docker exec tor-relay bridge-line` | | gen-auth | Nyx 的凭证 | `docker exec tor-relay gen-auth` | | gen-family | Happy Family 密钥生成 | `docker exec tor-relay gen-family MyRelays` | ``` # 带有 emojis 的完整健康报告 docker exec tor-relay status # 用于 automation/monitoring 的 JSON 输出 docker exec tor-relay health ``` JSON 示例： ``` { "status": "up", "pid": 1, "uptime": "01:00:00", "bootstrap": 100, "reachable": "true", "errors": 0, "nickname": "MyRelay", "fingerprint": "1234567890ABCDEF" } ``` ## 📊 监控与可观测性 支持**实时 CLI 监控和外部可观测性**，以实现最小化的镜像体积和最大化的安全性。 ### 实时监控 您可以通过 Control Port 安全地将 Nyx（前身为 arm）连接到您的中继。 1. 生成凭证：`docker exec tor-relay gen-auth` 2. 将哈希值添加到您的配置中 3. 通过本地 socket 或 TCP 连接 ### JSON 健康 API `health` 工具提供用于监控集成的 JSON 输出： ``` # 获取健康状态（原始 JSON） docker exec tor-relay health # 使用 jq 解析（要求 HOST 机器上已安装 jq） docker exec tor-relay health | jq . # 基于 cron 的监控示例 */5 * * * * docker exec tor-relay health | jq '.status' | grep -q 'healthy' || alert ``` ## 🎯 核心特性 ### 安全性与可靠性 - ✅ 非 root 用户执行（以 `tor` 用户运行） - ✅ 超精简 Alpine Linux 基础镜像（**约 16.8 MB**） - ✅ 仅依赖 Busybox 的工具（无 bash/python 依赖） - ✅ 启动时自动修复权限 - ✅ 启动前进行配置验证 - ✅ Tini init 提供正确的信号处理 - ✅ 带有清理机制的平滑关闭 ### 运维与自动化 - ✅ **6 个仅依赖 busybox 的诊断工具**（status、health、fingerprint、bridge-line、gen-auth、gen-family） - ✅ 用于监控集成的 **JSON 健康 API** - ✅ **多模式支持**（guard、exit、带有 obfs4 的 bridge） - ✅ **Happy Family 支持**（Tor 0.4.9.2-alpha 或更高版本，使用基于密钥的中继家族） - ✅ **基于环境变量的配置** (TOR_RELAY_MODE, TOR_NICKNAME, TOR_FAMILY_ID 等) - ✅ **多架构** 构建 (AMD64, ARM64) - ✅ 通过 GitHub Actions 实现**每周安全重建** - ✅ 用于单/多中继的 **Docker Compose 模板** - ✅ 支持一键部署的 **Cosmos Cloud** - ✅ **自动化维护：** 保留最近 14 个 GHCR 软件包版本和 14 个 Docker Hub 版本标签 ### 开发者体验 - ✅ 全面的文档（8 份指南） - ✅ 包含示例配置 - ✅ GitHub issue 模板 - ✅ 自动依赖更新 - ✅ CI/CD 验证和测试 - ✅ 多架构支持（同一命令，任意平台） ## 🖼️ 图库

Cosmos Cloud Dashboard	Docker Logs (Bootstrapping)
Relay Status Tool	obfs4 Bridge Line
Nyx Bandwidth Monitoring

## 📚 文档 按主题组织的**全面文档**： ### 入门指南 - **[常见问题](docs/FAQ.md)** - 提供事实解答的常见问题 - **[快速开始脚本](scripts/utilities/quick-start.sh)** - 交互式中继部署向导 - **[迁移助手](scripts/migration/migrate-from-official.sh)** - 从 thetorproject/obfs4-bridge 自动迁移 - **[部署指南](docs/DEPLOYMENT.md)** - Docker CLI、Compose、Cosmos Cloud 和 Portainer 的完整安装说明 - **[迁移指南](docs/MIGRATION-V1.1.X.md)** - 升级到最新版本或从其他 Tor 设置中迁移 ### 技术参考 - **[架构](docs/ARCHITECTURE.md)** - 包含 Mermaid 图表的技术架构 - **[工具参考](docs/TOOLS.md)** - 所有 6 个诊断工具的完整指南 - **[监控指南](docs/MONITORING.md)** - 外部监控集成、JSON 健康 API、警报和可观测性 - **[Control Port 指南](docs/CONTROL-PORT.md)** - 身份验证设置和 Nyx 集成 - **[备份指南](docs/BACKUP.md)** - 数据持久化、恢复和灾难规划 - **[性能指南](docs/PERFORMANCE.md)** - 优化、调优和资源管理 ### 法律与社区 - **[法律考量](docs/LEGAL.md)** - 运行 Tor 中继的法律层面 - **[文档索引](docs/README.md)** - 完整的文档导航 ### 项目信息 - **[安全政策](SECURITY.md)** - 安全实践和漏洞报告 - **[贡献指南](CONTRIBUTING.md)** - 如何为项目做出贡献 - **[行为准则](CODE_OF_CONDUCT.md)** - 社区准则 - **[更新日志](CHANGELOG.md)** - 版本历史与变更 ## 🛠️ 配置 ### 最小化配置 ``` Nickname MyTorRelay ContactInfo email:your-email[]example.com url:https://example.com proof:uri-familyid-ed25519 ciissversion:3 ORPort 9001 ORPort [::]:9001 DirPort 0 ExitRelay 0 SocksPort 0 DataDirectory /var/lib/tor Log notice file /var/log/tor/notices.log ``` 生产环境配置 ``` RelayBandwidthRate 50 MBytes RelayBandwidthBurst 100 MBytes NumCPUs 2 MaxMemInQueues 512 MB ORPort [::]:9001 ``` ### 示例配置 完整的带注释配置文件可以在 [`examples/`](examples/) 目录中找到： - **[relay-guard.conf](examples/relay-guard.conf)** - 推荐的生产环境配置 - 针对特定用例的其他示例 ### Happy Family (Tor 0.4.9.2-alpha 或更高版本) Tor 0.4.9.2-alpha 引入了 **Happy Families**，这是一种基于加密密钥的 `MyFamily` 替代方案。家族中的所有中继共享一个密钥，而无需在每个中继的配置中列出所有其他中继的指纹。 **为什么升级？** - 减少由重复的 `MyFamily` 列表引起的描述符开销 - 更易于维护 - 使用一个密钥文件代替 N×N 个指纹条目 **快速设置：** ``` # 1. 生成一个 family key（在任意一个 relay 容器上运行） docker exec tor-relay gen-family MyRelays # 2. 将 key 复制到其他 relay 容器 docker cp tor-relay:/var/lib/tor/keys/MyRelays.secret_family_key . docker cp MyRelays.secret_family_key other-relay:/var/lib/tor/keys/ # 3. 修复目标容器内的权限 docker exec -u 0 other-relay chown 100:101 /var/lib/tor/keys/MyRelays.secret_family_key docker exec -u 0 other-relay chmod 600 /var/lib/tor/keys/MyRelays.secret_family_key # 4. 将 FamilyId 添加到每个 relay 的 torrc 中，然后重启 docker restart tor-relay other-relay ``` **torrc 配置：** 在过渡期间，请**同时**配置 `FamilyId` 和 `MyFamily`： ``` # Happy Family（Tor 0.4.9.2-alpha 或更高版本） FamilyId wweKJrJxUDs1EdtFFHCDtvVgTKftOC/crUl1mYJv830 # MyFamily（旧版 - 在过渡期间保留） MyFamily 9A2B5C7D8E1F3A4B6C8D0E2F4A6B8C0D2E4F6A8B MyFamily 1F3E5D7C9B0A2F4E6D8C0B2A4F6E8D0C2B4A6F8E ``` Tor Project 将会宣布何时可以移除 `MyFamily`。 **基于 ENV 的配置（替代挂载的 torrc）：** `TOR_FAMILY_ID` 接受由 Tor 生成的确切的 43 字符无填充 base64 值。 ``` environment: TOR_FAMILY_ID: "wweKJrJxUDs1EdtFFHCDtvVgTKftOC/crUl1mYJv830" TOR_MY_FAMILY: "FINGERPRINT1,FINGERPRINT2,FINGERPRINT3" ``` ## 🔍 监控您的中继 ### 检查引导状态 ``` # 快速状态 docker exec tor-relay status # 用于 automation 的 JSON 输出（原始） docker exec tor-relay health # 使用 jq 解析特定字段（要求 host 上有 jq） docker exec tor-relay health | jq .bootstrap ``` ### 在 Tor Metrics 上查看 1-2 小时后，找到您的中继： 🔗 **[Tor Metrics Relay Search](https://metrics.torproject.org/rs.html)** 搜索方式： - 昵称（例如，“MyTorRelay”） - 指纹（通过 `docker exec tor-relay fingerprint` 获取） - IP 地址 ### 预期时间线 | 里程碑 | 时间 | 预期情况 | |-----------|------|----------------| | 引导完成 | 10-30 分钟 | 日志显示 "Bootstrapped 100%" | | 出现在共识中 | 1-3 小时 | 中继可在 Tor Metrics 搜索中可见 | | 带宽上限解除 | 约 3 天 | bwauths 对您进行测量；移除 20 KB/s 上限，流量开始攀升 | | 首次统计 | 24-48 小时 | Tor Metrics 上出现带宽图表 | | Guard 标志 | **8 天以上** | 有资格被客户端选为入口 guard | ## 🐛 故障排除 ### 快速诊断 ``` # 检查总体状态 docker exec tor-relay status # 检查 JSON 健康状况（原始） docker exec tor-relay health # 查看 fingerprint docker exec tor-relay fingerprint # 对于 bridge 模式：获取 bridge line docker exec tor-relay bridge-line # 生成 Control Port hash docker exec tor-relay gen-auth # 生成/查看 Happy Family key docker exec tor-relay gen-family MyRelays docker exec tor-relay gen-family --show ``` ### 常见问题 | 问题 | 快速解决 | |---------|-----------| | 容器无法启动 | 检查日志：`docker logs tor-relay` | | 权限/所有权错误 | 参阅 [部署指南](docs/DEPLOYMENT.md#bind-mount-ownership) | | ORPort 无法访问 | 检查防火墙：`sudo ufw allow 9001/tcp` | | 未出现在 Tor Metrics | 等待 24 小时，确认引导已完成 | | 流量过低/没有流量 | 对于新中继是正常现象（需要 2-8 周建立声誉） | ## 🏢 架构与设计 ### 为什么使用 Host 网络模式？ 本项目出于重要原因使用 `--network host`： - ✅ **IPv6 支持** - 直接访问主机的 IPv6 协议栈 - ✅ **无 NAT** - Tor 直接绑定到端口，无需地址转换 - ✅ **更好的性能** - 消除了网络开销 - ✅ **Tor 推荐** - 遵循 Tor Project 的最佳实践 **安全性：** 容器仍然以非 root 用户身份运行，并具有限制性权限。Host 网络对于 Tor 中继来说是标准做法。 ### 多架构支持 Docker 会自动拉取正确的架构： ``` # 相同的命令适用于： # - x86_64 服务器（拉取 amd64） # - Raspberry Pi（拉取 arm64） # - AWS Graviton（拉取 arm64） docker pull r3bo0tbx1/onion-relay:latest ``` 验证您获取的版本： ``` docker exec tor-relay cat /build-info.txt | grep Architecture ``` ## 🤝 贡献 欢迎您的贡献。 - 🐛 通过 [GitHub Issues](https://github.com/r3bo0tbx1/tor-guard-relay/issues) **报告 Bug** - 💡 **提出功能建议**或改进意见 - 📖 **改进文档**（拼写错误、清晰度、示例） - 🔧 **提交 Pull Request**（代码、配置、工作流） - ⭐ **给仓库点 Star** 以表示支持 - 🧅 **运行一个中继** 并强化网络！ ### 开发环境设置 ``` # Clone repository git clone https://github.com/r3bo0tbx1/tor-guard-relay.git cd tor-guard-relay # 本地 Build docker build -t tor-relay:dev . # Test docker run --rm tor-relay:dev status ``` 详细说明请参阅[贡献指南](CONTRIBUTING.md)。 ## 🔐 安全 ### ⚠️ 版本弃用通知 ### 最佳实践 ✅ 使用受限权限存储 `relay.conf` (`chmod 600`) ✅ 切勿将包含敏感信息的配置提交到 Git ✅ 在 ContactInfo 中使用 [CIISS v3](https://nusenu.github.io/ContactInfo-Information-Sharing-Specification/) 格式进行验证 ✅ 定期更新 Docker 镜像以获取安全补丁 ✅ 监控日志中的可疑活动 ✅ 正确配置防火墙 ### 安全政策 发现漏洞？请参阅我们的[安全政策](SECURITY.md)进行负责任的披露。 ### 更新 镜像会按照各自的独立时间表自动重建，以包含安全补丁： **Stable 版本** (`:latest`) - **时间表：** 每周日 UTC 时间 18:30 - **包含：** 最新的 Tor + Alpine 3.24.1 更新 - **策略：** 使用更新后的软件包覆盖上一个发布版本（例如 `:2.0.0`） - **更新的标签：** `:latest` 及版本标签（例如 `:2.0.0`） **Edge 版本** (`:edge`) - **时间表：** 每 3 天的 UTC 时间 12:00（独立时间表） - **包含：** 最新的 Tor + Alpine edge（最前沿）更新 - **策略：** 使用更新后的软件包覆盖上一个发布版本（例如 `:2.0.0-edge`） - **更新的标签：** `:edge` 及版本标签（例如 `:2.0.0-edge`） - **频率：** 更新频率比 stable 高约 2-3 倍 所有镜像自动发布到 Docker Hub 和 GitHub Container Registry。 ## 🌐 资源 ### 容器镜像仓库 - 🐳 [Docker Hub 仓库](https://hub.docker.com/r/r3bo0tbx1/onion-relay) - 📦 [GitHub Container Registry](https://github.com/r3bo0tbx1/tor-guard-relay/pkgs/container/onion-relay) ### 官方 Tor Project - 📚 [中继设置指南](https://community.torproject.org/relay/setup/) - 💬 [中继运营商论坛](https://forum.torproject.org/c/relay-operators) - 📧 [邮件列表](https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-relays) - 📊 [Tor Metrics](https://metrics.torproject.org/) ### 本项目 - 📖 [文档](docs/README.md) - 🐛 [Issue 跟踪器](https://github.com/r3bo0tbx1/tor-guard-relay/issues) - 💬 [讨论区](https://github.com/r3bo0tbx1/tor-guard-relay/discussions) - 📦 [容器镜像仓库](https://github.com/r3bo0tbx1/tor-guard-relay/pkgs/container/onion-relay) ## 📊 项目状态 ## 📄 许可证 本项目基于 MIT 许可证授权。 完整详情请参阅[许可证](LICENSE.txt)。 ## 🙏 致谢 - **The Tor Project**，感谢其维护全球隐私网络 - **Alpine Linux**，感谢其提供最小化且安全的基础镜像 - **azukaar**，感谢其开发的 Cosmos Cloud - **所有中继运营商**，感谢你们在全球范围内支持隐私和反审查 ## 💖 支持本项目 运营公共 Tor 基础设施意味着需要支付持续的服务器、带宽、监控和维护成本。如果这个项目对您有帮助，您的捐助将有助于维持这些基础设施的运转，并支持开源开发的继续。 捐款完全是自愿的。它们不能购买支持、优先权、影响力或访问权限。它们仅用于帮助支付已经在公开进行的工作的成本。 ### Bitcoin (BTC) ``` bc1q25xa47uknfeekm8xze06kfv7tjz4crcqqfpcuu ``` ### Monero (XMR) ``` 49eiKhJd3uFdRerHk87wx3YCzb3yWQ8kSKTuMc7QjJphY4dG89HAFd8CcKswWn8oUhBJLu4kbjywSX46DwvtGNUV9qLCrVW ``` 了解更多信息，请访问[完整捐赠页面](https://brokenbotnet.com/donate/)。 ### 其他支持方式 - ⭐ 给仓库点 Star - 🐛 报告 Bug - 💡 建议新功能 - 📖 改进文档 - 🤝 提交补丁 - 🧅 运行一个中继

标签：Docker, Tor, 安全防御评估, 网络安全, 网络安全, 请求拦截, 运维, 隐私保护, 隐私保护