thib3113/unifi-blockips-srv

unifi-blockips-srv

https://img.shields.io/docker/pulls/thib3113/unifi-blockips-srv.svg](https://hub.docker.com/r/thib3113/unifi-blockips-srv)

镜像概述

unifi-blockips-srv是一个用于管理UniFi控制器IP黑名单的服务镜像，通过HTTP API接口实现IP地址的动态添加与删除。该服务与UniFi控制器交互，将指定IP加入或移出预配置的防火墙规则与IP组，适用于动态阻止***IP访问UniFi网络环境，支持IPv4/IPv6，并兼容多种硬件架构。

核心功能与特性

• IP黑名单管理：通过HTTP POST/DELETE请求添加或删除需阻止的IP地址
• UniFi集成：与UniFi控制器交互，管理防火墙规则与IP组
• 安全校验：支持基于SHA256令牌的API访问控制（添加/删除IP需验证令牌）
• 多架构支持：自动构建linux/amd64、linux/arm64、linux/arm/v7镜像，兼容x86服务器及ARM设备（如树莓派）
• 灵活配置：通过环境变量或.env文件配置，支持自定义服务端口

环境变量配置

标签说明

镜像标签遵循以下规则：

• latest：最新稳定版本
• sha-<sha>：特定提交的精确构建（<sha>为提交的短SHA值）
• 1：主版本号为1的最新版本（如1.*.*）
• 1.1：主版本1、次版本1的最新版本（如1.1.*）
• 1.1.1：主版本1、次版本1、补丁版本1的最新版本（如1.1.1*）

使用方法

API接口说明

添加IP到阻止列表

通过POST请求添加IP，需验证ADD_CHECKSUM令牌：

bash
POST /?token=<令牌>&ips[]=192.168.1.100&ips[]=10.0.0.5

从阻止列表删除IP

通过DELETE请求删除IP，需验证RM_CHECKSUM令牌：

bash
DELETE /?token=<令牌>&ips[]=192.168.1.100&ips[]=10.0.0.5

令牌校验说明

令牌需通过SHA256计算校验值，可使用在线工具生成：https://emn178.github.io/online-tools/sha256.html

环境变量安全配置

为增强容器安全性，可通过/app/.env文件（遵循.env格式）传递环境变量，而非命令行参数。

UniFi控制器准备工作

使用前需在UniFi控制器中完成以下配置（参考https://github.com/tusc/blockips-unifi#preparation%EF%BC%89%EF%BC%9A

1. 创建防火墙规则（对应UNIFI_FW_RULE_NAME和UNIFI_FW_RULE_NAME_V6）
2. 创建IP组（对应UNIFI_GROUP_NAME和UNIFI_GROUP_NAME_V6）

示例配置：

• UNIFI_FW_RULE_NAME设为Scheduled Block Group
• UNIFI_GROUP_NAME设为Block_Group

部署示例

Docker运行

bash
docker run -d \
  -e UNIFI_CONTROLLER_IP=192.168.1.1 \
  -e UNIFI_CONTROLLER_PORT=8443 \
  -e UNIFI_USERNAME=admin \
  -e UNIFI_PASSWORD=password \
  -e UNIFI_FW_RULE_NAME="Scheduled Block Group" \
  -e UNIFI_GROUP_NAME="Block_Group" \
  -e ADD_CHECKSUM=2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae \
  -p 3000:3000 \
  docker.xuanyuan.run/thib3113/unifi-blockips-srv:latest

Docker Compose配置

yaml
version: '3.7'
services:
  unifi-blocker:
    image: docker.xuanyuan.run/thib3113/unifi-blockips-srv:latest
    environment:
      port: 3000
      UNIFI_CONTROLLER_IP: 192.168.1.1
      UNIFI_CONTROLLER_PORT: 8443
      UNIFI_USERNAME: admin
      UNIFI_PASSWORD: password
      UNIFI_SITE_NAME: default
      UNIFI_FW_RULE_NAME: "Scheduled Block Group"
      UNIFI_FW_RULE_NAME_V6: "Scheduled Block Group V6"
      UNIFI_GROUP_NAME: "Block_Group"
      UNIFI_GROUP_NAME_V6: "Block_Group_V6"
      ADD_CHECKSUM: 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
      RM_CHECKSUM: fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
    ports:
      - "3000:3000"
    restart: unless-stopped

与安全工具集成

Crowdsec集成

通过Crowdsec的自定义bouncer调用服务API，实现动态IP阻止。创建如下bash脚本（保存为crowdsec-bouncer.sh）：

bash
#!/bin/bash

IP=$2
DURATION=$3
REASON=$4
JSON_OBJECT=$5

# 服务访问URL
URL=http://unifi-blocker-ip:3000

# 日志文件路径
LOG=/var/log/bouncer.log

case $1 in
  add)
    # 添加IP到阻止列表
    /usr/bin/curl -k --location --request POST "${URL}?token=<添加令牌>&ips=${IP}" >> ${LOG} 2>&1
  ;;
  del)
    # 从阻止列表删除IP
    /usr/bin/curl -k --silent --location --request DELETE "${URL}?token=<删除令牌>&ips=${IP}" >> ${LOG} 2>&1
  ;;
  *) 
    echo "未知操作: $1" >> ${LOG}
    exit 1
  ;;
esac

Fail2ban集成

配置Fail2ban通过服务API阻止***IP：

1. 创建action配置文件/etc/fail2ban/action.d/unifi-ban.conf：

ini
[Definition]
actionstart =
actionstop =
actioncheck =
actionban = /usr/bin/curl -k --location --request POST 'http://unifi-blocker-ip:3000?token=<添加令牌>&ips=<ip>'
actionunban = /usr/bin/curl -k --silent --location --request DELETE 'http://unifi-blocker-ip:3000?token=<删除令牌>&ips=<ip>'

2. 在jail配置中引用该action（/etc/fail2ban/jail.d/your-jail.local）：

ini
[your-jail]
banaction = unifi-ban
enabled = true
# 其他jail配置...