wyi.cc 短链服务对接文档

基础URL: https://wyi.cc
版本: v1.2.0 | 更新: 2026-08-15
部署: Cloudflare Workers + D1
维护: Xianyan 团队
关联: 闲言账号体系（tools.wktyl.com）

职责：通用 URL 短链生成、跳转、统计、二维码、管理后台、自定义短码。已集成 Browser Rendering 网页截图与内容抓取能力。

1. 通用约定

• 公共接口（创建无需登录），管理需要登录
• 频率限制：60/60s（创建）/ 200/60s（跳转）/ 60/60s（二维码）
• 短链格式：https://wyi.cc/{code}（code 长度 2-8 位，支持自定义）
• 跳转类型：301（永久）/ 302（临时，默认）/ meta refresh / JS 跳转（可选）

2. 接口清单

2.1 创建 / 查询 / 删除

• POST /api/shortener/create — 创建短链（自动生成或自定义短码）
• GET /api/shortener/{code} — 查询元数据
• DELETE /api/shortener/{code} — 删除（创建者或 admin）
• POST /api/shortener/batch — 批量创建（≤50）

2.2 跳转（核心）

• GET /{code} — 主入口，跳转到目标 URL
• 永久跳转返回 301，临时跳转返回 302

2.3 统计 / 分析

• GET /api/shortener/{code}/stats — 点击次数、来源分布、设备分布、时间趋势
• GET /api/shortener/myList — 我的短链列表（需登录）

2.4 二维码

• GET /api/qr/{code} — 生成二维码（PNG）
• GET /api/qr/{code}?size=300 — 自定义尺寸

2.5 网页预览（Browser Rendering）

• GET /api/preview/screenshot?url=... — 网页截图 PNG
• GET /api/preview/meta?url=... — 抓取 title / description / OG 图

2.6 限流 / 排队

• 创建短链前会经过全局限流（3 req/s）+ 排队
• 详细看 SERVER_DEPLOYMENT_GUIDE §排队机制

3. 短链数据模型

{
  "code": "abc12",
  "target_url": "https://...",
  "created_at": 1777156407,
  "expires_at": 1779748407,
  "type": "301|302",
  "creator_id": null,           // null 表示匿名创建
  "click_count": 1234,
  "title": "网页标题",          // 自动抓取
  "description": "...",
  "og_image": "https://...",
  "is_active": true,
  "tags": ["doc"]
}

4. 核心示例

4.1 创建短链

POST /api/shortener/create
Content-Type: application/json

{ "url": "https://example.com/article/123", "custom_code": "blog1" }

# 响应
{ "code":1, "data": { "short_url": "https://wyi.cc/blog1", "code": "blog1" } }

4.2 获取预览

GET /api/preview/meta?url=https://example.com
# 响应
{ "code":1, "data": { "title": "...", "description": "...", "og_image": "..." } }

5. 设计要点

• D1 主存 + KV 缓存：D1 存元数据，KV 缓存高频跳转
• Browser Rendering 即时抓取：创建短链时异步触发，预填 title/description
• 排队限流：防滥用，D1 写入排队 + 算法限流
• 自定义短码：2-8 位，支持字母数字（避开歧义字符 0/o/1/l）

6. 关联文档

• 部署文档（Workers + D1）
• 管理后台（短链管理）