Kutt 自建短链接服务指南3 条命令完成部署附生产配置取舍【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kuttKutt 是一个免费、现代的自建短链接服务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 devnpm run migrate负责建库和表迁移一次跑完之后访问localhost:3000页面会引导你创建管理员账号数据默认落在db/data的 SQLite 文件里。跑通之后你会发现本地开发基本零配置。想要容器化部署的话一条命令就够docker compose up它会构建镜像、自动执行迁移并启动服务SQLite 数据和主题目录都挂到了命名卷上。三个典型用法个人链接管理站。默认配置即可用DISALLOW_ANONYMOUS_LINKS和DISALLOW_REGISTRATION默认都是 true也就是只有你自己创建的管理员能登录建链统计完全私有。每条短链可以单独设置自定义短名、密码、描述和过期时间。团队内部服务。关键开关是DISALLOW_REGISTRATIONfalse但注意注册流程依赖邮箱验证必须同时打开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_REGISTRATIONtrue即使打开注册依赖邮箱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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考