授权管理插件完整功能介绍与使用教程
文档面向插件使用者、站点管理员和插件发行者。本文根据当前项目源码整理，更新时间：2026-06-28。
文档中的配图为功能演示图，界面布局以实际安装后的 Halo Console / 用户中心为准。
功能体验
1. 插件定位
授权管理插件用于给自定义 Halo 插件提供统一的授权中心。它把“插件目录发布、用户授权申请、管理员审核、永久授权码、用户自助激活、许可证下载、公共授权校验、第三方发卡对接、过期清理和通知”放在一套流程里管理。
适合这些场景：
你维护多个 Halo 插件，希望统一管理插件下载、文档、价格和付款链接。
你需要按用户和域名控制插件授权。
你希望用户可以在用户中心自助申请授权、输入授权码、下载许可证。
你需要批量生成永久授权码，并按 QQ、微信、支付宝、爱发电、发卡平台等渠道追踪。
你需要业务插件通过 API 校验当前域名是否已授权。
2. 环境与入口
基础要求：
安装后主要入口：
3. 核心概念
3.1 插件目录
插件目录对应资源 LywqPlugin，表示一个可被授权的插件。
关键字段：
3.2 授权记录
授权记录对应资源 LywqPluginAuthLog，表示“某个用户的某个域名是否拥有某个插件的授权”。
关键字段：
3.3 永久授权码
永久授权码对应资源 PermanentAuthCode，用于付费或长期授权场景。
授权码状态：
授权码兑换成功后，系统会创建永久授权用户，并把授权记录有效期设置到 2099-12-31。
3.4 永久授权用户
永久授权用户对应资源 PermanentAuthUser，表示某个用户对某个插件拥有长期授权资格。用户再次为同一插件申请域名授权时，会直接获得长期授权。
4. 基础配置教程
安装并启用插件后，先进入 Console → 系统 → 插件 → 授权管理插件 → 设置 完成基础配置。
建议优先配置：
注意：如果开启定时清理，已授权记录必须有合理的 expireTime。当前实现中，authStatus=1 且 expireTime 为空的记录也会被清理任务处理为未授权，别把空时间当“永久”，这坑挺隐蔽。
5. 功能总览
插件围绕四类角色/系统协作：
6. 管理员教程：插件目录管理
6.1 新建插件
进入 插件授权 页面，左侧为插件目录。点击左侧列表底部或页面上的 新建，打开插件表单。
填写建议：
6.2 编辑和删除插件
在左侧插件列表中打开操作菜单：
修改：更新插件名称、版本、价格、文档、下载地址等。
删除：删除插件，并同步删除该插件下的授权记录。
拖拽排序：调整插件展示顺序，排序会写入
priority。
删除插件会清掉关联授权记录，别手滑。这个操作不适合“临时下架”，临时下架更建议改下载地址或文档说明。
7. 管理员教程：授权记录管理
授权记录是插件的核心工作台。管理员可以查看、筛选、审核和批量处理用户授权。
7.1 查看授权记录
右侧列表展示授权记录，主要信息包括：
授权用户
授权域名
关联插件
授权状态
到期时间
创建时间
到期时间显示规则：
7.2 筛选和搜索
支持按以下条件筛选：
7.3 手动新建授权
点击 新建，填写：
插件唯一标识
授权用户
授权域名
授权码/license（可留空）
授权时间
授权到期时间
授权状态
如果你直接把状态设为“已授权”，但没有填写授权时间和过期时间，前端会自动补默认值：授权时间为当前时间，过期时间为当前时间后 3 年。
7.4 单条授权
对未授权记录点击 授权，会把该记录改为已授权，并写入：
authTime：当前时间expireTime：当前时间后 3 年authStatus：1
如果需要自定义有效期，授权后再进入编辑弹窗修改到期时间。
7.5 批量授权、取消和删除
勾选多条记录后，顶部会出现批量操作：
当前批量授权逻辑默认把过期时间设置为当前时间后 3 天，而单条授权默认是 3 年。这个差异不小，批量操作前先确认你的运营策略，别一批授权刚发出去三天就到期，整得用户以为你在搞闪电售后。
7.6 导入和导出授权记录
导入支持 YAML 文件，适合迁移或批量初始化授权记录。导出会生成 lywqPluginAuthLogs.yaml。
建议：
导入前先在测试环境验证 YAML 格式。
不要跨插件随意改
metadata.name，授权记录名称由插件 key、域名、用户组成。批量导入后检查授权状态和过期时间。
8. 用户教程：自助授权
用户可以在 自助授权 页面完成申请、激活和许可证下载。
8.1 提交授权申请
点击 提交授权申请，填写：
提交后，系统会把 URL 转成域名保存，例如 https://www.example.com 会保存为 www.example.com。
提交结果：
如果用户已有该插件永久授权资格，系统会直接创建已授权记录。
如果没有永久授权资格，系统会创建待审核授权记录。
如果插件不存在或用户不存在，会返回失败提示。
如果超过授权数量限制，会提示“授权数量已超限”。
8.2 输入验证码激活
在授权卡片中点击 授权 或 重新授权，输入授权码。
不同价格类型对应不同激活方式：
临时免费验证码由 /public/generateAuthCode 生成，有效期 5 分钟。永久授权码由管理员或第三方发卡系统生成。
8.3 获取免费码或购买授权
自助授权弹窗中可能出现两个入口：
8.4 下载许可证
授权成功后，卡片会展示 许可证书 链接。点击后会下载 license.key。
许可证下载逻辑：
只允许当前登录用户下载自己的授权许可证。
必须传入
pluginKey和authDomain。授权状态为已授权时，系统会生成新的 license，并保存到授权记录。
8.5 删除自己的授权
用户可以删除自己的授权记录。删除后不可恢复，需要重新提交授权申请。
9. 管理员教程：永久授权码管理
永久授权码用于付费授权、长期授权、发卡平台销售等场景。
9.1 批量生成授权码
进入 插件授权 → 永久授权管理 → 授权码，点击 新建。
选择 批量生成，填写：
生成后状态为 PENDING。
9.2 指定用户生成授权码
选择 指定用户，填写授权用户。该授权码只能被指定用户兑换。源码中会校验当前登录用户与授权码绑定用户是否一致，不一致则兑换失败。
9.3 授权码兑换后的变化
用户输入永久授权码并通过校验后：
授权码状态改为
USED。授权码记录写入
authUser和authTime。系统创建
PermanentAuthUser。当前授权记录改为已授权。
到期时间设置为
2099-12-31。
9.4 筛选、导出和删除
授权码列表支持：
按授权插件筛选
按授权用户筛选
按渠道筛选
按状态筛选
按关键词搜索
批量导出授权码 TXT
单条或批量删除
导出的 TXT 每行一个授权码，适合交给发卡平台或客服发放。
10. 管理员教程：永久授权用户管理
永久授权用户表示“某个用户对某个插件长期有效”。它通常由永久授权码兑换产生，也可以由管理员手动创建。
10.1 查看永久授权用户
进入 永久授权管理 → 用户 标签页，可以查看：
授权用户
授权插件
创建时间
授权时间
10.2 手动创建永久授权用户
点击 新建，填写：
创建后，该用户再次为该插件提交域名授权时，会自动通过授权。
10.3 删除永久授权用户
删除永久授权用户只会删除“长期资格”记录，不一定自动删除已经存在的授权记录。需要回到授权记录列表检查已有授权是否也要取消。
11. 管理员教程：通知与定时清理
11.1 批量通知用户
在 插件授权 页面点击 通知用户。
填写：
系统会按插件和授权状态查询授权记录，去重后获取用户邮箱，再发送自定义通知。
11.2 授权状态通知
插件内置通知模板 auth-notification，包含：
授权插件
授权域名
授权用户
授权时间
过期时间
跳转地址
通知最终如何投递，取决于 Halo 的通知和邮件配置。
11.3 定时清理过期授权
开启“是否开启定时清理授权”后，系统会注册名为 LywqPluginAuth:clean-auth 的任务。
任务特性：
清理规则：
只处理
authStatus=1的记录。expireTime为空会被视为需要清理。expireTime早于当前时间会被清理。
12. 公共 API 与三方发卡对接
基础路径：
/apis/lywqPluginAuth.muyin.site/v1alpha1 12.1 公共授权接口
如果设置了 apiAccessSecret，调用 /public/** 接口时需要在请求头传入：
Authorization: <apiAccessSecret> 常用接口：
示例：
GET /apis/lywqPluginAuth.muyin.site/v1alpha1/public/checkAuth?pluginKey=halo-plugin-product&authDomain=www.example.com&license=xxxx Authorization: your-api-secret返回成功时，data 中会包含 license。若请求未携带 license，但授权记录有效，系统会生成新的 license 并写回授权记录。
12.2 三方发卡接口
接口：
POST /apis/lywqPluginAuth.muyin.site/v1alpha1/docking/getPermanentAuthCode 参数：
示例：
POST /apis/lywqPluginAuth.muyin.site/v1alpha1/docking/getPermanentAuthCode?dockingAccessSecret=your-secret&pluginKey=halo-plugin-product&channel=ACGFAKA&count=10成功后返回以 | 分隔的授权码字符串。
安全建议：
不要把
dockingAccessSecret暴露在前端页面。生产环境建议配合反向代理或网关限制来源 IP。
corsWhiteList不建议长期设置为*。授权码生成数量受
authCodeCreateLimit限制，避免被异常请求刷爆。
13. 权限说明
插件内置角色模板：
匿名访问角色会放行 /public/** 和 /docking/** 相关 API，但业务接口仍依赖密钥、参数和授权记录校验。上线时别只靠“看起来没人知道接口地址”这种玄学安全。
14. 常见问题
14.1 用户提交授权后为什么还是未授权？
普通用户提交授权申请后，默认会生成未授权记录。需要管理员手动授权，或用户输入有效授权码完成自助激活。
如果用户已经是该插件的永久授权用户，则会直接授权。
14.2 为什么用户无法继续申请新域名？
检查两个限制：
全局设置中的“授权数量限制”
插件目录里的
authCountLimit
插件级限制会覆盖全局限制。-1 表示不限制。
14.3 免费、限时免费、付费插件有什么区别？
14.4 授权码输入后提示不正确怎么办？
按顺序检查：
授权码是否过期。
授权码是否已被使用。
授权码绑定的插件是否与当前授权记录一致。
指定用户授权码是否被其他用户兑换。
免费验证码是否超过 5 分钟有效期。
14.5 为什么授权过期后状态自动变成未授权？
开启定时清理后，系统会扫描已授权记录。如果过期时间为空或早于当前时间，就会把状态改为未授权，并发送通知。
14.6 用户下载不到许可证怎么办？
检查：
授权状态是否为已授权。
请求中的
pluginKey是否正确。请求中的
authDomain是否与授权记录完全一致。当前登录用户是否就是授权记录中的
authUser。
14.7 第三方发卡接口返回“访问密钥不正确”怎么办？
检查请求参数 dockingAccessSecret 是否与插件设置中的“对接三方系统密钥”一致。注意该接口当前使用查询参数校验，不是只靠请求头。
15. 推荐使用流程
新插件上线：
管理员在插件目录中新建插件。
配置文档地址、下载地址、售价和付款地址。
设置授权数量限制。
按销售渠道批量生成永久授权码。
用户提交授权申请。
用户输入授权码完成激活，或管理员手动授权。
用户下载
license.key。被授权插件调用
/public/checkAuth校验授权。
免费试用活动：
把插件售价设置为
9999。配置免费授权码获取地址。
设置自助授权天数。
用户用临时验证码激活短期授权。
到期后清理任务自动取消授权。
用户需要长期使用时，通过付款地址获取永久授权码。
生产环境安全清单：
配置
apiAccessSecret。配置
dockingAccessSecret。收紧
corsWhiteList。控制
authCodeCreateLimit。开启 HTTPS。
对三方发卡接口增加网关或反代访问限制。
定期导出授权码和授权记录备份。
评论