rs-short 3.3.1 命令与 HTTP 端点详解

rs-short 3.3.1 命令面形态适配详解：无 CLI 子命令与 API Key 的设计取舍、8 个 HTTP 端点与状态码语义全表、curl 建链(验证码回路)/跳转/治理三连实测、psql 找回 admin key 与治理 SQL、备份恢复、日志审计命令与四组件命令面对比。

rs-shortrs-short短链接Docker自托管2026/11/02

rs-short 3.3.1 命令与 HTTP 端点详解

形态适配说明（篇首必读）：批次篇型原为《常用 CLI 命令与工具详解》，但 rs-short 3.3.1 没有任何 CLI 子命令——单二进制启动后只读当前目录的 config.toml/lists.toml 并监听 HTTP，无参数解析、无管理命令、无 API Key 体系。因此本篇按实际形态改写为"运行方式 + HTTP 端点命令面 + 数据库工具"三合一详解，篇型序号不变。全部命令实测于 Docker Compose + PostgreSQL 环境（取证：/opt/data/quzuo/tmp/rs-short/evidence.md）。

一、二进制运行方式（等价"启动命令"）

形态命令说明
Docker（官方推荐容器路径）docker compose up -d --build产物镜像内 CMD /run_dir/rs-short，postgres feature
源码 SQLitecargo run --release默认 feature；README 注明 "don't use in production"（库锁）
源码 PostgreSQLcargo run --release --no-default-features --features postgres与官方 Dockerfile 一致
源码 MySQLcargo run --release --no-default-features --features mysqldatabase_path 用 mysql://
systemd 裸机见官方 wiki《Integration with nginx / systemd》WorkingDirectory 必须含两份配置文件

无参可传：./rs-short --help 不会打印帮助，而是照常启动服务（实测行为）。配置全部走文件。

二、HTTP 端点全景（源码 routes/handlers 实测核对）

