Shlink 5.1.8 REST API 与 CLI 命令详解

本文基于 shlinkio/shlink **5.1.8** 实测（REST API 约 10 个端点与 CLI 30+ 命令清单均为 2026-10-30 真机运行取证，回显原样保留）。

ShlinkPHP自托管Docker2026/10/30

Shlink 5.1.8 REST API 与 CLI 命令详解

本文基于 shlinkio/shlink 5.1.8 实测（REST API 约 10 个端点与 CLI 30+ 命令清单均为 2026-10-30 真机运行取证，回显原样保留）。

Shlink 提供两条并行的管理通道：REST API（适合集成与自动化）与 CLI（docker exec <容器> shlink <命令>，适合运维排查）。本文以 REST API 实测为主线，CLI 给出完整命令清单与抽测回显。

一、API 基础：认证与健康检查

所有管理接口位于 /rest/v3/ 前缀下，认证方式为请求头 X-Api-Key。Key 由 CLI 签发（见第四节），无 Key 或 Key 无效一律 401：

$ curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8132/rest/v3/short-urls \
    -H 'Content-Type: application/json' -d '{"longUrl":"https://example.com"}'
401

健康检查不需要认证：

$ curl -s http://localhost:8132/rest/health
{"status":"pass","version":"5.1.8","links":{"about":"https://shlink.io","project":"https://github.com/shlinkio/shlink"}}

二、短链全生命周期（实测）

2.1 创建短链

$ curl -s -X POST http://localhost:8132/rest/v3/short-urls \
    -H 'Content-Type: application/json' -H 'X-Api-Key: <KEY>' \
    -d '{"longUrl":"https://www.quzuo.net/","customSlug":"quzuo","tags":["demo","test"],"title":"Quzuo Home"}'
{
    "shortUrl": "http://surl.localhost:8132/quzuo",
    "shortCode": "quzuo",
    "longUrl": "https://www.quzuo.net/",
    "dateCreated": "2026-10-30T12:58:49+08:00",
    "tags": ["demo", "test"],
    "meta": {"validSince": null, "validUntil": null, "maxVisits": null},
    "domain": null,
    "title": "Quzuo Home",
    "crawlable": false,
    "forwardQuery": true,
    "visitsSummary": {"total": 0, "nonBots": 0, "bots": 0},
    "hasRedirectRules": false
}

实测要点：

  • 不传 title 时 Shlink 会自动抓取目标页面标题（实测对 https://shlink.io 自动填入 Shlink — The URL shortener）；
  • customSlug 冲突时返回 400 类错误，加 "findIfExists": true 可改为复用既有短链；
  • 请求体支持 validSince/validUntil/maxVisits 三种失效元数据，直接进 meta。

2.2 跳转与失效控制

$ curl -s -o /dev/null -w 'HTTP %{http_code} -> %{redirect_url}\n' http://localhost:8132/quzuo
HTTP 302 -> https://www.quzuo.net/

maxVisits 失效实测：创建 maxVisits: 1 的短链后，第 1 次访问 302 正常跳转，第 2 次访问直接 404（访问同时记入 orphan visits，type 为 invalid_short_url）：

visit1: HTTP 302 -> https://shlink.io/
visit2超限: HTTP 404 ->

访问不存在的短码同样是 404（实测 GET /no-such-code → HTTP 404）。

2.3 列表与搜索（注意响应嵌套结构）

5.x 的列表类接口响应是按资源名再包一层的结构，解析时容易踩坑（老版本资料多为顶层 data）：

$ curl -s "http://localhost:8132/rest/v3/short-urls?itemsPerPage=10&searchTerm=shlink" -H 'X-Api-Key: <KEY>'
{"shortUrls":{"data":[ ... ],"pagination":{"currentPage":1,...,"totalItems":3}}}

分页参数 page + itemsPerPage，搜索参数 searchTerm 按长 URL/标题/短码匹配。

2.4 命中统计与标签

短链维度统计：

$ curl -s "http://localhost:8132/rest/v3/short-urls/quzuo/visits" -H 'X-Api-Key: <KEY>'
→ visits.pagination.totalItems: 2   # 两次 curl 跳转各计一次

标签列表：

