前言

平时我们在网上冲浪时，经常会看到像 bit.ly/xxx 或者 tinyurl.com/xxx 这样的短链接。它们能把又长又乱的网址变得简洁美观，不仅在社交媒体上分享时更清爽，还能提供点击统计等附加功能。但对于很多站长或者注重数据隐私的人来说，使用第三方的短链接服务始终有个顾虑：你的数据掌握在别人手里，链接什么时候失效也不受自己控制。

Kutt 就是为了解决这个问题而诞生的。它是一个现代化的开源短链接工具，支持自定义域名、详细的点击数据分析、密码保护链接、API 接口等一系列强大功能。你完全可以把它部署在自己的服务器上，打造一个专属于自己的、数据完全自主的短链接系统。

接下来，我会手把手地带你在云服务器上走一遍完整的部署流程。这篇文章主要面向零基础的新手，我会尽量避开那些晦涩难懂的专业术语，用最直白的方式把每个步骤拆解清楚。

第一步：准备工作

在正式开始操作之前，我们需要先确保手头的工具都齐全了。

(1). 拥有一台云服务器

准备一台具备公网IP的云服务器（推荐使用雨云）

优惠注册地址：https://www.rainyun.com/sn_

使用优惠码：sn

注: 使用优惠码注册后绑定微信可领取5折优惠券

服务器选购步骤：

1. 注册后，在"总览"页面找到"云服务器"入口，进入后点击"购买云服务器"
   ​
   2.根据需求选择合适的配置，建议选择国内的服务器，访问更快，选好后点击立即购买即可
   
   3.选好后进入控制台，使用SSH客户端远程连接服务器即可，SSH客户端建议选FinalShell

(2). 准备好一个域名（非必需，但强烈建议）

虽然你也可以直接用服务器的 IP 地址加端口号来访问 Kutt，但这样做出来的短链接会像 http://你的IP:3000/abc123，看起来不太专业。如果想让你的短链接是 short.你的域名/abc123 这种样式，就需要提前把域名（或者一个二级域名）解析到你的服务器 IP 上。

(3). 安装 Docker 和 Docker Compose

Kutt 的官方文档非常推荐用 Docker 来部署，这也是最简单、最不容易出错的方式。Docker 就像一个轻量级的“集装箱”，能把 Kutt 及其所需要的数据库等环境都打包在一起，互相隔离又不会弄乱你的系统。

打开你的 SSH 终端（比如 Windows 上的 PuTTY 或者 macOS/Linux 自带的终端），连接到你的服务器。然后逐条输入下面的命令：

# 更新系统包列表
sudo apt update

# 安装 Docker
sudo apt install docker.io -y

# 启动 Docker 并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证 Docker 是否安装成功
docker --version

看到输出了 Docker 的版本号，就说明安装成功了。

接下来安装 Docker Compose。它是一个用来定义和运行多个 Docker 容器的工具，对我们这种需要同时跑 Kutt 主程序、数据库、Redis 缓存的场景非常方便。

# 下载 Docker Compose 二进制文件
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 赋予执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version

如果能看到版本号，恭喜你，准备工作就全部完成了。

第二步：获取 Kutt 并规划目录

我们把 Kutt 的代码和相关配置放在一个专门的文件夹里，这样方便管理。

# 创建一个名为 kutt 的目录
mkdir ~/kutt

# 进入这个目录
cd ~/kutt

第三步：编写 docker-compose.yml 文件

这是整个部署过程中最关键的一步。我们需要创建一个配置文件，告诉 Docker 如何下载镜像、如何配置各个服务之间的关系。

这里我们选择一套比较均衡的配置：用 PostgreSQL 作为主数据库（稳定可靠），用 Redis 做缓存（提升访问速度）。这套组合足以应对绝大多数使用场景。

在 ~/kutt 目录下，创建一个名为 docker-compose.yml 的文件：

nano docker-compose.yml

然后把下面这段配置内容复制进去。注意：里面的几处 yourdomain.com 和密码需要改成你自己的。

version: '3.7'

