资源下载管理（sharelink）插件 · 配置指南与使用说明

适用版本：sharelink 1.0.x / Halo ≥ 2.22（已在 Halo Pro 2.25.4 实测）

本文配合截图说明插件的功能、配置方法、使用流程和注意事项。

目录

1. 插件是做什么的

2. 安装与启用

3. 全局配置

4. 日常使用：创建下载资源

5. 访客看到的下载页

6. 下载统计与记录

7. 文章引用扫描

8. 邮箱验证详解

9. 防直链原理与边界

10. 注意事项汇总

11. 常见问题 FAQ

一、插件是做什么的

Halo 默认的附件可以通过 /upload/文件名 直链被任何人直接下载，无法统计、无法设防。本插件把「资源下载」变成可管理的一等公民：

工作流程（一图流）

文章中粘贴 /download/xxx 链接
        │
        ▼
访客打开下载页（插件生成的独立页面）
        │
        ├─ 不需要验证：点击「立即下载」
        └─ 需要验证：输入邮箱 → 收验证码 → 填验证码
        │
        ▼
换取一次性下载令牌（默认 60 秒有效）→ 开始下载
        │
        ▼
后台记录一次下载（次数 +1，写入记录）

二、安装与启用

1. 进入 Console → 系统 → 插件，点击右上角 「安装」。

2. 选择 「本地上传」 上传 sharelink-x.y.z.jar（或「远程下载」粘贴 jar 地址）。

3. 安装后在插件列表找到 「资源下载管理」，点击启用。

4. 启用成功后，左侧菜单 「内容」 分组下会出现 「下载管理」 入口。

⚠️ 升级插件时的两个坑（Halo 通用行为，非本插件问题）：

• 用同名单 jar 覆盖安装时，会弹出「插件已存在，是否升级？」确认框，必须点「确定」 才会真正替换。

• 后台界面静态资源按 ?version= 缓存。每次发布新版本必须递增版本号，否则浏览器会继续使用旧界面。

三、全局配置

进入 系统 → 插件 → 资源下载管理 → 设置，有两个标签页。

3.1 基本设置

3.2 邮箱验证

⚠️ 邮箱验证依赖 Halo 的邮件通知能力。请确认 设置 → 通知设置 中已配置可用的邮件通知器（SMTP），否则验证码邮件发不出去。你的站点配置评论插件时应该已经配好。

四、日常使用：创建下载资源

进入 内容 → 下载管理，这里是所有下载资源的统一管理中心。

4.1 新建资源

点击右上角 「新建资源」：

字段	说明
资源名称 *	显示给访客的名称，也是下载文件的文件名（无扩展名时自动补上附件原扩展名）
slug *	下载链接的标识，如填 whitepaper-2024，下载链接就是 /download/whitepaper-2024。仅限小写字母、数字、中划线。创建后不可修改
描述	可选，显示在下载页标题下方
附件	点击「选择附件」从附件库选择（也可先上传新附件）
需要邮箱验证	开启后访客必须验证邮箱才能下载
启用	停用后下载页和下载链接立即 404，但配置保留

保存后回到列表，点击该行的 「复制」 按钮即可拿到完整下载链接（含域名），粘贴到文章的任意位置（普通链接、按钮、卡片都可以）。

4.2 列表各列含义

• 邮箱验证：该资源是否需要验证（需要 / 不需要）

• 启用：开关即改即存

• 引用文章：引用该资源下载链接的文章数，点击展开详情（见第七节）

• 下载数 / 下载人数：累计下载次数 / 去重后的下载人数（验证资源按邮箱去重，免验证资源按 IP 去重）

• 操作：记录（下载记录）、编辑、删除

⚠️ 删除资源会连同其全部下载记录一起删除，且下载链接立即失效，请谨慎操作。

五、访客看到的下载页

5.1 免验证资源

页面展示资源名称和描述，点击 「立即下载」 即开始下载。简单直接。

5.2 需要邮箱验证的资源

1. 输入邮箱地址；

2. 点击 「发送验证码」，按钮进入 60 秒倒计时，页面提示「验证码已发送，请查收邮件（10 分钟内有效）」；

3. 将邮件中的 6 位验证码填入，点击 「立即下载」。

已验证过的邮箱：下次再访问任何需要验证的资源时，输入邮箱后页面会提示「该邮箱已完成验证，可直接下载」，无需验证码（包括在评论区验证过的邮箱）：

下载页为插件自带的独立页面，不依赖主题，任何主题下表现一致。

六、下载统计与记录

在资源列表点击 「记录」，打开该资源的下载记录：

• 每条记录包含：时间、邮箱（免验证资源显示「匿名」）、IP、User-Agent；

