企业官网建设流程全解析

3 步跑通 Kutt 短链接服务：从零配置到生产部署的实战避坑指南

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

Kutt（kutt）是一个免费现代的 URL 短链接服务，一次部署就能拿到完整的短链系统：自建域名、链接统计、密码保护、管理后台和 REST API 全都有。它专为自托管设计，默认 SQLite 零配置，不需要构建步骤。读完这篇，你可以把 Kutt 跑在本地、用 API 批量造短链，并把它迁到 Postgres/MariaDB 上跑生产。

项目速览

它和一堆短链工具的区别就两点：一个进程同时提供网页和 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_ENABLED=true，缓存和限流都会走它。
• 反代（Nginx/Cloudflare）：如果统计里的用户 IP 全是代理地址 →TRUST_PROXY=true保持不变；裸跑无代理时设成false，否则 IP 可被伪造。
• API 限流：如果担心接口被刷 → 设ENABLE_RATE_LIMIT=true，有 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_REGISTRATION=false，并配好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