Kutt 自建 URL 短链服务完整指南5 分钟跑通你的短链接系统【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kuttKutt 是一个免费开源的 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 devnpm 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-2026Set 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_ENABLEDtrue 并给出 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_ENABLEDtrue放开注册要么给每人发管理员账号再各自用 API key 建链。反代之后统计或地区不对原因服务器拿到的是代理的 IP不是访客真实 IP地区统计自然偏。解法TRUST_PROXY 按部署方式设置。有代理设 true没有代理设 false否则访客可以伪造 IP。下一步行动清单读完按顺序做就行用两条路线之一跑通本地部署确认能生成一条短链建好管理员账号贴一条长链验证跳转正常在设置页生成 API key用一次接口创建链接定下数据库方案个人用 SQLite团队换 Postgres上线前核对三项JWT_SECRET、TRUST_PROXY、ENABLE_RATE_LIMIT可选绑定自定义域名给短链换上自己的域名可选用 custom/ 目录做主题替换完整配置项说明在 README.md环境变量全表看 .example.envAPI 定义在 docs/api/随时可以对照着往下走。【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kutt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