$ curl -s "http://localhost:8132/rest/v3/tags" -H 'X-Api-Key: <KEY>'
{"tags":{"data":["demo","test"],"pagination":{...}}}

孤儿访问（访问了无效短码、根路径等不对应任何短链的流量）：

$ curl -s "http://localhost:8132/rest/v3/visits/orphan" -H 'X-Api-Key: <KEY>'
{"visits":{"data":[{"referer":"","date":"...","userAgent":"curl/8.18.0",
  "visitLocation":null,"potentialBot":true,"visitedUrl":"http://localhost:8132/DyIhz",
  "redirectUrl":null,"type":"invalid_short_url"}, ...]}}

实测 type 取值含 invalid_short_url（无效短码/超限）、base_url（直接访问根路径）；potentialBot 对 curl 这类 UA 判定为 true。

三、CLI 命令全景（5.1.8 实测清单）

docker exec shlink-5.1.8-app shlink list 输出的完整命令组：

命令组命令
api-keygenerate / initial / list / rename / disable / delete
short-urlcreate / list / resolve / edit / delete / delete-expired / import / manage-rules / visits / visits-delete
taglist / rename / delete
domainlist / redirects / visits
visitorphan / non-orphan / locate / download-db / orphan-delete
integrationintegration:matomo:send-visits

注意：标签只能随短链创建或由 Web/API 创建，CLI 没有 tag:create（实测确认）。

四、CLI 抽测回显

生成与查看 API Key：

$ docker exec shlink-5.1.8-app shlink api-key:generate
 [OK] Generated API key: "062d8542-f251-43da-a5cc-384cff979418"
$ docker exec shlink-5.1.8-app shlink api-key:list
+--------------------------------------+------------+-----------------+-------+
| c3cbbf24-****-****-****-************ | +++        | -               | Admin |
+--------------------------------------+------------+-----------------+-------+

列表显示时 Key 自动脱敏。创建短链（-n 跳过长 URL 可达性检查）：

$ docker exec shlink-5.1.8-app shlink short-url:create -n https://docs.shlink.io
Processed long URL: https://docs.shlink.io
Generated short URL: http://surl.localhost:8132/23tSb

列表与解析：

$ docker exec shlink-5.1.8-app shlink short-url:list
+------------+------------+----------------------------------+------------------------+---------------------------+--------------+
| Short Code | Title      | Short URL                        | Long URL               | Date created              | Visits count |
| 23tSb      |            | http://surl.localhost:8132/23tSb | https://docs.shlink.io | 2026-10-30T12:59:31+08:00 | 0            |
| quzuo      | Quzuo Home | http://surl.localhost:8132/quzuo | https://www.quzuo.net/ | 2026-10-30T12:58:49+08:00 | 2            |
+------------+------------+---------------------------------- Page 1 of 1 ----------+---------------------------+--------------+

$ docker exec shlink-5.1.8-app shlink short-url:resolve quzuo
Long URL: https://www.quzuo.net/

单条短链的访问明细（含地理与 bot 判定列）：

$ docker exec shlink-5.1.8-app shlink short-url:visits quzuo
+---------------------------+---------------+-------------+---------+---------+--------+------+-----------------------------+------------------------+-----------------+
| Date                      | Potential bot | User agent  | Referer | Country | Region | City | Visited URL                 | Redirect URL           | Type            |
| 2026-10-30T12:58:49+08:00 | Potential bot | curl/8.18.0 |         | Unknown | Unknown|Unknown| http://localhost:8132/quzuo | https://www.quzuo.net/ | valid_short_url |

地理列为 Unknown 是因为实验环境未下载 GeoLite2 库，visit:download-db 可补齐（注意事项见 《Shlink 5.1.8 常见问题与进阶实战》）。

五、REST API vs CLI 怎么选

  • 系统集成/批量操作 → REST API（有完整 OpenAPI 描述，各语言 SDK 成熟）；
  • 运维排查/一次性任务 → CLI（docker exec 即用，输出人类可读，过期清理 short-url:delete-expired、地理位置库更新 visit:download-db 只有 CLI 有对应面）；
  • 两者共用同一数据库与鉴权体系，混用无一致性问题。

六、环境前置与系列导航