exoplatform/fail2ban-unban

fail2ban-unban

fail2ban-unban是一个自助式Web界面工具，用于从fail2ban jail中解封IP地址。该工具允许用户无需服务器管理员介入即可自行解封IP，有效简化运维流程。

🚀 核心功能

• 自助IP解封：用户可独立完成IP解封操作，无需管理员协助
• 多jail支持：同时从所有配置的fail2ban jail中移除目标IP
• 现代化UI：简洁响应式界面，内置IP检测辅助功能
• 容器化部署：通过Docker快速搭建，降低环境依赖
• 轻量级设计：基于Alpine Linux，资源占用极低
• 反向代理兼容：支持在nginx等反向代理后使用自定义子路径
• 灵活认证：默认无内置认证（适合内部场景，可通过反向代理添加认证）

📋 前提条件

• 已安装Docker及Docker Compose
• 主机系统运行正常的fail2ban服务
• 可访问主机的/var/run/fail2ban/fail2ban.sock文件

🏗️ 快速部署

1. 创建项目目录

bash
mkdir fail2ban-unban && cd fail2ban-unban && mkdir templates

2. 编写Dockerfile

dockerfile
FROM alpine:3.19

WORKDIR /app

# 安装系统依赖
RUN apk add --no-cache python3 py3-pip py3-virtualenv fail2ban \
    && ln -sf python3 /usr/bin/python \
    && ln -sf pip3 /usr/bin/pip

# 创建虚拟环境
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 安装Python依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用文件
COPY app.py .
COPY templates/ ./templates/

# 创建非root用户
RUN adduser -D -u 1000 unbanuser && chown -R unbanuser:unbanuser /app

# 暴露端口
EXPOSE 5000

# 以root用户运行（需访问fail2ban socket）
USER root

CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "2", "--threads", "4", "app:app"]

3. 编写requirements.txt

txt
flask==3.0.0
gunicorn==21.2.0
python-dotenv==1.0.0

4. 编写docker-compose.yml

yaml
version: '3.8'

services:
  unban-me:
    build: .
    container_name: fail2ban-unban
    restart: unless-stopped
    user: root
    environment:
      - ALLOWED_JAILS=${ALLOWED_JAILS:-sshd}
    volumes:
      - /var/run/fail2ban:/var/run/fail2ban:ro
    ports:
      - "5000:5000"
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  internal:
    driver: bridge

5. 编写.env文件

bash
# 逗号分隔的允许解封的jail列表
ALLOWED_JAILS=sshd,nginx-http-auth,postfix

6. 启动服务

bash
docker-compose up -d

7. 访问界面

打开浏览器访问：http://localhost:5000

🔧 配置说明

环境变量

查看可用Jail

在主机执行以下命令查看当前运行的fail2ban jail：

bash
sudo fail2ban-client status

🌐 Nginx反向代理配置

将工具隐藏在非公开路径（例如/banana）：

nginx
location /banana/ {
    proxy_pass http://fail2ban-unban:5000/;
    proxy_http_version 1.1;
    
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /banana;
    
    proxy_connect_timeout 10s;
    proxy_send_timeout 30s;
    proxy_read_timeout Thirtys;
    proxy_buffering off;
    
    proxy_redirect http://fail2ban-unban:5000/ /banana/;
    proxy_redirect https://fail2ban-unban:5000/ /banana/;
}

location = /banana {
    return 301 /banana/;
}

🛡️ 安全建议

1. 添加认证：生产环境建议通过nginx添加基本认证（如htpasswd）
2. 速率限制：配置nginx速率限制防止滥用
3. IP白名单：限制仅内部IP访问该工具
4. 隐藏路径：使用非直观路径（如/banana）避免暴露
5. 日志审计：定期检查容器和fail2ban日志

📊 测试验证

健康检查

bash
curl http://localhost:5000/health

测试解封接口

bash
curl -X POST http://localhost:5000/unban \
  -H "Content-Type: application/json" \
  -d '{"ip":"192.168.1.100"}'

🐛 故障排除

Socket权限问题

若出现权限错误，检查主机socket权限：

bash
ls -la /var/run/fail2ban/fail2ban.sock

查看容器日志

bash
docker-compose logs -f

🗑️ 卸载清理

bash
docker-compose down && docker rmi fail2ban-unban && rm -rf fail2ban-unban

📝 许可证

本项目采用MIT许可证，详情见LICENSE文件。

👥 贡献指南

欢迎提交PR或issue参与项目改进。

🙏 致谢

由eXo ITOP Team开发维护 | 官网链接