AichaDigital/unblock

# Unblock 防火墙管理器 [](https://github.com/AichaDigital/unblock/actions/workflows/ci.yml) [](https://www.gnu.org/licenses/agpl-3.0) [](https://phpstan.org/) [](https://laravel.com/docs/11.x/pint) [](https://pestphp.com) [](https://pestphp.com) **Unblock** 是一个专为托管服务商设计的基于 Web 的防火墙管理系统。它为管理员和客户简化了防火墙日志分析和 IP 解封操作，特别注重非技术用户的易用性。 ## ✨ 功能特性 - **🔍 IP 分析**：跨多种服务（CSF, DirectAdmin BFM, Exim, Dovecot, ModSecurity）的综合防火墙日志分析 - **🚀 一键解封**：具备智能检测功能的自动化 IP 解封 - **👥 多用户管理**：支持托管客户、经销商和 VPS 所有者 - **📧 邮件通知**：向用户和管理员发送详细报告 - **🔐 授权用户**：在无需完整账户访问权限的情况下，代理访问特定域名/服务器 - **🔄 WHMCS 集成**：可选的与 WHMCS 自动同步功能 - **🌍 多面板支持**：兼容 cPanel 和 DirectAdmin - **📊 详细报告**：包含解释的综合防火墙日志 - **🔒 安全至上**：所有操作均被记录，包含 IP 验证和 SSH 密钥管理 - **🌐 国际化**：全面支持英语和西班牙语 - **⚡ 简易模式**：适用于紧密耦合的托管环境的匿名 IP 解封（无需认证） ## 📋 系统要求 - **PHP**: 8.3 或更高版本 - **Laravel**: 12.x - **数据库**: SQLite (推荐) - **Web 服务器**: Nginx 或 Apache - **Node.js**: 18+ (用于资源编译) - **SSH 访问**：用于管理运行 CSF/DirectAdmin 的服务器 - **DirectAdmin secure_php**: 如果您使用 DirectAdmin CustomBuild [`secure_php`](https://docs.directadmin.com/webservices/php/secure-php.html)，请确保运行 Unblock 的 PHP 版本的 `disable_functions` 列表中**不**包含 `proc_open` 函数。远程防火墙操作依赖 Spatie SSH / Symfony Process，这需要 `proc_open` 可用。 ``` cd /usr/local/directadmin/custombuild mkdir -p custom echo "exec,system,passthru,shell_exec,proc_close,dl,popen,show_source,posix_kill,posix_mkfifo,posix_getpwuid,posix_setpgid,posix_setsid,posix_setuid,posix_setgid,posix_seteuid,posix_setegid,posix_uname" > custom/php_disable_functions da build secure_php ``` ## 🚀 快速开始 ### 1. 克隆并安装 ``` git clone https://github.com/AichaDigital/unblock.git cd unblock composer install npm install && npm run build ``` ### 2. 环境设置 ``` cp .env.example .env php artisan key:generate ``` ### 3. 配置公司信息 编辑 `.env` 并配置您的公司详情： ``` COMPANY_NAME="Your Hosting Company" SUPPORT_EMAIL=support@yourcompany.com SUPPORT_URL=https://support.yourcompany.com # Legal URL（GDPR 合规所需） LEGAL_PRIVACY_URL=https://yourcompany.com/privacy LEGAL_TERMS_URL=https://yourcompany.com/terms LEGAL_DATA_PROTECTION_URL=https://yourcompany.com/data-protection ``` ### 4. 数据库设置 ``` # 对于 SQLite（推荐） touch database/database.sqlite php artisan migrate --seed # 对于 MySQL，先在 .env 中配置 DB_* 变量 ``` ### 5. 创建管理员用户 ``` # 交互模式（推荐） php artisan user:create --admin # 非交互模式 php artisan user:create --admin \ --email="admin@yourcompany.com" \ --first-name="Admin" \ --last-name="System" \ --password="YourSecurePassword123!" # 开发模式（允许简单密码） php artisan user:create --admin --no-secure ``` **注意：** `user:create` 命令处理了我们 User 模型特有的所有自定义字段和验证。请勿使用 `tinker` 或 `make:filament-user`，因为它们不能正确处理表结构。 ### 6. 启动开发服务器 ``` php artisan serve ``` 访问 `http://localhost:8000` 并使用您的管理员凭据登录。 ## 📖 文档 ### 📚 完整指南 Unblock 以 **两种截然不同的模式** 运行。请选择符合您使用场景的文档： #### 操作模式 - **[管理员模式指南](docs/admin-mode-guide.md)** - 具有用户管理功能的完整认证系统，非常适合托管服务商 - **[简易模式指南](docs/simple-mode-guide.md)** - 匿名 IP 解封，实现简化的公开访问 #### 功能与设置 - **[Logo 自定义](docs/logo-customization.md)** - 为所有访问表单上传公司品牌标识 - **[SSH 密钥设置](docs/ssh-keys-setup.md)** - 安全的服务器访问配置 - **[WHMCS 集成](docs/whmcs-integration.md)** - 自动同步用户和域名 - **[授权用户](docs/authorized-users.md)** - 在不共享账户的情况下代理访问权限 #### 技术文档 - **[管理员 OTP 流程](docs/internals/admin-otp-flow.md)** - 管理面板的双因素认证 - **[配置参考](docs/configuration.md)** - 完整的环境变量指南 ### 添加服务器 (主机) 1. 进入 Admin Panel → Hosts 2. 添加您的服务器详情： - **FQDN**: 服务器主机名 - **IP Address**: 服务器 IP - **SSH User**: 通常为 `root` - **Panel Type**: `cpanel` 或 `directadmin` 3. 上传 SSH 密钥（见下文 SSH 密钥设置） ### SSH 密钥设置 出于安全考虑，请创建一个仅能执行特定 CSF 命令的受限 SSH 密钥： ``` # 在您的 Unblock 服务器上 ssh-keygen -t ed25519 -f ~/.ssh/unblock_csf -C "unblock-firewall" # 复制公钥到被管理服务器 cat ~/.ssh/unblock_csf.pub ``` 在被管理的服务器上，将其添加到 `~/.ssh/authorized_keys` 并附带命令限制： ``` command="/path/to/restricted-csf-wrapper.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAA... unblock-firewall ``` 详见 [docs/ssh-keys-setup.md](docs/ssh-keys-setup.md) 获取详细说明和封装脚本。 ### HQ 主机监控 (总部) **为您的主要托管平台自动进行 IP 白名单设置。** 如果您有一个中心服务器 (HQ)，客户通过它访问 cPanel、WHMCS、计费门户或支持工单，您可以启用自动监控。当用户请求 IP 解封时，系统会并行检查您的 HQ 主机是否存在 ModSecurity 封锁。 **问题所在：** 许多托管客户在试图提交关于被封禁的支持工单时，会被 ModSecurity 再次封禁。这造成了一个令人沮丧的循环：“我被封了” → 尝试开工单 → 再次被封 → 无法报告问题。 **解决方案：** 当任何用户请求 IP 解封（针对任何服务器）时，系统会自动： 1. 检查您 HQ 主机的 ModSecurity 日志 2. 如果 IP 在那里被封禁，则将其临时加入白名单 3. 给您发送包含详情的邮件通知 4. 客户现在可以访问支持系统并创建正规工单 **配置：** ``` # 在 'hosts' 表中找到您的 HQ host ID HQ_HOST_ID=1 # 或使用 FQDN 作为回退 HQ_HOST_FQDN=hq.yourcompany.com # 白名单持续时间（默认：7200 = 2 小时） HQ_WHITELIST_TTL=7200 ``` **邮件通知：** 您将收到如下邮件： ``` Subject: ModSecurity Detection HQ - IP temporarily whitelisted Hi Admin, ModSecurity activity detected from IP 79.116.177.99 on the central platform (HQ). We have temporarily added the IP to the whitelist for 2 hours to reduce friction while we review. We will review the rule to add it as strictly as possible if necessary. Regards, Your Company - Support Team ``` **重要提示：** - 仅检查 HQ 上的 **ModSecurity** 日志（而非 CSF/BFM） - 并行运行（不会减慢常规解封操作） - 如果 IP 未在 HQ 上被封禁，则静默处理 - 需要为您的 HQ 主机配置 SSH 访问 ### WHMCS 集成 (可选) 从 WHMCS 同步用户和主机信息： ``` WHMCS_SYNC_ENABLED=true WHMCS_API_URL=https://your-whmcs.com/includes/api.php WHMCS_API_IDENTIFIER=your_api_identifier WHMCS_API_SECRET=your_api_secret ``` 完整设置请参阅 [docs/whmcs-integration.md](docs/whmcs-integration.md)。 ### 授权用户 允许客户在不共享账户的情况下授予特定域名的访问权限： 1. 客户在其仪表板中创建授权用户 2. 分配特定域名或服务器 3. 授权用户获得 OTP 登录访问权限 4. 只能查看/管理被分配的资源 ### 简易解封模式 (无需认证) 对于拥有紧密客户关系的托管服务商，启用匿名 IP 解封功能： ``` # 启用简单模式 UNBLOCK_SIMPLE_MODE=true # 配置 throttling（每分钟请求数） UNBLOCK_SIMPLE_THROTTLE_PER_MINUTE=3 # 超过 rate limit 后的封禁时长（分钟） UNBLOCK_SIMPLE_BLOCK_DURATION=15 ``` **功能特性：** - 无需认证 - 用户提供：IP 地址、域名、邮箱 - 系统验证 IP 已被封禁 + 域名存在于服务器日志中 - 仅当两个条件都匹配时才解封（防止滥用） - 严格的速率限制（默认为 3 次请求/分钟） - 针对不匹配的情况为管理员静默记录日志 - 访问地址：`/simple-unblock` **重要提示：** - 运行 `php artisan db:seed --class=AnonymousUserSeeder` 以创建系统匿名用户 - 该用户 (`anonymous@system.internal`) 用于所有匿名报告 - 管理员接收所有尝试（成功和失败）的详细日志 - 用户仅在 IP 实际解封后收到确认邮件 **文档：** - **用户指南**：[Simple Mode User Guide](docs/SIMPLE_MODE_USER_GUIDE.md) - 最终用户文档 - **测试指南**：[Simple Mode Testing Guide](docs/SIMPLE_MODE_TESTING_GUIDE.md) - 使用真实数据进行测试 - **技术文档**：详见 `docs/internals/` 了解实现细节 ## 🔧 配置 ### 队列工作者 对于生产环境，使用 Supervisor 配置队列工作者： ``` sudo cp supervisor-laravel-worker.conf /etc/supervisor/conf.d/unblock-worker.conf # 编辑文件中的路径 sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start unblock-worker:* ``` ### 计划任务 添加到 crontab： ``` * * * * * cd /path/to/unblock && php artisan schedule:run >> /dev/null 2>&1 ``` ## 🧪 测试 运行完整的测试套件： ``` composer test # 带覆盖率 composer test:coverage # 并行执行 php artisan test --parallel ``` ## 🔒 安全 - **SSH 密钥**：使用专用的、受限的 SSH 密钥进行防火墙操作 - **输入验证**：所有 IP 和命令都经过验证和清理 - **操作日志**：所有防火墙操作均记录用户上下文 - **WHMCS**：为 WHMCS 集成创建只读 MySQL 用户 - **会话超时**：4 小时不活动超时 - **OTP 认证**：基于时间的 OTP 用于客户访问 - **Admin 2FA**：基于邮件的 OTP 双因素认证，用于管理面板（可配置） 安全最佳实践请参阅 [SECURITY.md](SECURITY.md)，Admin 2FA 配置请参阅 [docs/internals/admin-otp-flow.md](docs/internals/admin-otp-flow.md)。 ## 🌍 国际化 Unblock 开箱即支持多种语言： - **English** (en) - **Spanish** (es) 要添加更多语言，请将 `lang/en` 复制到您的语言代码目录并翻译字符串。 ## 📝 许可证 本项目基于 **GNU Affero General Public License v3.0 (AGPL-3.0)** 授权。 ### 这意味着： ✅ **您可以：** - 自由使用、学习、修改和分发本软件 - 用于商业目的 - 分叉并创建衍生作品 ❌ **您不得：** - 基于此代码创建闭源产品 - 将其作为 SaaS/服务运行而不共享您的源代码 - 移除归属或许可证声明 📋 **您必须：** - 在所有副本中保留 AGPL-3.0 许可证 - 共享任何修改的源代码 - 提供对本项目的明确归属 - 如果将其作为网络服务运行，需向用户提供您的源代码 **完整许可证：** [LICENSE](LICENSE) | [English](https://www.gnu.org/licenses/agpl-3.0.html) | [Español](https://www.gnu.org/licenses/agpl-3.0.es.html) 这种强 Copyleft 许可证确保软件保持自由和开源，即使在作为 Web 服务使用时也是如此。 ## 💬 支持 - **文档**: [完整文档](docs/) - **问题**: [GitHub Issues](https://github.com/AichaDigital/unblock/issues) - **讨论**: [GitHub Discussions](https://github.com/AichaDigital/unblock/discussions) ## 🙏 致谢 - 基于 [Laravel 12](https://laravel.com) 构建 - 管理面板由 [FilamentPHP 4](https://filamentphp.com) 提供 - 图标来自 [Heroicons](https://heroicons.com) - 使用 [Pest PHP](https://pestphp.com) 进行测试 ## 📊 项目统计 - **测试**: 257 个通过 - **覆盖率**: 85%+ - **PHPStan 级别**: Max - **Laravel 版本**: 12.x - **PHP 版本**: 8.3+ 为托管社区用 ❤️ 打造

标签：cPanel, CSF, DirectAdmin, ffuf, IPv6支持, IP解封, Laravel, MITM代理, ModSecurity, OpenVAS, PHP, VPS管理, WHMCS, 主机控制面板, 入侵防御, 内存分配, 多用户系统, 托管服务, 暴力破解防护, 服务器管理, 系统管理员, 网络安全, 自动化解封, 运维工具, 防火墙管理, 隐私保护