API 文档

短网址服务提供 RESTful 风格的 HTTP 接口，支持单条生成、批量生成、短链跳转与统计查询。

选哪种接入方式

方式	接口	鉴权	限流口径	适用
匿名（PHP）	`POST /api.php` `POST /batch.php`	无（可选 `csrf`）	按客户端 IP：单条 20 次/分钟；批量 100 次/分钟（cost = URL 条数）	临时试用、轻量脚本
API 密钥（Go）	`POST /public/api/short-urls` `POST /public/api/short-urls/batch`	`X-API-Key: dwz_xxx`	按密钥配额（管理台「API 密钥」里可设置 `rate_limit` 次/分钟）	生产集成、需要更高配额与用量统计

建议：正式集成请使用 API 密钥 + /public/api/*。密钥在管理台「API 密钥」页创建（明文仅创建时展示一次），支持权限范围、到期时间与用量统计。

概述

所有生成接口均为 application/x-www-form-urlencoded 的 POST-only 接口。GET 或其他方法返回 HTTP 405 和 Allow: POST 头。
成功响应默认返回 JSON（Content-Type: application/json; charset=utf-8）。
短链 URL 由服务端配置 $public_base_url 决定，格式为 {base_url}/{short_code}。
部署在子目录时，所有路径自动适配相对 URL。

单条生成：POST api.php

请求参数

参数	必填	说明
`url`	是	目标网址。仅接受 http/https，最长 2048 字节，不可含控制字符或 URL 凭据
`custom`	否	自定义短码，6–8 位 `[a-z0-5]`。留空则自动生成
`expire`	否	有效天数：`0`(永久) / `1` / `7` / `30` / `365`，默认 `0`
`password`	否	访问密码。设置后访客打开短链需先输入密码解锁（解锁状态通过 HMAC Cookie 记忆 30 天）
`domain`	否	指定域名池中的域名 ID。仅登录会员生效，匿名传入会被忽略并使用默认域名
`format`	否	设为 `txt` 时返回纯文本短链（成功，仅短链本身）或错误文本（失败，HTTP 状态码仍为非 200）

curl 示例

curl -X POST https://1.xk7.cn/api.php \
  -d "url=https://example.com/long-page" \
  -d "custom=mylink" \
  -d "expire=30"

成功响应 (HTTP 200)

{
  "code": "mylink",
  "msg": "success",
  "result": 1,
  "short_url": "https://1.xk7.cn/mylink",
  "state": "created"
}

state 取值：

值	含义
`created`	新建短链
`existing`	相同目标 URL 已存在，返回已有短码
`renewed`	已有短链已过期，续期后返回

批量生成：POST batch.php

请求参数

参数	必填	说明
`urls`	是	换行分隔的 URL 列表。最多 100 行，原始 body 最长 210000 字节

注意：批量接口需要会员登录（浏览器 Cookie 会话），匿名调用返回 401（result 10015）。不支持 custom 和 expire 参数，所有短链均使用随机短码且永久有效。

curl 示例

# 需先在浏览器登录会员（携带会话 Cookie），匿名调用返回 401
curl -X POST https://1.xk7.cn/batch.php \
  --data-urlencode "urls=https://example.com/a
https://example.com/b
https://example.com/c"

成功响应 (HTTP 200)

返回 JSON 数组，每个元素独立表示成功或失败：

[
  {
    "url": "https://example.com/a",
    "code": "abc123",
    "short_url": "https://1.xk7.cn/abc123",
    "msg": "success",
    "result": 1
  },
  {
    "url": "http://127.0.0.1/",
    "code": null,
    "short_url": "",
    "msg": "url host not allowed",
    "result": 10004
  }
]

请求级错误（空列表、超 100 条、body 过大、限流、方法错误）返回单个 JSON 对象而非数组，HTTP 状态码非 200。

方式二：API 密钥调用 POST /public/api/short-urls

使用管理台创建的 API 密钥调用，走 Go 后端，配额与用量可在后台按密钥查看。

鉴权

Header	说明
`X-API-Key: dwz_xxxxxxxx`	推荐。管理台「API 密钥」页创建，明文仅创建时展示一次
`Authorization: Bearer dwz_xxxxxxxx`	备选，与 `X-API-Key` 等价

请求参数（JSON body）

参数	必填	说明
`url`	是	目标网址，仅接受 http/https
`custom`	否	自定义短码，6–8 位 `[a-z0-5]`
`expire_days`	否	数字天数（与 PHP 版 `expire` 的枚举语义不同），`0` 表示永久
`domain_id`	否	域名池中的域名 ID，不传则用默认域名
`password`	否	访问密码

curl 示例

curl -X POST https://1.xk7.cn/public/api/short-urls \
  -H "X-API-Key: dwz_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/long-page","custom":"mylink","expire_days":30}'

成功响应 (HTTP 200)

{
  "code": 0,
  "msg": "success",
  "data": {
    "uid": "mylink",
    "short_url": "https://1.xk7.cn/mylink",
    "long_url": "https://example.com/long-page",
    "expire_at": "2026-10-12T00:00:00Z",
    "created_at": "2026-09-12T02:00:00Z"
  }
}

批量：POST /public/api/short-urls/batch

请求体 {"urls":["https://a.com","https://b.com"],"domain_id":1}（1–100 条）。响应含成功列表与 error_items（携带输入下标与原因）：

{
  "code": 0,
  "msg": "success",
  "data": {
    "results": [ { "index": 0, "uid": "abc123", "short_url": "https://1.xk7.cn/abc123" } ],
    "error_items": [ { "index": 1, "message": "url host not allowed" } ]
  }
}

错误码对照

HTTP	含义	处理建议
401	缺少或无法识别的 API 密钥	检查 `X-API-Key` 是否完整、是否已吊销
403	密钥已过期或无该操作权限	在管理台续期或调整密钥权限
429	超出该密钥的配额	按 `Retry-After` 退避，或提高密钥 `rate_limit`
400	参数校验失败（URL 非法、短码格式错等）	读取 `msg`；批量场景按 `error_items[].index` 定位行号
500	服务内部错误	稍后重试；持续失败请查看后端日志

短链跳转：GET /{code}

通过 Web 服务器重写规则，/{6-8位短码} 映射到 do.php?uid={code}。

HTTP 状态	条件
302	短码有效且未过期，重定向到目标 URL，同时点击计数 +1
404	短码格式无效或不存在
410	短链已过期，或目标 URL 未通过安全校验
500	数据库查询异常

密码保护短链会先返回解锁页（HTTP 200），输入正确密码后才 302 跳转；密码错误返回 200 并展示错误提示。

所有跳转响应携带缓存与索引控制头：

Cache-Control: no-store, private, max-age=0
Pragma: no-cache
Expires: 0
Referrer-Policy: no-referrer
X-Robots-Tag: noindex, nofollow

说明：短码是 302 跳板而非落地页，因此响应带 X-Robots-Tag: noindex，且不会出现在 sitemap.xml 中。

统计页：GET stats.php

私有统计页面，需通过请求头传递 Token 认证：

Header	说明
`X-Stats-Token: <token>`	主要认证方式
`Authorization: Bearer <token>`	备选认证方式

安全机制：当 $stats_enabled = false 或 $stats_token 为空时，stats.php 对所有请求返回 404，绝不泄露统计功能的存在。Token 比较使用 hash_equals() 防止时序攻击。

页面展示内容：

短链总数
累计点击总数
点击量 Top 10
最近创建的 20 条短链

安全响应头：

Cache-Control: no-store
X-Robots-Tag: noindex, nofollow
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer

HTTP 状态码与业务错误码

HTTP	result	含义
200	1	成功
400	10001	URL 或 URL 列表为空
400	10002	URL 过长、格式/协议/端口无效、含控制字符或凭据
400	10004	目标主机不允许（私有/保留地址/DNS 解析失败）
405	10010	请求方法不允许（仅接受 POST）
409	10007	自定义短码已被其他 URL 占用
409	10013	该 URL 已有短链，不能改用其他自定义短码
413	10011	批量请求 body 超过 210000 字节
422	10006	自定义短码格式不合法
422	10008	有效期不在允许值集合内
422	10012	批量 URL 超过 100 条
429	10005	触发速率限制，响应含 `Retry-After: 60`
500	10003	数据库写入/续期失败
500	10009	自动短码碰撞重试耗尽（12 次）
503	10000	数据库不可用

错误响应 JSON 格式：

{"code": 0, "msg": "rate limit exceeded", "result": 10005}

速率限制

接口	限制	窗口	计费
api.php	20 次	60 秒	每次请求 cost = 1
batch.php	100 次	60 秒	cost = URL 条数

基于客户端 IP 的文件锁滑动窗口计数器。
仅当 REMOTE_ADDR 匹配 $trusted_proxies 配置时才信任 X-Forwarded-For 头。
限流目录不可写时请求直接失败（fail-closed）。

SSRF 防护

在创建和跳转两个阶段均执行目标 URL 安全校验：

仅接受 http / https 协议
拒绝含 URL 凭据（user:pass@host）的地址
拒绝控制字符、非法端口
拒绝 localhost、*.local 主机名
DNS 解析后拒绝所有私有/保留 IPv4/IPv6 地址
DNS 解析失败直接拒绝

建议：SSRF 校验为应用层防护，建议同时在主机/容器层面配置出站防火墙规则作为纵深防御。

配置项

变量	默认值	说明
`$public_base_url`	`'https://s.example.com'`	API 响应中 short_url 的基础地址
`$trusted_proxies`	`array()`	允许信任 X-Forwarded-For 的上游 IP/CIDR 列表
`$rate_limit_dir`	`__DIR__.'/logs/ratelimit'`	限流计数器文件存储目录
`$stats_enabled`	`false`	是否启用统计页
`$stats_token`	`''`	统计页认证 Token（启用时必须非空）