django-ip-safeguard 0.3.0

Django IP Risk Guard - IP risk query, geographical rules and automatic blocking plugin

django-ip-safeguard Enterprise

企业级 Django IP 风险防护中间件与运营控制台

📌 项目简介

django-ip-safeguard 是一个面向企业生产环境的 Django 请求前置安全插件。
它在请求进入业务视图前完成 IP 风险识别、地区策略校验、缓存决策复用和封禁治理，并提供企业 Dashboard 与策略中心。

文档：按功能拆分的完整说明见 docs/README.md；总览与发布验收见 docs/django-ip-guard-开发与发布指南.md。

🧭 企业能力总览

• 🛡️ 请求前置防护：中间件早期阻断风险流量，减少业务层压力。
• 🌍 风险与地区策略：支持风险分阈值、风险标签、国家白黑名单。
• 📡 中国内 / 国际 CIDR 池：远程文本列表同步至 Redis，可按「仅允许池内 / 池内拦截」策略匹配；支持 manage.py sync_geo_ip_pools 定时更新（详见 docs/django-ip-guard-开发与发布指南.md）。
• ⚙️ 策略中心：支持数据库策略覆盖 settings（策略即时生效）。
• 📊 Dashboard：提供统计面板、策略接口、健康检查、解封接口。
• 🔐 安全加固：管理接口权限控制、API Key 环境变量化、IP 脱敏审计。
• 🚀 高可用：熔断、重试、并发去重锁、分级缓存 TTL、降级策略。

🏗️ 企业架构说明

1. 请求进入 IpGuardMiddleware。
2. 读取运行时策略（数据库策略优先，其次 settings）。
3. IP 白名单 → 黑名单 → 中国内/国际 CIDR 池规则 → 单 IP 限流 → 封禁缓存 → 情报缓存 / Provider。
4. 风险引擎判定放行/阻断；按开关记录审计日志（可配置脱敏）。
5. Dashboard 对外提供管理与运营数据接口。

⚡ 快速接入（从 PyPI）

包名：PyPI · django-ip-safeguard
升级：pip install -U django-ip-safeguard

1) 安装

pip install django-ip-safeguard
# 可选：本地 GeoIP2
# pip install "django-ip-safeguard[geoip2]"

2) 注册 App 与中间件

将 IpGuardMiddleware 放在 SessionMiddleware 之后、CommonMiddleware / CsrfViewMiddleware / AuthenticationMiddleware 等之前，以便尽早按 IP 决策，且与 Session 兼容：

INSTALLED_APPS = [
    # ...
    "django_ip_safeguard",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django_ip_safeguard.middleware.IpGuardMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    # ...
]

3) 挂载控制台与 API（内置 Vue 构建产物）

from django.urls import include, path

urlpatterns = [
    path("ip-guard/", include("django_ip_safeguard.urls")),
]

访问 /ip-guard/ 打开管理控制台（Session + CSRF）。若部署在其它域名/端口，请在 settings 中配置 CSRF_TRUSTED_ORIGINS（如 https://ops.example.com）。

4) 执行迁移

python manage.py migrate

5) 最小可用配置

可使用扁平 IP_GUARD_*，或使用 IP_GUARD 嵌套字典（与扁平键合并：嵌套为基线，同名扁平键覆盖）。详见 docs/zh/02-installation.md / docs/en/02-installation.md。

import os

IP_GUARD_ENABLED = True
IP_GUARD_REDIS_URL = "redis://127.0.0.1:6379/0"
IP_GUARD_PROVIDER = "http"
IP_GUARD_PROVIDER_ENDPOINT = "https://risk-api.example.com/ip/query"
IP_GUARD_PROVIDER_API_KEY = os.getenv("IP_GUARD_PROVIDER_API_KEY", "")
IP_GUARD_RISK_SCORE_THRESHOLD = 70
IP_GUARD_TRUSTED_PROXY_CIDRS = ("10.0.0.0/8",)

🧩 配置分组说明

🔧 基础开关

• IP_GUARD_ENABLED
• IP_GUARD_REDIS_URL
• IP_GUARD_CACHE_TTL
• IP_GUARD_BAN_TTL
• IP_GUARD_BLOCK_STATUS_CODE
• IP_GUARD_USE_DB_LOG
• IP_GUARD_ENABLE_POLICY_CENTER
• IP_GUARD_POLICY_CACHE_SECONDS

🌐 Provider

• IP_GUARD_PROVIDER
• IP_GUARD_PROVIDER_ENDPOINT
• IP_GUARD_PROVIDER_API_KEY（建议仅环境变量）
• IP_GUARD_PROVIDER_TIMEOUT
• IP_GUARD_PROVIDER_MAX_RETRIES
• IP_GUARD_PROVIDER_RETRY_BACKOFF
• IP_GUARD_PROVIDER_CIRCUIT_BREAKER_FAILURES
• IP_GUARD_PROVIDER_CIRCUIT_BREAKER_TTL
• IP_GUARD_PROVIDER_HEADERS

