Kutt 短链服务自托管到快速上线的完整指南【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kuttKutt 是一款免费、现代、可自托管的 URL 短链接服务。一个 Node.js 项目就能把长链接变成短地址点击数据、用户、域名全部掌握在你自己手里。你可以绑定自己的域名、给链接加密码和过期时间还能通过 REST API 批量管理。官方短链服务很难满足团队的全部需求死链接没人管点击数据拿不到使用规则定不了。Kutt 就是为自托管设计的零配置起步、没有构建步骤默认用 SQLite一条命令就能跑起一个私有短链服务。快速上手环境与依赖只需 Node.js 20 及以上版本。默认数据库是 SQLite驱动better-sqlite3已内置在依赖里不用装任何数据库。想要多实例或高并发再换 Postgres 或 MySQL/MariaDB加 Redis 做缓存。获取与加载git clone https://gitcode.com/GitHub_Trending/ku/kutt cd kutt npm install完整步骤见 README数据库连接由 knexfile.js 管理配置全部走环境变量参考 server/env.js。最小验证npm run migrate npm run dev打开 http://localhost:3000 首次启动会引导你创建管理员账号。在首页贴一个长链接生成短链再粘贴短链确认能跳转就算跑通了。核心能力拆解自定义短码与字母表输入是两个环境变量LINK_LENGTH控制短码长度默认 6 位LINK_CUSTOM_ALPHABET控制字符集默认剔除了 o、O、0、i、I、l、1、j避免视觉混淆。创建链接时还可以传id字段指定自定义短码。LINK_LENGTH6 DEFAULT_DOMAINlink.yoursite.com输出就是link.yoursite.com/abc123形式的短链地址。自定义域名绑定输入是你要绑定的域名。处理上管理员页面添加域名后该域名下的短链会优先走自己的地址。输出是CUSTOM_DOMAIN_USE_HTTPS决定是否拼 httpsSSL 证书需要你手动签发。CUSTOM_DOMAIN_USE_HTTPStrue TRUST_PROXYtrue过期与密码保护输入是创建链接时传入的expire_in和password字段API 定义在 docs/api/api.js 里可查。处理上server/cron.js 每 30 秒扫一次库把到期链接批量删除带密码的链接跳转时先经过校验页。输出是过期链接彻底 404密码错误则进不了目标页。expire_in7 days passwordkutt2026点击统计输入是每次短链跳转请求。处理上server/queues/visit.js 解析 User-Agent 得到浏览器和系统用 geoip-lite 反查国家再把 referrer 脱敏入库。输出是每个链接独立的访问统计前端用 Chart.js 出图逻辑在 static/scripts/stats.js。# 每次点击落库浏览器、系统、国家、来源典型应用场景 团队内部分发文档适用条件链接很长且你需要知道它被点了多少次。curl -X POST http://localhost:3000/api/v2/links \ -H x-api-key: 你的key \ -d {url:https://docs.example.com/page}预期效果拿到短链后在统计页查看点击趋势和访客地区分布。 活动页限时投放适用条件短链需要跟着活动周期一起消失。curl -X POST .../api/v2/links -d {url:...,expire_in:7 days}预期效果7 天后链接被定时任务自动清掉活动结束不留死链。 内网入口加密码适用条件目标页面不想被外人直接打开。curl -X POST .../api/v2/links -d {url:...,password:kutt2026}预期效果访问者必须先输对密码猜错看不到任何目标信息。 用自己的域名发短链适用条件短链要对外展示不能挂着默认域名。DEFAULT_DOMAINlink.yoursite.com预期效果所有新短链都是link.yoursite.com/短码对外更可信。性能与部署调优存储加速路径SQLite 零配置最快并发上量后切DB_CLIENTpg或mysql2直接换 docker-compose.postgres.yml 起服务。缓存加速REDIS_ENABLEDtrue启用 ioredis 缓存访问记录进 Bull 队列API 限流也自动从内存切到 Redis。内存降级策略单机低负载就保持 SQLite 单实例关掉 Redis 和邮件数据目录放DB_FILENAME指向的卷即可。批处理建议API 支持limit/skip分页拉取链接管理员用alltrue一次拿全量用户链接做批量治理。多实例注意定时任务只在NODE_APP_INSTANCE0的实例上跑其他实例不要重复执行清理。可视化调试用/api/v2/health做存活探测访问统计页直接看点击图表比翻数据库更快定位问题链接。避坑指南API 创建链接返回 401→ 没带x-api-key或密钥未启用 → 到设置页生成 API Key 并放进请求头。自定义域名的短链没走 https→ 没设CUSTOM_DOMAIN_USE_HTTPS→ 设为 true 并手动给该域名签发 SSL 证书。访客 IP 全是代理地址→TRUST_PROXY设置与拓扑不符 → 前面有 NGINX/Cloudflare 才开 true否则用户能伪造 IP。到期链接在集群里没被删→ 多实例都跑了清理任务或没有实例是 0 号 → 确保有且仅有一个实例NODE_APP_INSTANCE0。注册/验证一直失败→ 注册依赖邮件验证但MAIL_ENABLEDfalse→ 先配好MAIL_HOST等 SMTP 变量再开注册。小结Kutt 短链服务自托管、零配置覆盖自定义域名、过期、密码和点击统计适合需要数据自主权的小团队。下一步就是克隆仓库跑npm run dev验证你的第一条短链。【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kutt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考