#方法+路径功能凭据成功码实测
1GET /首页表单 + 下发验证码（写会话 Cookie）无200✅
2POST /创建短链（表单 url_to/url_from/captcha）会话验证码303 → Location: /<short>/admin/<key>?created=true✅
3GET /<short>跳转（clicks+1，RAM 可疑监视）无303 → 目标 URL；已标记钓鱼 410；不存在 404✅
4GET /<short>/<key>管理页兼容路由admin key303 → #5✅
5GET /<short>/admin/<key>管理页（短链/目标/Click count/删除链接）admin key200✅
6GET /<short>/delete/<key>删除短链admin key200；已标记钓鱼则 401✅
7GET /<short>/phishing/<phishing_password>标记钓鱼（软删+反诈页）服务端密码200✅
8GET /assets/*主题/Logo 静态资源无200✅

其余路径由 default_handler 统一 404。

状态码语义表（error_handlers.rs 实测核对）

码场景（全部实测触发过）
400验证码错误 / 会话过期(>30min) / url_to·url_from 非法 / 协议不在白名单
401phishing_password 或 admin key 错误 / 删除已标记链接
403命中 urls/names 黑名单 / 同名链接已存在 / 自链接（instance_hostname 无端口时）
404短链不存在
410访问已被标记钓鱼的短链（反诈教育页）
500DB 池/查询内部错误

三、端点命令面实测（curl）

3.1 建链（含验证码回路）

curl -s -c jar.txt http://127.0.0.1:8164/ -o home.html   # 取 Cookie+验证码 PNG
# 识别 home.html 内 base64 PNG 的 6 字符后：
curl -s -b jar.txt -w "%{http_code} %{redirect_url}\n" -X POST http://127.0.0.1:8164/ \
  --data-urlencode "url_to=https://quzuo.net/" \
  --data-urlencode "url_from=quzuo-doc" \
  --data-urlencode "captcha=kjarxp"
# 303 http://127.0.0.1:8164/quzuo-doc/admin/OxdoBGNVko4NDmnhY1O3z9nagSL-QuNH?created=true

细节（实测）：url_from 留空则自动生成 8 字符 base64url 随机短名；自定义名 ≤50 字符、禁 . 与 URL 保留字符（模板 pattern + 源码 RE_URL_FROM 双重校验）；验证码 30 分钟有效且提交成功后仍复用（失败重试不必重新识别）；url_to 协议白名单含 http/https/ftp/gopher/gemini/magnet/ipfs/mailto/matrix/irc/news/ssh/webcal/feed 等 20+ 种（实测 ftp:// 建链成功）。

3.2 跳转与统计

curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://127.0.0.1:8164/quzuo-doc
# 303 https://quzuo.net/          （每访问一次 clicks +1，实测 26 连击后 clicks=27）
curl -s http://127.0.0.1:8164/quzuo-doc/admin/OxdoBGNVko4NDmnhY1O3z9nagSL-QuNH | grep -o 'Click count: [0-9]*'
# Click count: 27

3.3 治理三连

PASS=$(cat phishing_password.txt)
# 标记钓鱼 → 后续访问变 410 反诈页；用户删除通道变 401
curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8164/phish-demo/phishing/$PASS"   # 200
curl -s -o /dev/null -w "%{http_code}\n"  http://127.0.0.1:8164/phish-demo                    # 410
# 正常删除
curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8164/<short>/delete/<key>"         # 200

3.4 负向用例速查

# 缩短 bit.ly → 403 + 文案「Please do not chain shortened links…」
# 重复建同名 → 403；错验证码 → 400；不存在短链 → 404；错误 admin key → 401

四、数据管理（psql / sqlite3 工具面）

rs-short 无管理命令，运维兜底全靠直连数据库。表结构单表 links：id, url_from, url_to, key(bytea), time, clicks, phishing（无 IP/UA，隐私属实）。

4.1 日常查询（PostgreSQL，实测）

docker exec -it rs-short-3.3.1-db psql -U rsshort -d rs_short

SELECT url_from, url_to, clicks, phishing, time FROM links ORDER BY id;
--  quzuo-doc    | https://quzuo.net/            | 27 | 0 | 2026-11-01 21:33:21
--  phish-demo   | https://example.org/          |  1 | 1 | 2026-11-01 21:34:00
--  verbose-test | https://news.ycombinator.com/ |  0 | 0 | 2026-11-01 21:37:30

4.2 找回丢失的 admin key（实用命令，实测）

key 列存 24 随机字节，URL 中呈现为 base64url-nopad——等价转换一行拿到管理链接：

K=$(docker exec rs-short-3.3.1-db psql -U rsshort -d rs_short -t -A \
    -c "SELECT encode(key,'hex') FROM links WHERE url_from='quzuo-doc';")
python3 -c "import base64; print(base64.urlsafe_b64encode(bytes.fromhex('$K')).decode().rstrip('='))"
# OxdoBGNVko4NDmnhY1O3z9nagSL-QuNH  ← 与建链时 303 返回完全一致（实测验证）

4.3 治理与修复操作

UPDATE links SET phishing = 0 WHERE url_from='phish-demo';  -- 撤销误标（410→恢复跳转）
UPDATE links SET clicks = 0  WHERE url_from='quzuo-doc';    -- 重置计数
DELETE FROM links WHERE url_from='verbose-test';            -- 强删（含已标记钓鱼的）
SELECT url_from, clicks FROM links WHERE clicks > 100 ORDER BY clicks DESC;  -- 热点巡查

SQLite 形态同理：sqlite3 ./db/db.sqlite 'SELECT ...'（key 列为 BLOB，hex(key) 后走同一 base64url 转换）。

4.4 备份与恢复

docker exec rs-short-3.3.1-db pg_dump -U rsshort rs_short > rsshort-$(date +%F).sql
# 恢复：cat 备份 | docker exec -i rs-short-3.3.1-db psql -U rsshort -d rs_short

五、日志运维命令

docker logs -f rs-short-3.3.1-app                 # 实时治理流（verbose_console=true 时每条建链四行）
docker logs rs-short-3.3.1-app 2>&1 | grep -A4 'New link created'   # 建链审计
docker logs rs-short-3.3.1-app 2>&1 | grep -A5 'suspicious activity' # 分布式钓鱼告警（≥25 去重IP/12h）
docker logs rs-short-3.3.1-app 2>&1 | grep 'FATAL: Missing translation'  # 名单命中审计（见 C1 §3.3 缺陷）

README 官方姿势：把 403 日志喂给 fail2ban，对滥用 IP 做时段封禁。

六、与其他短链命令面对比

能力rs-short 3.3.1KuttShlinkChhoto URL
CLI 管理命令❌ 无❌✅ shlink CLI❌
REST API + Key❌ 无（刻意：反自动化）✅✅✅ 简单
建链方式仅表单+验证码API/UIAPI/UI/CLIAPI/UI
治理动作URL 端点（phishing/delete）UIUI/CLIUI
数据兜底直连 DB直连 DB直连 DB直连 DB

结论：rs-short 的"命令面"哲学是一切走 URL、拒绝机器批量建链——适合公开反滥用场景，不适合自动化流水线；后者请选 Shlink/Kutt（互链见选型篇）。

七、互链

rs-short 3.3.1 命令与 HTTP 端点详解 - Quzuo