3 步跑通 Kutt 短链接服务从零配置到生产部署的实战避坑指南【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kuttKuttkutt是一个免费现代的 URL 短链接服务一次部署就能拿到完整的短链系统自建域名、链接统计、密码保护、管理后台和 REST API 全都有。它专为自托管设计默认 SQLite 零配置不需要构建步骤。读完这篇你可以把 Kutt 跑在本地、用 API 批量造短链并把它迁到 Postgres/MariaDB 上跑生产。项目速览项说明架构类型Express 单服务Node.jsHandlebars 模板 htmx无独立前端工程输入规格长 URL → 短码短链长度LINK_LENGTH默认 6 位数据库SQLite默认/ Postgres / MySQL / MariaDBRedis 缓存可选核心依赖Node.js 20、Express、Knex、better-sqlite3LicenseMIT它和一堆短链工具的区别就两点一个进程同时提供网页和 API数据库用 Knex 抽象从 SQLite 换到 Postgres 只改环境变量。完整配置项见 .example.env。把 Kutt 跑起来的最小步骤git clone https://gitcode.com/GitHub_Trending/ku/kutt cd kutt npm install npm run migrate npm run dev第一条命令克隆仓库第二条装依赖Node 20。第三条执行 Knex 迁移建表然后启动开发模式——终端会输出 Ready on http://localhost:3000。打开 http://localhost:3000 会提示创建管理员账号之后首页就是这个输入框粘贴长 URL可选设置自定义短码和密码。按场景拆解核心用法场景一团队内部自建短链入口最直接的用途。设SITE_NAME改站名、DEFAULT_DOMAIN填你的域名首页就变成团队自己的短链台。短链支持密码保护和过期时间统计页能看到访问来源 IP 分布geoip-lite 解析。场景二用 REST API 批量造短链脚本里集成时在设置页生成 API Key然后curl -X POST http://localhost:3000/api/v2/links \ -H x-api-key: 你的key -H Content-Type: application/json \ -d {url:https://example.com/very/long/path}返回 JSON 里含data.id和data.url可以直接落库。接口细节在 docs/api/api.js认证头是x-api-key见 server/passport.js。场景三换 Postgres/MariaDB 跑生产仓库给了多套编排按需选docker compose -f docker-compose.postgres.yml up选 Postgres 或 MariaDB 版时要传DB_PASSWORD、DB_NAME、DB_USER等变量连接池用DB_POOL_MIN/DB_POOL_MAX控制默认 0~10。性能与部署调优SQLite单机/低流量如果你要持久化数据 → 把DB_FILENAME指到挂载卷Docker 版默认是/var/lib/kutt/data.sqlite见 docker-compose.yml。Postgres/MariaDB多实例/大流量如果请求变慢 → 调大DB_POOL_MAX如果开 Redis → 设REDIS_ENABLEDtrue缓存和限流都会走它。反代Nginx/Cloudflare如果统计里的用户 IP 全是代理地址 →TRUST_PROXYtrue保持不变裸跑无代理时设成false否则 IP 可被伪造。API 限流如果担心接口被刷 → 设ENABLE_RATE_LIMITtrue有 Redis 走 Redis否则用内存计数。踩坑记录Error: missing env variables: JWT_SECRET现象npm start启动直接退出。原因JWT_SECRET是生产唯一必填项签名 JWT 用。解决在.env里放一个长随机字符串或用JWT_SECRET_FILE/path/to/secret从文件读。401 Unauthorized调用 /api/v2/links现象curl 建短链返回 401。原因缺x-api-key头或 key 不是当前用户的。解决在设置页重新生成 API Key确认请求头拼写是小写x-api-key。注册页提交没反应现象想开放注册但注册入口不存在。原因DISALLOW_REGISTRATION默认true且注册依赖邮箱验证MAIL_ENABLED默认也是false。解决设DISALLOW_REGISTRATIONfalse并配好MAIL_HOST/MAIL_USER等发信参数。换数据库后数据不见了现象SQLite 数据没带过去表是空的。原因DB_CLIENT/DB_FILENAME还是默认值新库等于全新初始化。解决改DB_CLIENT为pg或mysql2配齐DB_HOST/DB_PORT/DB_NAME等再跑npm run migrate建表。写在最后适合想给自己或团队搭短链入口、又不想依赖第三方服务的开发者下一步可以试 OIDC 登录、/custom目录换主题或用docker compose一键起 Postgres 版。参考 docs/api/api.js 和 .example.env 两个文件基本能覆盖所有配置场景。【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kutt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 3 步跑通 Kutt 短链接服务：从零配置到生产部署的实战避坑指南
3 步跑通 Kutt 短链接服务从零配置到生产部署的实战避坑指南【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kuttKuttkutt是一个免费现代的 URL 短链接服务一次部署就能拿到完整的短链系统自建域名、链接统计、密码保护、管理后台和 REST API 全都有。它专为自托管设计默认 SQLite 零配置不需要构建步骤。读完这篇你可以把 Kutt 跑在本地、用 API 批量造短链并把它迁到 Postgres/MariaDB 上跑生产。项目速览项说明架构类型Express 单服务Node.jsHandlebars 模板 htmx无独立前端工程输入规格长 URL → 短码短链长度LINK_LENGTH默认 6 位数据库SQLite默认/ Postgres / MySQL / MariaDBRedis 缓存可选核心依赖Node.js 20、Express、Knex、better-sqlite3LicenseMIT它和一堆短链工具的区别就两点一个进程同时提供网页和 API数据库用 Knex 抽象从 SQLite 换到 Postgres 只改环境变量。完整配置项见 .example.env。把 Kutt 跑起来的最小步骤git clone https://gitcode.com/GitHub_Trending/ku/kutt cd kutt npm install npm run migrate npm run dev第一条命令克隆仓库第二条装依赖Node 20。第三条执行 Knex 迁移建表然后启动开发模式——终端会输出 Ready on http://localhost:3000。打开 http://localhost:3000 会提示创建管理员账号之后首页就是这个输入框粘贴长 URL可选设置自定义短码和密码。按场景拆解核心用法场景一团队内部自建短链入口最直接的用途。设SITE_NAME改站名、DEFAULT_DOMAIN填你的域名首页就变成团队自己的短链台。短链支持密码保护和过期时间统计页能看到访问来源 IP 分布geoip-lite 解析。场景二用 REST API 批量造短链脚本里集成时在设置页生成 API Key然后curl -X POST http://localhost:3000/api/v2/links \ -H x-api-key: 你的key -H Content-Type: application/json \ -d {url:https://example.com/very/long/path}返回 JSON 里含data.id和data.url可以直接落库。接口细节在 docs/api/api.js认证头是x-api-key见 server/passport.js。场景三换 Postgres/MariaDB 跑生产仓库给了多套编排按需选docker compose -f docker-compose.postgres.yml up选 Postgres 或 MariaDB 版时要传DB_PASSWORD、DB_NAME、DB_USER等变量连接池用DB_POOL_MIN/DB_POOL_MAX控制默认 0~10。性能与部署调优SQLite单机/低流量如果你要持久化数据 → 把DB_FILENAME指到挂载卷Docker 版默认是/var/lib/kutt/data.sqlite见 docker-compose.yml。Postgres/MariaDB多实例/大流量如果请求变慢 → 调大DB_POOL_MAX如果开 Redis → 设REDIS_ENABLEDtrue缓存和限流都会走它。反代Nginx/Cloudflare如果统计里的用户 IP 全是代理地址 →TRUST_PROXYtrue保持不变裸跑无代理时设成false否则 IP 可被伪造。API 限流如果担心接口被刷 → 设ENABLE_RATE_LIMITtrue有 Redis 走 Redis否则用内存计数。踩坑记录Error: missing env variables: JWT_SECRET现象npm start启动直接退出。原因JWT_SECRET是生产唯一必填项签名 JWT 用。解决在.env里放一个长随机字符串或用JWT_SECRET_FILE/path/to/secret从文件读。401 Unauthorized调用 /api/v2/links现象curl 建短链返回 401。原因缺x-api-key头或 key 不是当前用户的。解决在设置页重新生成 API Key确认请求头拼写是小写x-api-key。注册页提交没反应现象想开放注册但注册入口不存在。原因DISALLOW_REGISTRATION默认true且注册依赖邮箱验证MAIL_ENABLED默认也是false。解决设DISALLOW_REGISTRATIONfalse并配好MAIL_HOST/MAIL_USER等发信参数。换数据库后数据不见了现象SQLite 数据没带过去表是空的。原因DB_CLIENT/DB_FILENAME还是默认值新库等于全新初始化。解决改DB_CLIENT为pg或mysql2配齐DB_HOST/DB_PORT/DB_NAME等再跑npm run migrate建表。写在最后适合想给自己或团队搭短链入口、又不想依赖第三方服务的开发者下一步可以试 OIDC 登录、/custom目录换主题或用docker compose一键起 Postgres 版。参考 docs/api/api.js 和 .example.env 两个文件基本能覆盖所有配置场景。【免费下载链接】kuttFree Modern URL Shortener.项目地址: https://gitcode.com/GitHub_Trending/ku/kutt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考