nurl 密钥管理

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

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

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

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

一、运行方式

cd {项目目录}

php nurl

docker exec -it {PHP容器名} bash

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`	查看版本
`-h` / `-help`	显示帮助信息

三、使用示例

1. 创建密钥

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

php nurl -new

正在生成 API 密钥...

━━━ 常驻密钥 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  su_Egj....
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
有效期：7 天。过期时间：2026-05-30T00:00:00+08:00

一次性密钥池已满（20/20）。

密钥已存储至：/.../../backend/data/keys.json

2. 生成服务密钥

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

php nurl -svc

正在生成服务密钥...

━━━ 服务密钥 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  su_SvcKey...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
此密钥永不过期，不限使用次数，适用于服务间集成。
仅限无头模式使用（nurl-key / X-Headless-Token），前端 API 将拒绝此密钥。
请将此密钥配置到需要调用短链 API 的服务环境变量中。
请立即保存，之后将不再显示。

密钥已存储至：/.../../backend/data/keys.json

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

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

正在生成服务密钥（标签：{你的项目 Name}）...

━━━ 服务密钥 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  su_SvcKey...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
此密钥永不过期，不限使用次数，适用于服务间集成。
仅限无头模式使用（nurl-key / X-Headless-Token），前端 API 将拒绝此密钥。
请将此密钥配置到需要调用短链 API 的服务环境变量中。
请立即保存，之后将不再显示。

密钥已存储至：/.../../backend/data/keys.json

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

服务密钥仅限nurl-key（X-Headless-Token）链路。前端面板 API（X-Token）会拒绝服务密钥并返回 406。

3. 管理内部通信令牌

内部通信令牌（LPA-Key）用于 PHP↔Lua 内部 API 认证。nurl -new 首次执行时自动生成，也可单独操作。

php nurl -itk

php nurl -drop -itk

已清除内部通信令牌。
内部通信将跳过认证，直到重新生成（php nurl -itk 或 php nurl -new）。
注意：需 reload nginx 后 Lua 侧才会跳过校验。

正在生成内部通信令牌（LPA-Key）...

━━━ 内部通信令牌（LPA-Key）━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  5b7b8a45d3e0db168547...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
已写入：/.../../backend/data/internal_token
用于 PHP↔Lua 内部通信认证。
注意：轮换后需 reload nginx（如 nginx -s reload）令牌才在 Lua 侧生效，
      reload 前内部同步会返回 403（synced=false），属正常现象。

轮换令牌后需 nginx -s reload，因为 Lua 侧在 worker 启动时将令牌缓存到内存。

4. 撤销密钥

php nurl -drop

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

php nurl -drop -long

已撤销：resident
常驻密钥已被撤销。请使用 'php nurl -long' 生成新密钥。

php nurl -drop -full

已撤销：onetime
所有一次性密钥已被撤销。请使用 'php nurl -full' 补充新密钥。

php nurl -drop -svc

已撤销：service
服务密钥已被撤销。请使用 'php nurl -svc' 生成新密钥，并更新对应服务的环境变量。

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

5. 轮换常驻密钥

php nurl -long

正在生成 API 密钥...

━━━ 常驻密钥 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  su_PhT....
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
有效期：7 天。过期时间：2026-05-30T00:30:00+08:00

密钥已存储至：/.../../backend/data/keys.json

6. 补充一次性密钥池

php nurl -full

正在生成 API 密钥...

━━━ 一次性密钥（新增 15 个）━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. su_xYz987...
  ...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
请立即保存所有密钥，之后将不再显示。
每个密钥仅可使用一次。使用后会自动生成新密钥。
密钥永不过期，直到被使用。

密钥已存储至：/.../../backend/data/keys.json

正在生成 API 密钥...

一次性密钥池已满（20/20）。

密钥已存储至：/.../../backend/data/keys.json

7. 查看密钥状态

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

php nurl -look

API 密钥状态
────────────────────────────────────────────────────────────

  常驻密钥：
    前缀：      su_PhTq5
    创建时间：  2026-05-23T00:00:00+08:00
    过期时间：  2026-05-30T00:00:00+08:00

  服务密钥：
    前缀：      su_SvcKey
    创建时间：  2026-05-23T00:00:00+08:00
    标签：      default
    有效期：    永不过期

  一次性密钥池：20/20 个密钥
    1. su_mnotD  （创建时间：2026-05-23T00:00:00+08:00）
    2. su_7IHy9  （创建时间：2026-05-23T00:00:00+08:00）
    ...

  内部通信令牌（LPA-Key）：5b7b8a45...（已设置）

8. 清理过期短链

php nurl -sweep

正在清理过期临时短链...

已清理 5 条过期临时短链。
剩余：12 条。

正在清理过期临时短链...

无需清理，无过期条目。

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

四、错误处理

错误信息	原因
`此脚本必须从命令行运行。`	通过浏览器访问了 CLI 脚本
`未找到 config.php`	在错误的目录运行命令
`-long 和 -full 不能同时使用`	标志冲突
`未知标志 xxx`	输入了不存在的标志
`[safe_write] ...`	写入验证失败

声明

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

nurl 密钥管理

声明

本页目录