services:
  # Kutt 主服务
  kutt:
    image: kutt/kutt:latest
    container_name: kutt-server
    restart: unless-stopped
    depends_on:
      - postgres
      - redis
    environment:
      # 基础配置
      DEFAULT_DOMAIN: 'yourdomain.com'          # 换成你的域名，非常重要！
      SITE_NAME: 'My Kutt'                      # 你的网站名称
      LINK_LENGTH: 6                             # 短链接后缀长度
      # 数据库配置 (PostgreSQL)
      DB_CLIENT: 'pg'
      DB_HOST: 'postgres'
      DB_PORT: '5432'
      DB_NAME: 'kutt'
      DB_USER: 'kutt_user'
      DB_PASSWORD: '这里换成复杂的数据库密码'   # 设置一个强密码
      # Redis 缓存配置
      REDIS_ENABLED: 'true'
      REDIS_HOST: 'redis'
      REDIS_PORT: '6379'
      # 安全配置：JWT密钥，用于加密用户登录状态，一定要改！
      JWT_SECRET: '这里换成足够长的随机字符串，越乱越好'
      # 邮件配置（暂时可忽略，但注册用户需要）
      # MAIL_ENABLED: 'false'
      # 其他可选配置
      DISALLOW_REGISTRATION: 'false'             # 是否禁止新用户注册，自己用可设true
      DISALLOW_ANONYMOUS_LINKS: 'false'          # 是否禁止匿名创建链接
    ports:
      - '3000:3000'                              # 映射端口，宿主机3000 -> 容器3000
    volumes:
      - './data:/var/lib/kutt'                   # 数据持久化

  # PostgreSQL 数据库
  postgres:
    image: postgres:15-alpine
    container_name: kutt-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: 'kutt_user'
      POSTGRES_PASSWORD: '这里换成复杂的数据库密码' # 与上面DB_PASSWORD保持一致
      POSTGRES_DB: 'kutt'
    volumes:
      - './postgres-data:/var/lib/postgresql/data' # 数据库文件持久化

  # Redis 缓存
  redis:
    image: redis:7-alpine
    container_name: kutt-redis
    restart: unless-stopped
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - './redis-data:/data'                       # Redis数据持久化

volumes:
  postgres-data:
  redis-data:

关于上面配置的几个关键点解释一下：

• DEFAULT_DOMAIN：这是整个配置的“心脏”。一定要填你最终要用来访问 Kutt 的域名（比如 kutt.yourdomain.com），否则生成的短链接会乱套。
• JWT_SECRET：这是一个安全密钥，用来给用户的登录凭证加密。务必改成你自己的、足够长且随机的一串字符，不要用网上的示例，否则会有安全隐患。
• 数据库密码：同样的，DB_PASSWORD 和 POSTGRES_PASSWORD 要一致，并且也要改成复杂密码。
• 端口映射 3000:3000：这表示把容器内部的 3000 端口暴露到服务器的 3000 端口。之后你通过 http://你的服务器IP:3000 就能访问到 Kutt 了。

编辑完确认无误后，按 Ctrl+O 保存文件，再按 Ctrl+X 退出 nano 编辑器。

第四步：启动服务

配置文件写好之后，启动就只是一条命令的事了。

在 ~/kutt 目录下，执行：

sudo docker-compose up -d

-d 参数表示后台运行。你会看到一堆下载镜像和创建容器的日志输出。第一次运行因为要下载 PostgreSQL、Redis 和 Kutt 的镜像，可能需要几分钟时间，耐心等待就好。

运行完之后，可以执行下面命令看看容器是不是都正常运行了：

sudo docker-compose ps

如果看到三个服务的状态都是 Up（正常运行），就说明启动成功了。

第五步：初始化数据库

Kutt 需要创建数据库表结构。虽然我们配置了自动迁移，但保险起见，我们可以手动执行一下。

sudo docker-compose exec kutt npm run migrate

这条命令的意思是：在运行着的 kutt 这个容器里，执行数据库迁移操作。看到输出一堆 done 之类的字样，就说明表创建好了。

第六步：配置 Nginx 反向代理（可选，但强烈推荐）

现在 Kutt 已经跑起来了，但只能通过 http://你的IP:3000 访问。这样做有两个问题：

1. 没有 HTTPS 加密，不安全，也不好看。
2. 每次访问都要带端口号 :3000，很麻烦。

理想的状态是用标准的 80（HTTP）和 443（HTTPS）端口访问，并且配上免费的 SSL 证书。这就需要用到 Nginx 反向代理了。

这个步骤稍微有点复杂，但并不是 Kutt 本身必需的。如果你的技术比较熟练，可以参考网上的 Nginx 配置教程，用 acme.sh 或者 certbot 申请证书，然后把 你的域名:3000 代理到标准的 443 端口。

这里简单给一个 Nginx 配置的参考片段（假设你的域名是 kutt.yourdomain.com）：

server {
    listen 80;
    server_name kutt.yourdomain.com;
    return 301 https://$server_name$request_uri; # HTTP 自动跳转 HTTPS
}

server {
    listen 443 ssl http2;
    server_name kutt.yourdomain.com;

    # SSL 证书路径（需提前申请好）
    ssl_certificate     /etc/nginx/ssl/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000; # 转发到 Kutt 的 Docker 端口
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置好 Nginx 之后，你就可以直接用 https://kutt.yourdomain.com 愉快地访问了。

第七步：注册管理员账号

首次访问你的 Kutt 域名，会看到一个注册页面。输入你的邮箱和密码，点击注册。因为这是第一个账号，Kutt 会自动把它设置为管理员账号。

注册成功后登录进去，你就可以开始创建短链接、查看统计、管理用户了。

最后

到这里，你的专属短链接服务 Kutt 就已经搭建完毕了。

这套流程走下来，你会发现通过 Docker 部署一个复杂的应用，远比想象中要简单。Kutt 本身的功能也足够丰富，无论是自己日常使用缩短链接，还是分享给朋友、小团队内部协作，都能很好地满足需求。如果在搭建的过程中卡在了哪一步，别灰心，多看几遍日志，或者回头检查一下域名和密码的配置，大部分问题都出在这些地方。