• 支持分页浏览、删除单条记录；

• 点击 「导出 CSV」 可下载全部记录（带 BOM，Excel 直接打开不乱码）。

需要邮箱验证的资源，记录中可以看到具体是哪个邮箱下载的：

计数口径（重要，避免误解数字）：

• 只有真正开始下载才计数：令牌核销成功且文件可输出时记 1 次，下载页浏览不计数、失败不计数；

• 免验证资源：同一 IP 在去重窗口（默认 10 分钟）内重复下载只计 1 次；

• 需要验证的资源：每次换令牌下载都计数（同一人多次下载会体现为次数 > 人数）。

七、文章引用扫描

资源多了之后最容易遇到的问题：「这个资源到底在哪些文章里用过？删了会不会有文章变死链？」

列表的 「引用文章」 列给出答案。点击数字展开：

• 显示每篇引用文章的标题，点击 「编辑器」 直接跳转到文章编辑页，「访问」 打开前台文章页；

• 扫描结果缓存 5 分钟。刚改完文章想立即看到最新结果，点击页面顶部的 「刷新引用扫描」 强制重扫。

扫描口径：只统计已发布文章的正式内容中出现的 /download/{slug}；草稿、回收站文章、历史快照不计入。

八、邮箱验证详解

8.1 验证状态的来龙去脉

• 验证通过后，邮箱会被永久登记为「已验证」，之后下载任何需要验证的资源都无需再验证；

• 「已验证邮箱」有两个来源（可在设置中关掉第二个）：

  1. 本插件验证过的：在下载页完成验证码验证的邮箱；

  2. 评论插件验证过的（互认）：评论组件中「已验证邮箱」名单里的访客。开启「信任评论插件已验证的邮箱」后，在评论区验证过的读者下载时直接免验证，体验无缝。

8.2 安全设计（了解即可）

• 验证码 6 位数字，10 分钟有效，一次性使用，连续输错 5 次作废；

• 验证码比对使用恒时比较，防时序攻击；

• 发码有三级限流：同邮箱 60 秒重发间隔、同邮箱每天 5 封、同 IP 每小时 20 封；

• 邮件通过 Halo 通知中心发出，复用站点已有 SMTP 配置，插件不直接接触邮件密码。

九、防直链原理与边界

原理：插件在请求层面拦截 GET/HEAD /upload/**，如果目标附件已被注册为「启用的下载资源」，对外直接返回 404（就像文件不存在一样）；访客只能通过 /download/{slug} 下载页获取文件——文件由插件直接从服务器磁盘流式输出，真实存储路径全程不暴露。

边界（务必了解）：

⚠️ 最重要的使用纪律：不要把文章中需要直接显示的图片/附件注册为下载资源。注册即等于"此文件只能经下载页获取"。

十、注意事项汇总

1. 图片与下载资源分离：需要直接展示的图片不要注册为资源；建议下载类文件（zip/pdf 等）单独建一个附件分组管理。

2. slug 创建后不可改：改 slug 等于换链接，旧链接立即失效。如确需更换，新建资源并在文章里换链接（可用引用扫描找出所有旧链接位置）。

3. 删除资源会级联删除下载记录。

4. 令牌有效期短是特性：把 /download/xxx/file?token=... 发给别人是无用的（60 秒 + 一次性），分享请分享 /download/xxx 页面链接。

5. 大文件：文件经 Halo 应用中转流式输出，不占内存，但占用服务器带宽；GB 级大文件建议评估带宽。

6. 引用扫描是按需的：不实时监听文章变更，改完文章点「刷新引用扫描」或等 5 分钟缓存过期。

7. 升级插件：确认弹窗要点「确定」；版本号每次递增；升级后界面异常先强刷浏览器。

十一、常见问题 FAQ

Q：访客点下载没反应？
A：下载令牌默认 60 秒有效，网络慢导致跳转超时时会自动回到下载页，重新点击即可。

Q：收不到验证码邮件？
A：① 检查 设置 → 通知设置 的 SMTP 是否可用（评论验证能用即正常）；② 检查垃圾邮件；③ 同一邮箱每天最多发 5 封、同一 IP 每小时 20 封，超限会提示稍后再试。

Q：为什么图片附件注册成资源后文章里图片裂了？
A：这是防直链的预期行为。把该图片从资源中移除（删除资源或换用专用下载文件），图片即可恢复显示。

Q：下载数为什么比下载人数多？
A：正常。同一个人多次下载，次数累加、人数去重。

Q：对象存储附件能防直链吗？
A：不能。防直链只对本地存储策略生效；但统计与邮箱验证对所有存储策略都有效。