Kutt 自建 URL 短链服务完整指南：5 分钟跑通你的短链接系统

Kutt 自建 URL 短链服务完整指南：5 分钟跑通你的短链接系统

【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kutt

Kutt 是一个免费开源的 URL 短链器，帮你把长链接变成短链接。它自托管、默认零配置，不用装数据库就能跑。你还能拿到完整功能：短链管理、点击统计、多用户、自定义域名和 REST API。

它凭什么值得试

一句话：Kutt 让你把短链服务握在自己手里，数据落在自己的服务器上。

它解决什么问题：

• 第三方短链服务随时可能失效或封禁，链接说断就断
• 想在官网、文档里放短链时，用自有域名更稳更专业
• 想看点击数据，而公开服务往往不给细粒度统计

适合谁：

• 想试水自托管的人：默认用 SQLite，一个数据库都不用装
• 开发者：带完整 REST API，脚本和系统里都能调
• 小团队：多用户、管理员面板、权限管理一应俱全

它从一开始就为自托管设计：开箱即零配置，支持 SQLite、Postgres、MySQL 多种数据库，注册、登录、匿名建链都能按需求开关。

5 分钟验证能不能跑通

先跑起来，再看功能。两条路，结果一样：浏览器打开 localhost:3000，能看到短链生成页面。

路线一：npm（已有 Node.js 20+ 的话推荐）

git clone https://gitcode.com/GitHub_Trending/ku/kutt cd kutt npm install npm run migrate npm run dev

• npm install：安装依赖
• npm run migrate：初始化数据库。默认 SQLite，不用任何配置
• npm run dev：以开发模式启动，改动代码会自动重启

首次打开 http://localhost:3000，会提示你创建管理员账号。建好之后，贴一条长链接，就能拿到短链了。

路线二：Docker

装了 Docker 的话，一条命令起完整服务：

cd kutt docker compose up

默认配置用 SQLite，数据存进 db_data_sqlite 卷里，重启容器数据不丢。

核心用法拆解

跑通之后，有四个能力最实用。每个都配一个真实场景。

自定义短链、密码和有效期

场景：你有个很长的发布页链接要对外发，还想控制谁能打开。

怎么用：在首页贴长链接后，勾选两个选项：

• Set custom URL：自己指定短链后缀，比如 s.example.com/report-2026
• Set password：打开链接时要求输密码

还能设到期时间，到点自动失效。之后编辑、删除都在个人链接列表里操作。

私有统计

场景：链接发出去之后，想知道多少人点了、从哪来。

每条链接都有统计页，能看到点击量、来源页面和访客地区（基于 IP 地理位置，见 server/routes/link.routes.js 中的 stats 路由）。数据只属于你自己，不公开。

自定义域名

场景：短链现在显示的是部署服务器地址，又丑又不可信。

Kutt 支持绑自己的域名，比如 s.yoursite.com。配置完成之后，所有短链都走你的域名。注意两点：SSL 证书要自己签发，相关开关在 .example.env 的 CUSTOM_DOMAIN_USE_HTTPS。

REST API

场景：想在脚本或别的系统里自动创建短链。

Kutt 暴露了一组 RESTful API，用 API key 鉴权，覆盖创建、查询、删除链接和看统计。接口定义在 docs/api/，可以据此生成可交互文档。在个人设置页生成 API key，之后请求里带上它就能建链。

怎么让它更好用

以下建议都能直接落地，每条标了适用条件和取舍。

换 Postgres 或 MySQL

适用：生产环境、数据量变大之后。

取舍：SQLite 对单人使用足够，但团队共用或写量上来时，建议切到 Postgres/MySQL。直接用仓库里的 docker-compose.postgres.yml 配置，填好数据库凭证即可。

开 Redis 缓存

适用：短链高频被点击的场景。

取舍：命中跳转是最高频的操作，加一层缓存能明显降低数据库压力。设 REDIS_ENABLED=true 并给出 Redis 地址即可。流量很小可以不开，白占一个服务。

收紧生产配置

适用：任何要对公网开放部署。

• JWT_SECRET 必填，用一段长随机字符串
• 放在 Nginx 等反向代理后面时，把 TRUST_PROXY 设对。设错了访客可以伪造自己的 IP
• 建议开 ENABLE_RATE_LIMIT，限制 API 被刷

换成自己的样子

适用：对外的场合需要品牌感。

把样式、图片、模板放进 custom/ 目录即可覆盖默认样式，不用改代码。放一个同名 styles.css，整体视觉就换掉了。

统一团队登录

适用：企业内部部署。

开启 OIDC 登录（OpenID Connect，一种统一登录协议），配合关闭注册，团队成员直接用公司账号进，不用在 Kutt 里单独管账号。

卡住了看这里

新手最容易踩的四个坑，每个都给原因和解法。

启动报错或页面打不开

原因：没跑 npm run migrate，数据库表还没建。

解法：先执行一次迁移命令再启动。走 Docker 路线的话，镜像启动时会自动迁移，不用管。

生产模式启动失败，提示 JWT_SECRET

原因：npm start 生产模式下 JWT_SECRET 是必填项，它负责签发登录凭证。

解法：在环境变量或 .env 文件里给一段长随机字符串，参考 .example.env。

匿名用户建不了链

原因：默认 DISALLOW_ANONYMOUS_LINKS 为 true，建链需要登录。

解法：两条路。要么开邮件服务（MAIL_ENABLED=true）放开注册；要么给每人发管理员账号，再各自用 API key 建链。

反代之后统计或地区不对

原因：服务器拿到的是代理的 IP，不是访客真实 IP，地区统计自然偏。

解法：TRUST_PROXY 按部署方式设置。有代理设 true；没有代理设 false，否则访客可以伪造 IP。

下一步行动清单

读完按顺序做就行：

• 用两条路线之一跑通本地部署，确认能生成一条短链
• 建好管理员账号，贴一条长链验证跳转正常
• 在设置页生成 API key，用一次接口创建链接
• 定下数据库方案：个人用 SQLite，团队换 Postgres
• 上线前核对三项：JWT_SECRET、TRUST_PROXY、ENABLE_RATE_LIMIT
• （可选）绑定自定义域名，给短链换上自己的域名
• （可选）用 custom/ 目录做主题替换

完整配置项说明在 README.md，环境变量全表看 .example.env，API 定义在 docs/api/，随时可以对照着往下走。

【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kutt