用户小黑屋

一款面向 Halo 2 的用户处罚与账号访问限制插件，为站点提供临时封禁、永久封禁、处罚记录、自动到期和登录限制等管理能力。

• 作者：itxiaohui
• 官方网站：www.itxiaohui.top
• 问题反馈：https://www.itxiaohui.top/subject/subject-l2d1oe4l

插件介绍

用户小黑屋用于处理站点用户违规、恶意操作或其他需要限制账号访问的场景。管理员可以直接在 Halo 后台查看处罚记录、封禁用户、修改处罚、解除封禁，并保留完整的处罚历史。

插件遵循 Halo 原生后台的布局与交互方式，使用简洁的表格、标签、筛选和弹窗，不修改 Halo 核心代码，也不会干扰匿名访客正常浏览网站。

主要功能

• 查看全部用户处罚记录
• 按用户名或用户 ID 搜索
• 按处罚状态、处罚类型筛选
• 支持临时封禁和永久封禁
• 临时封禁支持 1 小时、1 天、7 天和 30 天
• 修改处罚类型、处罚原因、结束时间和管理员备注
• 手动解除封禁
• 临时处罚到期后自动解除
• 保留封禁、修改、解除和到期等操作历史
• 展示当前封禁用户数和今日处罚数
• 对已经登录的被封禁用户清除登录状态
• 为 API 请求返回标准 403 响应
• 为浏览器请求显示独立的账号限制页面

正确的账号限制方式

插件不会在普通访客打开网站首页时直接展示封禁页面。

只有用户完成身份认证，或者已经登录的用户继续访问认证内容时，插件才会检查该账号是否存在有效处罚。命中有效处罚后，插件会清除登录状态并显示账号限制页面。

匿名用户以及未被封禁的用户仍可正常访问站点公开内容。

账号限制页面

限制页面会向用户展示：

• 用户名和用户 ID
• 封禁原因
• 开始时间
• 结束时间
• 剩余时间
• 与管理员联系按钮

管理员可在“工具 → 用户小黑屋 → 联系方式设置”中配置按钮文字和联系方式。

联系方式支持：

• 邮箱地址，例如 admin@example.com
• 手机号，例如 13800138000
• 网页地址，例如 https://example.com/appeal
• 站内路径，例如 /contact
• 已带协议的 mailto:、tel:、http: 或 https: 地址

普通邮箱、手机号和不带协议的网站地址会被自动转换成可点击链接。

后台入口

插件启用后，Halo 后台侧边栏会出现：

工具
└── 用户小黑屋

管理页面提供处罚统计、搜索筛选、处罚列表、封禁弹窗、处罚详情和联系方式设置。

安装要求

安装方法

1. 下载插件 JAR 文件。
2. 登录 Halo 管理后台。
3. 进入“插件”，点击右上角“安装”。
4. 选择“本地”，上传插件 JAR。
5. 安装完成后启用插件。
6. 进入“工具 → 用户小黑屋”开始使用。

升级插件时，直接在插件安装页面上传新版本 JAR，并根据提示确认升级即可。

首次使用建议

安装完成后，建议先进行以下配置和检查：

1. 打开“联系方式设置”。
2. 设置“与管理员联系”按钮的显示文字。
3. 填写管理员邮箱、手机号、申诉页面或其他联系链接。
4. 创建一个普通测试用户。
5. 分别测试临时封禁、永久封禁和解除封禁。

请勿使用生产站点的超级管理员账号进行封禁测试。插件也会主动阻止管理员封禁当前登录账号，避免误锁死后台。

权限说明

超级管理员默认拥有插件全部权限。其他后台角色可按需授权：

数据与安全

• 处罚记录使用 Halo 原生 Extension 机制持久化。
• 插件不会创建或修改 Halo 核心数据库表。
• 用户输入在输出到限制页面前会进行 HTML 转义。
• 联系链接仅允许安全的常用协议和站内绝对路径。
• 限制响应设置为不缓存，避免浏览器缓存处罚页面。
• 同一用户不会同时存在多条有效处罚。
• 解除封禁后记录仍会保留，方便后续审计。

使用边界

• 已登录用户被管理员封禁后，会在下一次认证请求时被清除登录状态；插件不会向停留不动的页面主动推送跳转。
• 到期任务每分钟更新一次处罚状态，但请求拦截会即时判断结束时间，因此已到期处罚不会继续阻止用户。
• 当前临时封禁使用预设时长，不提供任意日期时间选择器。
• 本插件只负责 Halo 账号处罚与认证访问限制，不是防火墙、WAF 或 IP 封禁工具。

技术实现

• Java 21
• Spring Boot / Project Reactor
• Halo Plugin API
• Halo Extension / CustomEndpoint / RBAC
• Vue 3 / TypeScript
• Halo UI / Vite

开发者微信（添加备注halo）：hui12052

QQ群：127988535

二维码