shirainbown
13 KiB
资源下载管理（sharelink）插件 · 配置指南与使用说明
适用版本：sharelink 1.0.x / Halo ≥ 2.22（已在 Halo Pro 2.25.4 实测）
本文配合截图说明插件的功能、配置方法、使用流程和注意事项。
💬 遇到问题或有功能建议，欢迎到 博客同名文章 下方留言评论交流。
目录
一、插件是做什么的
Halo 默认的附件可以通过 /upload/文件名 直链被任何人直接下载，无法统计、无法设防。本插件把「资源下载」变成可管理的一等公民：
| 能力 | 说明 |
|---|---|
| 下载链接管理 | 为每个资源生成 /download/{slug} 链接，粘贴到文章即可 |
| 下载统计 | 每个资源的下载次数、去重下载人数、逐条下载记录（时间/邮箱/IP/UA），可导出 CSV |
| 邮箱验证 | 按资源开关。访客需输入邮箱收取验证码，验证通过才能下载；验证过的邮箱长期免验证 |
| 防直链 | 注册为资源的附件，/upload/** 直链对外直接 404，文件真实地址不暴露 |
| 文章引用扫描 | 一键扫描全站文章，告诉你每个下载资源被哪些文章引用 |
工作流程（一图流）
文章中粘贴 /download/xxx 链接
│
▼
访客打开下载页（插件生成的独立页面）
│
├─ 不需要验证：点击「立即下载」
└─ 需要验证：输入邮箱 → 收验证码 → 填验证码
│
▼
换取一次性下载令牌（默认 60 秒有效）→ 开始下载
│
▼
后台记录一次下载（次数 +1，写入记录）
二、安装与启用
- 进入 Console → 系统 → 插件，点击右上角 「安装」。
- 选择 「本地上传」 上传
sharelink-x.y.z.jar（或「远程下载」粘贴 jar 地址）。 - 安装后在插件列表找到 「资源下载管理」，点击启用。
- 启用成功后，左侧菜单 「内容」 分组下会出现 「下载管理」 入口。
⚠️ 升级插件时的两个坑（Halo 通用行为，非本插件问题）：
- 用同名单 jar 覆盖安装时，会弹出「插件已存在，是否升级？」确认框，必须点「确定」 才会真正替换。
- 后台界面静态资源按
?version=缓存。每次发布新版本必须递增版本号，否则浏览器会继续使用旧界面。
三、全局配置
进入 系统 → 插件 → 资源下载管理 → 设置，有两个标签页。
3.1 基本设置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 下载令牌有效期（秒） | 60 | 访客在下载页点击下载后，插件签发一次性下载令牌，需在此时长内开始下载。过期或已使用的令牌会跳回下载页重新获取，防止下载地址被传播复用 |
| 免验证资源下载去重窗口（分钟） | 10 | 不需要邮箱验证的资源，同一 IP 在窗口内重复下载只计 1 次（防止刷新刷量），但下载行为本身不受限 |
3.2 邮箱验证
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 验证码有效期（分钟） | 10 | 验证码超过该时长未使用即失效 |
| 重发间隔（秒） | 60 | 同一邮箱两次发码的最小间隔（下载页按钮有倒计时） |
| 同一邮箱每日发送上限 | 5 | 防止针对单个邮箱的轰炸 |
| 验证码最大错误尝试次数 | 5 | 连续输错超过该次数，验证码作废，需重新获取 |
| 同一 IP 每小时发送上限 | 20 | 防止单个 IP 批量发码 |
| 信任评论插件已验证的邮箱 | 开启 | 开启后，在评论组件中已验证过邮箱的访客，下载需要验证的资源时无需再次验证（需安装评论组件插件） |
⚠️ 邮箱验证依赖 Halo 的邮件通知能力。请确认 设置 → 通知设置 中已配置可用的邮件通知器（SMTP），否则验证码邮件发不出去。你的站点配置评论插件时应该已经配好。
四、日常使用：创建下载资源
进入 内容 → 下载管理，这里是所有下载资源的统一管理中心。
4.1 新建资源
点击右上角 「新建资源」：
| 字段 | 说明 |
|---|---|
| 资源名称 * | 显示给访客的名称，也是下载文件的文件名（无扩展名时自动补上附件原扩展名） |
| slug * | 下载链接的标识，如填 whitepaper-2024，下载链接就是 /download/whitepaper-2024。仅限小写字母、数字、中划线。创建后不可修改 |
| 描述 | 可选，显示在下载页标题下方 |
| 附件 | 点击「选择附件」从附件库选择（也可先上传新附件） |
| 需要邮箱验证 | 开启后访客必须验证邮箱才能下载 |
| 启用 | 停用后下载页和下载链接立即 404，但配置保留 |
保存后回到列表，点击该行的 「复制」 按钮即可拿到完整下载链接（含域名），粘贴到文章的任意位置（普通链接、按钮、卡片都可以）。
4.2 列表各列含义
- 邮箱验证：该资源是否需要验证（需要 / 不需要）
- 启用：开关即改即存
- 引用文章：引用该资源下载链接的文章数，点击展开详情（见第七节）
- 下载数 / 下载人数：累计下载次数 / 去重后的下载人数（验证资源按邮箱去重，免验证资源按 IP 去重）
- 操作：记录（下载记录）、编辑、删除
⚠️ 删除资源会连同其全部下载记录一起删除，且下载链接立即失效，请谨慎操作。
五、访客看到的下载页
5.1 免验证资源
页面展示资源名称和描述，点击 「立即下载」 即开始下载。简单直接。
5.2 需要邮箱验证的资源
- 输入邮箱地址；
- 点击 「发送验证码」，按钮进入 60 秒倒计时，页面提示「验证码已发送，请查收邮件（10 分钟内有效）」；
- 将邮件中的 6 位验证码填入，点击 「立即下载」。
已验证过的邮箱：下次再访问任何需要验证的资源时，输入邮箱后页面会提示「该邮箱已完成验证，可直接下载」，无需验证码（包括在评论区验证过的邮箱）：
下载页为插件自带的独立页面，不依赖主题，任何主题下表现一致。
六、下载统计与记录
在资源列表点击 「记录」，打开该资源的下载记录：
- 每条记录包含：时间、邮箱（免验证资源显示「匿名」）、IP、User-Agent；
- 支持分页浏览、删除单条记录；
- 点击 「导出 CSV」 可下载全部记录（带 BOM，Excel 直接打开不乱码）。
需要邮箱验证的资源，记录中可以看到具体是哪个邮箱下载的：
计数口径（重要，避免误解数字）：
- 只有真正开始下载才计数：令牌核销成功且文件可输出时记 1 次，下载页浏览不计数、失败不计数；
- 免验证资源：同一 IP 在去重窗口（默认 10 分钟）内重复下载只计 1 次；
- 需要验证的资源：每次换令牌下载都计数（同一人多次下载会体现为次数 > 人数）。
七、文章引用扫描
资源多了之后最容易遇到的问题：「这个资源到底在哪些文章里用过？删了会不会有文章变死链？」
列表的 「引用文章」 列给出答案。点击数字展开：
- 显示每篇引用文章的标题，点击 「编辑器」 直接跳转到文章编辑页，「访问」 打开前台文章页；
- 扫描结果缓存 5 分钟。刚改完文章想立即看到最新结果，点击页面顶部的 「刷新引用扫描」 强制重扫。
扫描口径：只统计已发布文章的正式内容中出现的 /download/{slug}；草稿、回收站文章、历史快照不计入。
八、邮箱验证详解
8.1 验证状态的来龙去脉
- 验证通过后，邮箱会被永久登记为「已验证」，之后下载任何需要验证的资源都无需再验证；
- 「已验证邮箱」有两个来源（可在设置中关掉第二个）：
- 本插件验证过的：在下载页完成验证码验证的邮箱；
- 评论插件验证过的（互认）：评论组件中「已验证邮箱」名单里的访客。开启「信任评论插件已验证的邮箱」后，在评论区验证过的读者下载时直接免验证，体验无缝。
8.2 安全设计（了解即可）
- 验证码 6 位数字，10 分钟有效，一次性使用，连续输错 5 次作废；
- 验证码比对使用恒时比较，防时序攻击；
- 发码有三级限流：同邮箱 60 秒重发间隔、同邮箱每天 5 封、同 IP 每小时 20 封；
- 邮件通过 Halo 通知中心发出，复用站点已有 SMTP 配置，插件不直接接触邮件密码。
九、防直链原理与边界
原理：插件在请求层面拦截 GET/HEAD /upload/**，如果目标附件已被注册为「启用的下载资源」，对外直接返回 404（就像文件不存在一样）；访客只能通过 /download/{slug} 下载页获取文件——文件由插件直接从服务器磁盘流式输出，真实存储路径全程不暴露。
边界（务必了解）：
| 场景 | 是否生效 |
|---|---|
| 本地存储策略的附件（你当前的使用方式） | ✅ 直链 404 |
| 外部对象存储（S3/OSS 等）的附件 | ❌ 无法拦截（文件不经 Halo 发出），但下载统计和邮箱验证仍正常 |
| 同一附件被文章当图片直接引用 | ⚠️ 会被一并拦截，图片变 404！ |
⚠️ 最重要的使用纪律：不要把文章中需要直接显示的图片/附件注册为下载资源。注册即等于"此文件只能经下载页获取"。
十、注意事项汇总
- 图片与下载资源分离：需要直接展示的图片不要注册为资源；建议下载类文件（zip/pdf 等）单独建一个附件分组管理。
- slug 创建后不可改：改 slug 等于换链接，旧链接立即失效。如确需更换，新建资源并在文章里换链接（可用引用扫描找出所有旧链接位置）。
- 删除资源会级联删除下载记录。
- 令牌有效期短是特性：把
/download/xxx/file?token=...发给别人是无用的（60 秒 + 一次性），分享请分享/download/xxx页面链接。 - 大文件：文件经 Halo 应用中转流式输出，不占内存，但占用服务器带宽；GB 级大文件建议评估带宽。
- 引用扫描是按需的：不实时监听文章变更，改完文章点「刷新引用扫描」或等 5 分钟缓存过期。
- 升级插件：确认弹窗要点「确定」；版本号每次递增；升级后界面异常先强刷浏览器。
十一、常见问题 FAQ
Q：访客点下载没反应？ A：下载令牌默认 60 秒有效，网络慢导致跳转超时时会自动回到下载页，重新点击即可。
Q：收不到验证码邮件？ A：① 检查 设置 → 通知设置 的 SMTP 是否可用（评论验证能用即正常）；② 检查垃圾邮件；③ 同一邮箱每天最多发 5 封、同一 IP 每小时 20 封，超限会提示稍后再试。
Q：为什么图片附件注册成资源后文章里图片裂了？ A：这是防直链的预期行为。把该图片从资源中移除（删除资源或换用专用下载文件），图片即可恢复显示。
Q：下载数为什么比下载人数多？ A：正常。同一个人多次下载，次数累加、人数去重。
Q：对象存储附件能防直链吗？ A：不能。防直链只对本地存储策略生效；但统计与邮箱验证对所有存储策略都有效。