Technical Specifications & Architecture
这是一份根据该指南整理的详细规范的 README.md 项目介绍文档：
短链接服务
一个基于 Cloudflare Workers（边缘函数计算）与 Cloudflare KV（分布式键值存储）构建的轻量级、无服务器（Serverless）短链接生成与重定向系统。
本项目完全运行在 Cloudflare 全球边缘节点上，无需服务器、无需数据库运维，自带高颜值、多语言支持的可视化前端界面，并提供 RESTful API 接口，开箱即用。
✨ 核心特性
-
⚡ 极速重定向：借助 Cloudflare 全球边缘网络，毫秒级响应并执行 302 重定向跳转。
-
🌐 多语言界面：内置现代化单页 UI，原生支持 8 种语言（英文、简体中文、繁体中文、日语、韩语、德语、法语、西班牙语）实时切换。
-
🔀 灵活的短码规则：
-
支持自定义短短码（带保留词冲突检测与防重校验）。
-
支持自动生成 6 位随机短码（内置 5 次防碰撞重试机制）。
-
⏳ 数据生命周期管理：短链接默认配置 90 天有效期（
expirationTtl: 7776000秒），到期由 KV 自动清除，避免脏数据堆积。 -
🔒 合规与隐私政策：页面内置法律免责声明与隐私条款弹窗，不收集个人身份信息 (PII)、IP 或 Cookie。
-
💰 完全免费：利用 Cloudflare 免费层额度即可零成本长期稳定运行。
🛠️ 技术架构
-
计算平台：Cloudflare Workers (JavaScript ES Modules)
-
存储引擎：Cloudflare Workers KV
-
前端呈现：HTML5 + 原生 CSS/JS（嵌入 Worker 单文件，零构建依赖）
🚀 部署指南
前置准备
-
一个 Cloudflare 账号（免费注册）。
-
（可选）一个已接入 Cloudflare 解析的自定义短域名（未绑定时可使用官方提供的免费
*.workers.dev域名）。
第一步：创建 KV 命名空间（数据库）
-
登录 Cloudflare 控制台，依次点击 Workers 和 Pages -> KV。
-
点击 “创建命名空间” (Create a namespace)。
-
命名空间名称输入：
SHORT_URL_KV，点击 “添加”。
第二步：创建 Worker 服务
-
在控制台左侧进入 Workers 和 Pages -> 概述，点击 “创建应用程序” (Create application)。
-
选择 “创建 Worker”，将服务命名为
url-shortener，点击 “部署”。
第三步：绑定 KV 命名空间
-
进入
url-shortener服务详情页，切换到 设置 (Settings) 选项卡。 -
找到 变量 (Variables) -> KV 命名空间绑定 (KV Namespace Bindings)，点击 “添加绑定”。
-
配置参数：
-
变量名称：
URL_DB（必须全大写，与代码严格对应） -
KV 命名空间：选择第一步创建的
SHORT_URL_KV
- 点击 “保存并部署”。
第四步：部署核心代码
-
在 Worker 详情页面右上角点击 “编辑代码” (Edit Code)。
-
清空代码编辑器中的默认代码，粘贴完整的
Worker + 前端代码（即指南中的核心脚本）。 -
点击 “部署” (Deploy) 保存发布。
第五步：绑定自定义短域名（可选）
如果需要使用自己的短域名（如 s.example.com）替代默认的 *.workers.dev：
-
进入 Worker 详情页的 设置 (Settings) -> 域名与路由 (Domains & Routes)。
-
点击 “添加” -> 自定义域名 (Custom Domain)。
-
输入你的子域名并保存，Cloudflare 会自动完成 DNS 记录配置与 SSL 证书下发。
📖 API 接口文档
除了通过网页创建短链接，你也可以通过 HTTP API 进行集成：
创建短链接
-
请求方式：
POST -
请求路径：
/api/create -
Content-Type：
application/json
请求体 (Body)
JSON
{
"longUrl": "https://example.com/very/long/path/to/page",
"customCode": "custom" // 可选，不传则系统自动随机生成
}
成功响应 (200 OK)
JSON
{
"shortUrl": "https://s.example.com/custom",
"shortCode": "custom"
}
常见错误响应
| HTTP 状态码 | 错误代码 (error) | 描述说明 |
|---|---|---|
400 Bad Request |
invalid_url |
缺少 URL 或协议头不以 http:// / https:// 开头 |
400 Bad Request |
code_reserved |
自定义短码占用了保留词（如 api, create, privacy, terms） |
409 Conflict |
code_exists |
自定义短码已被占用 |
500 Server Error |
system_busy |
随机生成短码多次碰撞失败 |
🔧 运维与管理
-
手动管理/修改映射：进入 Cloudflare 控制台 -> Workers 和 Pages -> KV -> 进入
SHORT_URL_KV，点击 “查看/添加条目”，可手动创建、查看、修改或强制删除指定短码映射。 -
过期机制：每个短链接均带有
expirationTtl: 7776000属性，90 天后 KV 会自动彻底回收，无需手动清理磁盘与过期键。
📊 Cloudflare 免费配额参考
系统完全运行在 Cloudflare 免费方案中，日常配额如下：
| 资源类别 | 免费额度 | 说明 |
|---|---|---|
| Worker 请求 | 100,000 次 / 天 | 足以承载日常访问重定向 |
| KV 读取 | 100,000 次 / 天 | 每次短链访问读取 1 次 KV |
| KV 写入 | 1,000 次 / 天 | 每天可创建 1,000 个短链接 |
⚖️ 免责与隐私说明
-
按现状提供：本项目为轻量级免维护工具，按现状提供。
-
生命周期限制：短链接存活期固定为 90 天，到期自动物理销毁，商业高要求场景请留意链接时效。
-
隐私合规：服务默认不记录访客 IP、Cookies 及 PII 数据，仅维护短码与原始 URL 的单向映射关系。