nurl 密钥管理

nurl 是 Short_NURL 的本地管理工具，纯本地文件读写。

工具	定位	依赖网络	用途
`nurl`	本地管理工具	否	密钥生成/查看/撤销、清理过期数据、数据文件健康检查
`nurl-key`	远程短链客户端	是	通过无头 API 查看/创建/删除短链（点此跳转）

本文档使用 {花括号} 标记占位符，使用时请替换为实际值：

占位符	含义	示例
`{你的域名}`	短链服务部署的域名	`s.example.com`
`{su_你的Key}`	你的 API Key	`su_aBcDeFgH1234`

一、运行方式

cd {项目目录}

php nurl

二、命令总览

标志	说明
`-new`	生成常驻密钥 + 补充一次性密钥池
`-long`	仅轮换常驻密钥
`-full`	仅补充一次性密钥池
`-svc`	生成服务密钥（永不过期，用于服务间集成）
`-svc -label:X`	指定服务密钥标签（默认 `default`）
`-itk`	生成/轮换内部通信令牌（LPA-Key）
`-look`	显示密钥状态（不显示明文）
`-drop`	撤销所有密钥（含内部令牌）
`-drop -long`	仅删除常驻密钥
`-drop -full`	仅删除所有一次性密钥
`-drop -svc`	仅删除服务密钥
`-drop -itk`	仅删除内部通信令牌
`-sweep`	清理过期临时短链
`-v`	显示脚本内置的旧版自定义信息（不能据此判断 Short_NURL 软件版本）
`-h` / `-help`	显示帮助信息

三、使用示例

密钥类型与权限

类型	有效期与次数	无头 API（`X-Headless-Token`）	前端 API（`X-Token`）
常驻密钥（resident）	默认 7 天，不限次数；再次执行 `-new` / `-long` 会立即替换旧密钥	创建、查询、列表、配额、删除	可用
一次性密钥（onetime）	使用前永不过期；认证成功时立即消费，只能使用一次	可创建、查询单条；列表、配额、删除返回 `403 onetime_forbidden`	可创建；管理接口同样受限
服务密钥（service）	永不过期、不限次数；同一时间只能存在一个	可执行全部操作；创建时按 `svc_*_limit` 阈值检查，并支持最长 5 位短码	返回 `406`，不可用于前端 API 链路

一次性密钥在认证阶段就会被消费，而不是等业务操作成功后才消费。因此，即使后续参数错误、短码冲突，或调用了无权访问的管理接口，该密钥也不能再次使用。系统不会自动补充一次性密钥池，请使用 php nurl -full 手动补充。

1. 创建密钥

同时生成新的常驻密钥并补充一次性密钥池至最大容量。

php nurl -new

2. 生成服务密钥

生成永不过期的服务密钥，适用于服务间集成。

php nurl -svc

可通过 -label:X 指定标签（默认 default）：

php nurl -svc -label:{你的项目 Name}

服务密钥仅可同时存在一个。如需更换，请先使用 -drop -svc 撤销旧密钥。

服务密钥仅限 nurl-key（X-Headless-Token）链路。前端面板 API（X-Token）会拒绝服务密钥并返回 406 服务密钥不可用于前端API链路。使用服务密钥创建时，服务端按 svc_perm_limit / svc_temp_limit 选择配额阈值；这些密钥并不拥有独立的短链数据池。还可通过 nurl-key -len 4|5 选择自动生成的短码长度；详见 nurl-key 短链管理。

3. 管理内部通信令牌

内部通信令牌（LPA-Key）用于 PHP↔Lua 内部 API 认证。nurl -new 仅在令牌文件为空或不存在时自动生成，也可单独生成或轮换。

php nurl -itk

PHP 和 Lua 会在每次内部请求时重新读取令牌文件，不在进程内缓存，因此轮换立即生效，无需 reload nginx。令牌缺失或文件不可读时采用 fail-close：Lua 内部接口返回 500 internal token missing；令牌不匹配时返回 403 Forbidden，不会跳过认证。

清除 LPA-Key 后，冷存储操作仍可能完成，但热存储同步会失败：创建响应会出现 synced=false 与 warning，删除响应会出现 synced=false，配额响应会出现 hot_available=false。请尽快执行 php nurl -itk 恢复内部通信。

4. 撤销密钥

php nurl -drop

已撤销：all
所有 API 密钥（含服务密钥）已被撤销。在生成新密钥之前，请求将返回 406。

撤销操作不可逆。撤销后所有使用该密钥的请求将返回 406 密钥失效或不正确。

5. 轮换常驻密钥

php nurl -long

6. 补充一次性密钥池

php nurl -full

7. 查看密钥状态

显示当前常驻密钥的元数据和一次性密钥池状态，不会显示密钥明文。

php nurl -look

8. 清理过期短链

php nurl -sweep

PHP 写操作（create / delete）时会顺带清理过期条目。-sweep 适用于长期无写操作时手动清理，防止 temp.json 持续膨胀。

四、错误处理

错误信息	原因
`此脚本必须从命令行运行。`	通过浏览器访问了 CLI 脚本
`未找到 config.php`	在错误的目录运行命令
`-long 和 -full 不能同时使用`	标志冲突
`-drop 一次只能指定一个目标（-long / -full / -svc / -itk）`	一次指定了多个撤销目标
`无可用密钥，请先执行 php nurl -new 初始化`	密钥库为空时直接执行了 `-long` 或 `-full`
`服务密钥已存在，请先使用 -drop -svc 撤销旧密钥`	同一时间只允许存在一个服务密钥
`keys.json 数据损坏，请手动检查`	密钥文件不是有效 JSON；工具会拒绝覆盖原文件
`未知标志 xxx`	输入了不存在的标志
`[safe_write] ...`	写入验证失败

声明

作者：圣堂之魂；发布于：2026-05-22；修改于：2026-08-24；许可协议：CC BY-NC-SA 4.0

nurl 密钥管理

声明

本页目录