Kutt 自建短链接服务指南：3 条命令完成部署，附生产配置取舍

Kutt 自建短链接服务指南：3 条命令完成部署，附生产配置取舍

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

Kutt 是一个免费、现代的自建短链接服务（URL Shortener），集自定义域名、私有访问统计、用户管理与 RESTful API 于一身。如果你受够了把各处链接都丢到第三方平台，自己用一台机器就能把服务跑起来。

Kutt 是什么，谁适合用

Kutt 是用 Node.js 写的、以自托管为前提设计的短链接服务，默认数据库是 SQLite，装完依赖就能直接运行。它适合三类读者：想统一管理文章、文档、社群外发的零散链接的个人用户；需要绑定自己的域名、带用户体系的私有短链服务的团队；以及希望在自己的站点或工具里通过接口生成短链接的开发者。如果你只是想要一个公开的短链服务，官方 SaaS 已经存在，自托管未必更划算。

最小依赖安装与首次启动

唯一的前置条件是 Node.js 20 以上（官方 Docker 镜像基于 node:22）。最短路径就三步，一条命令串起来：

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

npm run migrate负责建库和表迁移，一次跑完；之后访问localhost:3000，页面会引导你创建管理员账号，数据默认落在db/data的 SQLite 文件里。跑通之后你会发现本地开发基本零配置。想要容器化部署的话，一条命令就够：

docker compose up

它会构建镜像、自动执行迁移并启动服务，SQLite 数据和主题目录都挂到了命名卷上。

三个典型用法

个人链接管理站。默认配置即可用：DISALLOW_ANONYMOUS_LINKS和DISALLOW_REGISTRATION默认都是 true，也就是只有你自己创建的管理员能登录建链，统计完全私有。每条短链可以单独设置自定义短名、密码、描述和过期时间。

团队内部服务。关键开关是DISALLOW_REGISTRATION=false，但注意：注册流程依赖邮箱验证，必须同时打开MAIL_ENABLED并配好 SMTP，否则注册依然是禁用状态。如果团队已有统一登录，更稳妥的做法是开启OIDC_ENABLED接入 OpenID Connect，再把邮箱密码登录表单关掉。服务放在 NGINX、Cloudflare 这类反向代理后面时，TRUST_PROXY保持默认 true，让程序从代理头里取真实 IP。

API 集成。Kutt 提供 RESTful API，可在设置页生成 API Key，用密钥调用建链、查询等接口。API 的说明源码放在 docs/api/ 目录，本地执行npm run docs:build即可生成文档，方便对着接口写对接代码。

关键参数怎么取舍：选大选小都有代价

数据库是第一选择。默认better-sqlite3零配置：没有额外数据库进程，个人和小团队规模完全够；代价是数据在单个文件里，多实例部署和并发写入都不合适。换成 Postgres 或 MariaDB，并发和运维能力更强，但要补DB_HOST、DB_USER、DB_PASSWORD等一组连接参数——仓库里的 docker-compose.postgres.yml 已经配好服务编排，填好环境变量就能起。有个隐藏坑：pg-native和sqlite3这两个驱动默认没有安装，DB_CLIENT想用这两个值，得先单独 npm 安装。

LINK_LENGTH 是易读与唯一性的平衡。默认 6 位；改短更好记，但短名碰撞概率上升；改长唯一性更高，分享体验变差。默认字符集已经剔除了o/O/0/i/I/l/1/j这类易混淆字符，想换字符集可以用LINK_CUSTOM_ALPHABET。

Redis 与 JWT_SECRET 是生产必做的两件事。REDIS_ENABLED默认关闭，打开后高负载下性能更好，ENABLE_RATE_LIMIT也能借它做限流，代价是多一个缓存进程要维护。JWT_SECRET是生产环境唯一必填的变量，签名靠它，务必用长随机串，也可以写成文件后用JWT_SECRET_FILE指向；开发态的默认值securekey不能带上生产。各变量的默认值一览在 README.md，实际校验逻辑见 server/env.js。

踩坑与排查：四个常见现象

启动报 JWT_SECRET 缺失。原因：生产模式没设置该变量。解法：配长随机串，或写入文件后用JWT_SECRET_FILE指定路径。

npm run migrate 报驱动或连接错误。原因：DB_CLIENT指定的客户端未安装，或数据库连接参数没填。解法：先装驱动；嫌麻烦就换回默认的better-sqlite3。

用户注册不了，页面显示注册已禁用。原因：默认DISALLOW_REGISTRATION=true；即使打开，注册依赖邮箱，MAIL_ENABLED不置 true 也无效。解法：先配好邮箱，再开注册开关，两步顺序别反。

自定义域名的链接打不开或提示不安全。原因：DEFAULT_DOMAIN与用户访问的域名不一致、DNS 没指过来；走 HTTPS 时还要把CUSTOM_DOMAIN_USE_HTTPS置 true，且证书需要自己签发。

适用边界与下一步

Kutt 适合个人链接管理、团队私有服务和绑定自定义域名的场景；不适合承载公开短链平台级别的高并发流量，也不适合期待零运维、开箱即用的 SaaS 场景。建议的路线是：先用 SQLite 默认配置跑通，再打开邮箱和注册试运行一周，最后按真实的链接量和并发决定要不要迁移 Postgres、开启 Redis。

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