站点访问控制

站点访问控制是为 Halo 2 提供路径级访问保护的插件。你可以为登录入口、私密文章、独立页面或任意网站路径配置 Passkey、独立访问密码、IP 白名单和 IP 黑名单。

插件运行在 Halo 原有认证之前，只增加一道前置门禁，不替换 Halo 的登录和权限体系。

交流与反馈

QQ 交流群

使用中遇到问题，请前往 GitHub Issues 提交，并附上 Halo 版本、插件版本、复现步骤和相关日志。

请勿在 Issue 中公开访问密码、恢复码、Cookie、Passkey challenge 或其他敏感信息。

功能特性

• 路径级规则：支持精确路径、子路径通配和指定 HTTP 方法，不需要修改主题。
• Passkey 保护：使用系统 Passkey、手机或安全密钥验证，支持一次性恢复码。
• 独立访问密码：每条密码规则拥有自己的密码和门禁授权，互不通用。
• IP 访问控制：支持 IPv4、IPv6 和 CIDR，可配置白名单或黑名单。
• Halo 登录保护预设：一键创建适用于 Halo 2.26 登录与认证入口的 Passkey 规则。
• 门禁会话管理：查看有效会话，撤销单个会话、当前浏览器会话或全部会话。
• 可信代理解析：适配 Nginx 等反向代理，避免直接信任访客伪造的转发请求头。
• 安全失败策略：规则或配置无法可靠读取时，对受保护路径失败关闭。

界面预览

兼容性

使用方式

1. 前往 Releases 下载 Assets 中的 JAR 文件。
2. 登录 Halo 控制台，在“插件”中上传 JAR。
3. 启用“站点访问控制”插件。
4. 进入“系统 → 站点访问控制”，按照“开始使用”页面完成配置。

Halo 插件的安装和更新方式可参考 Halo 插件使用文档。

插件安装后默认不会保护任何路径。只有创建、配置并启用规则后，对应路径才会受到保护。

配置概览

插件在 Halo 控制台中提供以下页面：

• 开始使用：查看当前配置状态，并按步骤完成 Passkey、密码或 IP 规则配置。
• 保护规则：创建、编辑、启用和停用路径规则。
• Passkey：注册或撤销站点 Passkey。
• 门禁会话：查看和撤销已经签发的访问授权。
• 安全恢复：生成、确认和查看剩余的一次性恢复码。
• IP 与代理：配置 RP ID、精确 Origin 和可信代理 CIDR。

插件没有“全局保护开关”。每条规则由自己的启用状态和验证方式决定是否生效。

验证方式

每条规则只能选择一种验证方式。同一个请求命中多条规则时，只执行优先级最高的一条。

快速开始

使用独立密码保护路径

以保护 /private 及其子路径为例：

1. 打开“保护规则”，新建规则。

