10分钟跑通自己的短链接站：kutt 自托管零配置上手

10分钟跑通自己的短链接站：kutt 自托管零配置上手

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

想发给同事的链接有 300 多个字符，往 IM 里一贴折了两行，对方还得全选复制。你要的其实就是一条几个字符的短链，随手转发、点击数还能随时看。kutt 就是一个免费、自托管的现代短链接服务（URL Shortener）：默认用 SQLite 存数据，不用装数据库，仓库里没有构建步骤，clone 下来就能跑。下面这条流程大概 10 分钟能走完，顺手把按场景调参数和最容易踩的坑都讲了。

跑通它：4 条命令出第一条短链

唯一的前置条件是 Node.js 20 以上。打开终端，在你想放代码的目录里执行：

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

npm run migrate负责初始化数据库（跑 knex 迁移脚本），npm run dev带文件监听启动服务。浏览器打开localhost:3000，第一次访问会直接把你带到"创建管理员账户"页面，填好邮箱密码就进入主站。首页粘贴一条长 URL、点发送，6 个字符的短链就出来了；点进链接详情能看到每次点击的统计。

这里省事的原因是：默认数据库就是 SQLite，数据落在db/目录下一个文件里，端口默认 3000，你什么都不用准备。

更省事：Docker 一行启动

不想在机器上装 Node 的话，仓库根目录自带几套 compose 配置。最原味的是 docker-compose.yml，SQLite + 数据卷：

docker compose up

容器启动时会自动先跑迁移再启动应用（见 Dockerfile 最后的 CMD）。SQLite 数据文件被挂到命名卷里，custom/目录也做了挂载——后面要改主题就把文件放这里。想上 Postgres 或 MariaDB，换成 docker-compose.postgres.yml 或 docker-compose.mariadb.yml，按注释补上DB_PASSWORD、DB_NAME等几个必需变量即可。

按场景调：所有参数都是环境变量

配置全靠环境变量，直接传或者写进.env文件都行，完整清单参考 env 配置模板，解析逻辑在 server/env.js——遇到没定义的变量启动会直接报错，拼错一个字母藏不住。

几个大概率要动的：

SITE_NAME=我的短链站 DEFAULT_DOMAIN=link.example.com JWT_SECRET=一串足够长的随机字符串 PORT=3000

• DEFAULT_DOMAIN决定生成的短链长什么样，正式对外开放前一定先设好；
• JWT_SECRET是登录态 token 的签名密钥，生产环境必填；
• DISALLOW_ANONYMOUS_LINKS控制未登录能否建链，默认禁止，保持默认就对了；
• TRUST_PROXY声明应用是否跑在 nginx 或 Cloudflare 后面。没有代理就设false，否则用户可以伪造 IP，统计页的访客 IP 会一片混乱。

这里有个坑，提前说：注册默认是关的（DISALLOW_REGISTRATION=true）。想开放注册，得先把邮件跑通——MAIL_ENABLED加一组MAIL_*变量，因为注册流程依赖验证邮件。内部给团队用，更干净的做法是开 OIDC（OIDC_ENABLED及相关变量），让同事拿现成的 SSO 登录，连注册都省了。

正式环境用npm start启动（自动带上--production），从这一刻起JWT_SECRET不填就起不来，这是故意的，别嫌它烦。

避坑：这四个地方最容易绊一下

• 想换数据库驱动？sqlite3和pg-native这两个 client 默认没装进依赖，得先手动npm install再改DB_CLIENT，否则启动报错很费解。
• 自定义域名：短链可以挂你自己的子域名，CUSTOM_DOMAIN_USE_HTTPS控制生成的链接用不用 https。但注意这些域名的 SSL 证书要你自己签发挂载，应用不负责。
• 接口被刷？ENABLE_RATE_LIMIT=true打开限流，启了 Redis 就用 Redis 计数，否则走内存。生产环境建议顺手把REDIS_ENABLED也开了，缓存和限流一起受益。
• db/目录别乱动，那是 SQLite 的数据本体；用 Docker 的话对应的是那个db_data_sqlite卷。要备份，备份它。

回到开头那个场景：现在你 IM 里那条 300 字的链接已经变成 6 个字符，每次点开都留了记录。下一步值得做的事，按顺序排：绑定自己的域名让短链更像正式出品，开邮件或 OIDC 把注册放给团队，再把 CSS 和页面模板丢进 custom/ 目录换成你自己的皮肤。想深入源码，全部逻辑在 server/ 下，路由、数据模型、迁移脚本分目录放着，结构很直白。

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