nurl-key 短链管理

nurl-key 是 Short_NURL 的远程短链管理工具，通过无头 API（headless）远程操作短链，需要网络连接。

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

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

占位符	含义	示例
`{你的域名}`	短链服务部署的域名	`s.example.com`
`{su_你的Key}`	你的 API Key	`su_aBcDeFgH1234`
`{长链接}` / `{目标长链接}`	要缩短的原始 URL	`https://example.com/very/long/path`
`{短链后缀}`	短链路径部分，1–4 位	`a1b2`
`{完整短链地址}`	生成的完整短链 URL	`https://s.example.com/a1b2`
`{ISO 8601 过期时间}`	链接过期时间，ISO 8601 格式	`2026-05-20T12:00:00+08:00`
`{永久/临时短链当前数量}`	当前已有的短链数量	`12`
`{永久/临时短链配额上限}`	配额上限值	`9999`

一、运行方式

cd {项目目录}

php nurl

docker exec -it {PHP容器名} bash

cd {项目目录}

php nurl

二、命令总览

操作	说明
`-list`	查看所有短链
`-stat`	查看配额状态
`-get "code"`	查看单条短链
`-add`	创建短链
`-rm`	删除短链
`-v`	查看版本
`-h` / `-help`	显示帮助信息
`-insecure`	跳过 SSL 证书验证（仅用于内网/自签名证书）

三、参数

参数支持两种赋值格式：

格式	示例	说明
空格分隔	`-key "su_xxx"`	经典格式，值紧随标志
冒号分隔（v2.1 新增）	`-key:"su_xxx"`	紧凑格式，同一参数内赋值

参数	说明	示例
`-key "su_xxx"`	API Key（必填）	`-key "su_aBcDe..."` 或 `-key:"su_aBcDe..."`
`-url "https://..."`	目标长链接（-add 必填）	`-url "https://..."` 或 `-url:"https://..."`
`-ttl N`	有效期秒数（默认 0=永久）	`-ttl 604800` 或 `-ttl:604800`
`-code "abc"`	短链后缀，1-4 位（可选）	`-code "demo"` 或 `-code:"demo"`

四、使用示例

1. 创建短链

php nurl-key -key:"{su_你的Key}" -add -url:"{目标长链接}" -ttl:0

正在创建短链...
创建成功 ✓
  短链：{完整短链地址}

php nurl-key -key:"{su_你的Key}" -add -url:"{目标长链接}" -ttl:0 -code:"{短链后缀}"

正在创建短链...
创建成功 ✓
  短链：{完整短链地址}

php nurl-key -key:"{su_你的Key}" -add -url:"{目标长链接}" -ttl:1800

正在创建短链...
创建成功 ✓
  短链：{完整短链地址}
  过期：{ISO 8601 过期时间}

php nurl-key -key:"{su_你的Key}" -add -url:"{目标长链接}" -ttl:0

正在创建短链...
命中去重 ✓（复用已有永久短链，未实际写入）
  短链：{完整短链地址}

TTL 常用值：0 永久 · 1800 30分钟 · 3600 1小时 · 86400 1天 · 604800 7天

2. 查询短链

php nurl-key -key:"{su_你的Key}" -list

短链列表
────────────────────────────────────────────────────────────

永久短链（2 条）：
  1. abc1  →  https://example.com/page1
     https://{你的域名}/abc1
  2. xyz2  →  https://example.com/page2
     https://{你的域名}/xyz2

临时短链（1 条）：
  1. b3k9  →  https://example.com/temp
     https://{你的域名}/b3k9
     过期：2026-06-17T08:00:00+08:00

3. 删除短链

php nurl-key -key:"{su_你的Key}" -rm -code:"{短链后缀}"

正在删除短链 {短链后缀}...
删除成功 ✓
  已删除：{短链后缀}

4. 查看单条短链

php nurl-key -key:"{su_你的Key}" -get "{短链后缀}"

短链详情
────────────────────────────────────────────────
  后缀：    {短链后缀}
  目标：    {目标长链接}
  短链：    {完整短链地址}
  类型：    永久

5. 查看配额状态

php nurl-key -key:"{su_你的Key}" -stat

配额状态
────────────────────────────────────────────────
  永久短链：{永久短链当前数量} / {永久短链配额上限}
  临时短链：{临时短链当前数量} / {临时短链配额上限}

五、错误处理

错误信息	原因
`缺少密钥`	未指定 `-key`
`缺少目标链接`	`-add` 未指定 `-url`
`网络错误：...`	无法连接到服务
`错误 (invalid_key): 密钥失效或不正确 [HTTP 406]`	Key 无效或过期
`错误 (conflict): 已占用 [HTTP 409]`	自定义后缀冲突
`错误 (quota_exceeded): 已达上限 [HTTP 429]`	配额已满
`错误 (not_found): 该短链不存在 [HTTP 404]`	短码不存在

nurl-key 通过无头 API（X-Headless-Token）通信，支持常驻密钥、一次性密钥和服务密钥三种类型。服务密钥在前端面板 API 中会被拒绝，但在此工具中可正常使用。

声明

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

nurl-key 短链管理

声明

本页目录