2. 路径每行填写一个：

   /private
   /private/**
   

3. 验证方式选择“访问密码”。

4. 设置当前规则的独立密码。

5. 启用并保存规则。

访问对应路径时，插件会显示密码门禁页。该密码和验证后的会话只属于当前规则，不能用于通过其他密码规则。

使用 Passkey 保护 Halo 登录入口

1. 在“IP 与代理”中填写站点 RP ID 和精确 Origin。
2. 确认生产站点已经使用 HTTPS。
3. 在“Passkey”中注册至少一个凭证。
4. 在“安全恢复”中生成恢复码，离线保存后确认。
5. 返回“开始使用”，创建“Halo 登录保护预设”。

预设会保护 Halo 2.26 的登录页面、登录提交、社交登录、OAuth2 回调、二次认证和资料补全入口。

首次配置时不要直接启用宽泛的 /** 规则。请先使用具体路径验证 Passkey、恢复码和插件停用流程。

路径规则

规则支持精确路径和 Spring 风格的子路径通配：

查询参数不参与路径匹配。规则不接受路径变量、正则表达式、反斜杠或百分号编码表达式。

可以按需限制 HTTP 方法；方法留空时匹配所有请求方法。

Passkey 配置说明

Passkey 使用 WebAuthn 标准。启用 Passkey 规则前必须完成以下项目：

1. RP ID：填写稳定的站点域名，不包含协议、端口或路径，例如 example.com。
2. Origin：每行填写一个允许的完整来源，例如 https://example.com。
3. HTTPS：生产环境必须使用安全上下文；仅 localhost 开发环境可使用 HTTP。
4. Passkey：使用当前已登录的 Halo 超级管理员注册至少一个凭证。
5. 恢复码：生成并离线保存一次性恢复码，然后在控制台确认已保存。

RP ID、Origin 和已注册的 Passkey 属于站点级 WebAuthn 配置；是否对某个路径使用 Passkey，则由每条保护规则单独决定。不同 Passkey 规则签发的门禁授权互不通用。

浏览器或系统进行指纹、Face ID、PIN 等本地解锁时，插件不会收到生物识别数据。

IP 与可信代理

未配置可信代理时，插件只使用与 Halo 建立连接的客户端地址。Halo 位于 Nginx 等反向代理之后时，只填写实际连接 Halo 的代理 IP 或最小 CIDR。

例如 Nginx 与 Halo 位于同一主机：

location / {
    proxy_pass http://127.0.0.1:8090;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Forwarded "";
}

插件侧可以信任 127.0.0.1/32；如果实际通过 IPv6 回环连接，再增加 ::1/128。

不要将 0.0.0.0/0 或 ::/0 设置为可信代理，否则访客可能伪造客户端 IP。

会话与安全恢复

• Passkey 和密码验证成功后，会签发当前规则的门禁会话。
• 会话有效期可设置为 5 分钟至 12 小时。
• 停用规则或更换验证方式后，该规则原有授权会被撤销。
• 恢复码只能使用一次；重新生成恢复码后，旧恢复码全部失效。
• 恢复码只为当前命中的 Passkey 规则签发 10 分钟临时会话。

如果配置错误导致无法进入站点：

1. 优先在 Halo 控制台的插件管理页面停用“站点访问控制”。
2. 如果控制台也无法访问，停止 Halo。
3. 在 Halo 的 work-dir/plugins 中找到文件名包含 plugin-site-access-control 的 JAR。
4. 将该 JAR 移出插件目录并重新启动 Halo。
5. 恢复访问后修正规则，再重新安装或启用插件。

不要直接删除数据库或插件安全数据。

安全说明

• Passkey 验证由 Yubico WebAuthn Server 完成，插件不自行实现 WebAuthn 密码学。
• 每条访问密码使用 BCrypt 单独哈希，明文不会写入规则资源或 URL。
• 门禁 Cookie 使用 HttpOnly、Secure、SameSite=Strict 和 __Host- 前缀。
• Halo 中只保存门禁令牌的 SHA-256 哈希，不保存浏览器持有的原始令牌。
• Passkey、密码和恢复码验证均有每 IP 与全局限流。
• 规则、Passkey、会话、恢复码和网络配置仅允许 Halo 超级管理员管理。
• 插件无法通过 HTTP 请求获取访客真实 MAC 地址，也不提供 MAC 地址控制。

开发环境

克隆项目：

git clone git@github.com:acanyo/plugin-site-access-control.git
cd plugin-site-access-control

启动 Halo Docker 开发环境并自动加载插件：

./gradlew haloServer

默认访问地址为 http://localhost:8090，默认管理员账号和密码均为 admin。

构建发布 JAR：

./gradlew build

构建产物位于 build/libs/。

Halo 插件的详细开发文档可查阅 Halo 插件开发。

注意事项

• 每条规则只支持一种验证方式，不支持 AND/OR 策略组合。
• 一个浏览器 Cookie 保存当前门禁授权；通过另一条规则后会替换原授权，需要访问原规则时需重新验证。
• 修改 Passkey 的 RP ID 或 Origin 前，需要先停用所有 Passkey 规则。
• 站点域名迁移后，原 Passkey 可能无法继续使用，请提前准备恢复和重新注册方案。
• 插件卸载时不会主动删除规则、凭据和恢复数据，避免误操作造成安全数据丢失。

开源协议

本项目基于 GPL-3.0 协议开源。