🛡️ 风险规则

• IP_GUARD_RISK_SCORE_THRESHOLD
• IP_GUARD_BLOCKED_RISK_TAGS
• IP_GUARD_ALLOWED_COUNTRIES
• IP_GUARD_BLOCKED_COUNTRIES
• IP_GUARD_IP_WHITELIST（单 IP 或 CIDR；命中直接放行）
• IP_GUARD_IP_BLACKLIST（单 IP 或 CIDR；启用策略中心时以数据库策略为准）
• IP_GUARD_RATE_LIMIT_PER_MINUTE（单 IP 每分钟请求上限，0 关闭；需 Redis）

🧯 降级与高可用

• IP_GUARD_FAIL_OPEN
• IP_GUARD_FAIL_OPEN_PATH_PREFIXES
• IP_GUARD_FAIL_CLOSE_PATH_PREFIXES
• IP_GUARD_DEDUPE_LOCK_SECONDS
• IP_GUARD_HIGH_RISK_CACHE_TTL
• IP_GUARD_LOW_RISK_CACHE_TTL

🔐 审计与合规

• IP_GUARD_IP_MASK_ENABLED
• IP_GUARD_IP_MASK_KEEP_PREFIX

📊 Dashboard 与管理接口

• GET /ip-guard/：企业管理面板入口
• GET /ip-guard/api/dashboard/：24h 统计、拦截率、决策分布、按小时趋势、Top 风险 IP、国家/路径/拦截原因分布
• GET /ip-guard/api/recent-records/：近 days 天（1–30）访问/拦截按日汇总、最新拦截与访问记录、近期封禁（需开启审计写库才有数据）
• GET /ip-guard/api/policy/：读取当前策略
• POST /ip-guard/api/policy/：更新策略（支持 IP/CIDR 白黑名单与地区白黑名单；自动校验与去重）
• POST /ip-guard/api/ban/、POST /ip-guard/api/unban/、GET /ip-guard/api/ban-list/：封禁管理与分页列表
• GET /ip-guard/api/access-logs/：审计分页（路径、日期等筛选）
• GET /ip-guard/api/access-logs/export/：审计 CSV 导出（与列表相同筛选，上限 1 万条）
• GET /ip-guard/api/health/：Redis 连通与延迟、Provider、熔断失败计数、策略中心开关
• JWT 配置：IP_GUARD_JWT_SECRET_KEY、IP_GUARD_JWT_ALGORITHM、IP_GUARD_JWT_ACCESS_TTL、IP_GUARD_JWT_REFRESH_TTL

✅ 企业上线检查清单

• 已开启受信代理网段，避免伪造 X-Forwarded-For。
• API Key 通过环境变量注入，不落盘。
• 关键路径已设置 fail-close（登录/支付/管理端）。
• 已配置白名单（办公网、探针、健康检查）。
• 已开启审计日志与 IP 脱敏。
• 已验证熔断、降级、Redis 异常场景行为。
• 已跑通 pytest 与 ruff。

🧪 开发与验证命令

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
ruff check .

📚 文档导航

• 企业完整指南：docs/django-ip-guard-开发与发布指南.md
• 企业发布流程：docs/django-ip-guard-开发与发布指南.md 中 “PyPI 发布流程”

🖥️ Vue3 企业控制台（Element Plus）

PyPI 安装包已附带构建好的静态资源（django_ip_safeguard/contrib/.../static），挂载 urls 即可用。若需二次开发前端，可使用仓库内 frontend-admin/ 或包内 django_ip_safeguard/contrib/admin_frontend/，技术栈为 Vue3 + Vite + Element Plus + Pinia + Axios。

本地启动

cd frontend-admin
npm install
npm run dev

默认地址：http://127.0.0.1:5173

后端联调要求

• Django 服务运行在 http://127.0.0.1:8010
• 前端通过 Vite 代理访问 /ip-guard/api/*
• 鉴权采用 Django Session + CSRF：
  1. GET /ip-guard/api/auth/csrf/
  2. POST /ip-guard/api/auth/login/
  3. GET /ip-guard/api/auth/me/（返回 groups 与 permissions）
• 所有管理 API 视图均显式启用 csrf_protect，写操作必须携带有效 X-CSRFToken。
• 控制台基于 Django 用户与组权限显示菜单并限制访问：
  • django_ip_safeguard.view_ipaccesslog：仪表盘/审计日志/近期记录
  • django_ip_safeguard.view_ipguardpolicy：策略中心查看、健康状态
  • django_ip_safeguard.change_ipguardpolicy：策略中心修改
  • django_ip_safeguard.view_ipbanrecord：封禁列表查看
  • django_ip_safeguard.change_ipbanrecord：手动封禁/解封

已实现页面

• 登录页：/login
• 仪表盘：/dashboard（含 ECharts 国际来源世界地图 + 国家 Top 条形图）
• 策略中心：/policy
• 封禁管理：/ban
• 审计日志：/logs
• 健康状态：/health