feat: 新增受保护链接并将控制台合并为资源访问管理
- 新增 ProtectedLink/LinkVisitRecord，/link/{slug} 门禁页 + 一次性令牌跳转
- 复用邮箱验证体系，验证码邮件区分下载/链接模板
- 控制台下载资源与受保护链接合并为「资源访问管理」单页（页签切换）
- 引用扫描支持 /link/ 链接，角色模板/设置/文档同步更新
- 版本 1.3.0
This commit is contained in:
shirainbown
+70
-25
@@ -1,6 +1,6 @@
|
||||
# 资源下载管理（sharelink）插件 · 配置指南与使用说明
|
||||
# 资源访问管理（sharelink）插件 · 配置指南与使用说明
|
||||
|
||||
> 适用版本：sharelink 1.0.x / Halo ≥ 2.22（已在 Halo Pro 2.25.4 实测）
|
||||
> 适用版本：sharelink 1.2.x / Halo ≥ 2.22（已在 Halo Pro 2.25.4 实测；受保护链接自 1.2.0 起提供）
|
||||
>
|
||||
> 本文配合截图说明插件的功能、配置方法、使用流程和注意事项。
|
||||
>
|
||||
@@ -14,13 +14,14 @@
|
||||
2. [安装与启用](#二安装与启用)
|
||||
3. [全局配置](#三全局配置)
|
||||
4. [日常使用：创建下载资源](#四日常使用创建下载资源)
|
||||
5. [访客看到的下载页](#五访客看到的下载页)
|
||||
6. [下载统计与记录](#六下载统计与记录)
|
||||
7. [文章引用扫描](#七文章引用扫描)
|
||||
8. [邮箱验证详解](#八邮箱验证详解)
|
||||
9. [防直链原理与边界](#九防直链原理与边界)
|
||||
10. [注意事项汇总](#十注意事项汇总)
|
||||
11. [常见问题 FAQ](#十一常见问题-faq)
|
||||
5. [受保护链接（超链接访问门禁）](#五受保护链接超链接访问门禁)
|
||||
6. [访客看到的下载页](#六访客看到的下载页)
|
||||
7. [下载统计与记录](#七下载统计与记录)
|
||||
8. [文章引用扫描](#八文章引用扫描)
|
||||
9. [邮箱验证详解](#九邮箱验证详解)
|
||||
10. [防直链原理与边界](#十防直链原理与边界)
|
||||
11. [注意事项汇总](#十一注意事项汇总)
|
||||
12. [常见问题 FAQ](#十二常见问题-faq)
|
||||
|
||||
---
|
||||
|
||||
@@ -35,6 +36,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
| **邮箱验证** | 按资源开关。访客需输入邮箱收取验证码，验证通过才能下载；验证过的邮箱长期免验证 |
|
||||
| **防直链** | 注册为资源的附件，`/upload/**` 直链对外直接 404，文件真实地址不暴露 |
|
||||
| **文章引用扫描** | 一键扫描全站文章，告诉你每个下载资源被哪些文章引用 |
|
||||
| **受保护链接** | 给任意 http/https 超链接加访问门禁：邮箱验证放行、访问统计、真实地址隐藏 |
|
||||
|
||||
### 工作流程（一图流）
|
||||
|
||||
@@ -60,8 +62,8 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
1. 进入 **Console → 系统 → 插件**，点击右上角 **「安装」**。
|
||||
2. 选择 **「本地上传」** 上传 `sharelink-x.y.z.jar`（或「远程下载」粘贴 jar 地址）。
|
||||
3. 安装后在插件列表找到 **「资源下载管理」**，点击启用。
|
||||
4. 启用成功后，左侧菜单 **「内容」** 分组下会出现 **「下载管理」** 入口。
|
||||
3. 安装后在插件列表找到 **「资源访问管理」**，点击启用。
|
||||
4. 启用成功后，左侧菜单 **「内容」** 分组下会出现 **「资源访问管理」** 入口，一个页面内通过页签切换「下载资源」与「受保护链接」。
|
||||
|
||||
> ⚠️ **升级插件时的两个坑**（Halo 通用行为，非本插件问题）：
|
||||
> - 用同名单 jar 覆盖安装时，会弹出「插件已存在，是否升级？」确认框，**必须点「确定」** 才会真正替换。
|
||||
@@ -71,7 +73,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
## 三、全局配置
|
||||
|
||||
进入 **系统 → 插件 → 资源下载管理 → 设置**，有两个标签页。
|
||||
进入 **系统 → 插件 → 资源访问管理 → 设置**，有两个标签页。
|
||||
|
||||
### 3.1 基本设置
|
||||
|
||||
@@ -101,7 +103,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
## 四、日常使用：创建下载资源
|
||||
|
||||
进入 **内容 → 下载管理**，这里是所有下载资源的统一管理中心。
|
||||
进入 **内容 → 资源访问管理 → 下载资源** 页签，这里是所有下载资源的统一管理中心。
|
||||
|
||||
|
||||
|
||||
@@ -126,7 +128,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
- **邮箱验证**：该资源是否需要验证（需要 / 不需要）
|
||||
- **启用**：开关即改即存
|
||||
- **引用文章**：引用该资源下载链接的文章数，点击展开详情（见第七节）
|
||||
- **引用文章**：引用该资源下载链接的文章数，点击展开详情（见第八节）
|
||||
- **下载数 / 下载人数**：累计下载次数 / 去重后的下载人数（验证资源按邮箱去重，免验证资源按 IP 去重）
|
||||
- **操作**：记录（下载记录）、编辑、删除
|
||||
|
||||
@@ -134,15 +136,58 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 五、访客看到的下载页
|
||||
## 五、受保护链接（超链接访问门禁）
|
||||
|
||||
### 5.1 免验证资源
|
||||
除了附件下载，插件也可以给任意 **http/https 超链接**加一道访问门禁：访客先打开门禁页（需要时先完成邮箱验证），验证通过后才 302 跳转到真实地址。适合隐藏真实地址、按邮箱验证放行、统计访问量等场景。
|
||||
|
||||
| 能力 | 说明 |
|
||||
|---|---|
|
||||
| **访问门禁** | 为每个链接生成 `/link/{slug}` 门禁页，验证通过后才跳转 |
|
||||
| **邮箱验证** | 按链接开关，与下载共用同一套验证码体系（验证过的邮箱两者通用） |
|
||||
| **访问统计** | 每次跳转记录时间/邮箱/IP/UA，可导出 CSV；列表展示访问次数与去重访问人数 |
|
||||
| **真实地址隐藏** | 门禁页不展示目标 URL，访客只有验证通过才会被跳转 |
|
||||
| **文章引用扫描** | 一键扫描全站文章中出现的 `/link/{slug}` |
|
||||
|
||||
### 5.1 创建受保护链接
|
||||
|
||||
控制台 **「资源访问管理」→ 受保护链接** 页签 → **新建链接**：
|
||||
|
||||
- **链接名称**：访客在门禁页看到的标题
|
||||
- **slug**：访问链接为 `/link/{slug}`，创建后不可修改；留空时会按目标链接自动生成建议值
|
||||
- **目标链接**：验证通过后跳转的 http/https 地址，不会在门禁页展示
|
||||
- **需要邮箱验证**：开启后访客需输入邮箱收取验证码（邮件模板与下载验证区分开，标题为「链接访问验证码」）
|
||||
- **启用**：停用后门禁页 404
|
||||
|
||||
### 5.2 访客流程
|
||||
|
||||
```
|
||||
文章中粘贴 /link/xxx（门禁页链接）
|
||||
│
|
||||
▼
|
||||
访客打开门禁页
|
||||
├─ 不需要验证：点击「继续访问」
|
||||
└─ 需要验证：输入邮箱 → 收验证码 → 填验证码
|
||||
│
|
||||
▼
|
||||
换取一次性访问令牌（与下载共用「访问令牌有效期」设置）→ 302 跳转到目标地址
|
||||
│
|
||||
▼
|
||||
后台记录一次访问（次数 +1，写入访问记录）
|
||||
```
|
||||
|
||||
> 与下载资源一样，访问令牌一次性有效，跳转后即失效；免验证链接同一 IP 在去重窗口内的重复访问只计 1 次。
|
||||
|
||||
---
|
||||
|
||||
## 六、访客看到的下载页
|
||||
|
||||
### 6.1 免验证资源
|
||||
|
||||
|
||||
|
||||
页面展示资源名称和描述，点击 **「立即下载」** 即开始下载。简单直接。
|
||||
|
||||
### 5.2 需要邮箱验证的资源
|
||||
### 6.2 需要邮箱验证的资源
|
||||
|
||||
|
||||
|
||||
@@ -158,7 +203,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 六、下载统计与记录
|
||||
## 七、下载统计与记录
|
||||
|
||||
在资源列表点击 **「记录」**，打开该资源的下载记录：
|
||||
|
||||
@@ -180,7 +225,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 七、文章引用扫描
|
||||
## 八、文章引用扫描
|
||||
|
||||
资源多了之后最容易遇到的问题：「这个资源到底在哪些文章里用过？删了会不会有文章变死链？」
|
||||
|
||||
@@ -195,16 +240,16 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 八、邮箱验证详解
|
||||
## 九、邮箱验证详解
|
||||
|
||||
### 8.1 验证状态的来龙去脉
|
||||
### 9.1 验证状态的来龙去脉
|
||||
|
||||
- 验证通过后，邮箱会被**永久登记**为「已验证」，之后下载任何需要验证的资源都无需再验证；
|
||||
- 「已验证邮箱」有两个来源（可在设置中关掉第二个）：
|
||||
1. **本插件验证过的**：在下载页完成验证码验证的邮箱；
|
||||
2. **评论插件验证过的**（互认）：评论组件中「已验证邮箱」名单里的访客。开启「信任评论插件已验证的邮箱」后，在评论区验证过的读者下载时直接免验证，体验无缝。
|
||||
|
||||
### 8.2 安全设计（了解即可）
|
||||
### 9.2 安全设计（了解即可）
|
||||
|
||||
- 验证码 6 位数字，10 分钟有效，一次性使用，连续输错 5 次作废；
|
||||
- 验证码比对使用恒时比较，防时序攻击；
|
||||
@@ -213,7 +258,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 九、防直链原理与边界
|
||||
## 十、防直链原理与边界
|
||||
|
||||
**原理**：插件在请求层面拦截 `GET/HEAD /upload/**`，如果目标附件已被注册为「启用的下载资源」，对外直接返回 404（就像文件不存在一样）；访客只能通过 `/download/{slug}` 下载页获取文件——文件由插件直接从服务器磁盘流式输出，**真实存储路径全程不暴露**。
|
||||
|
||||
@@ -229,7 +274,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 十、注意事项汇总
|
||||
## 十一、注意事项汇总
|
||||
|
||||
1. **图片与下载资源分离**：需要直接展示的图片不要注册为资源；建议下载类文件（zip/pdf 等）单独建一个附件分组管理。
|
||||
2. **slug 创建后不可改**：改 slug 等于换链接，旧链接立即失效。如确需更换，新建资源并在文章里换链接（可用引用扫描找出所有旧链接位置）。
|
||||
@@ -241,7 +286,7 @@ Halo 默认的附件可以通过 `/upload/文件名` 直链被任何人直接下
|
||||
|
||||
---
|
||||
|
||||
## 十一、常见问题 FAQ
|
||||
## 十二、常见问题 FAQ
|
||||
|
||||
**Q：访客点下载没反应？**
|
||||
A：下载令牌默认 60 秒有效，网络慢导致跳转超时时会自动回到下载页，重新点击即可。
|
||||
|
||||
Reference in New Issue
Block a user