安装部署

Keygate 是一个 Go 服务，所有数据都存在 PostgreSQL 里。大多数产品用一台小型云服务器就够了：API、管理后台和客户门户都由同一个进程提供。本页介绍怎样把它部署到你自己掌控的服务器上，并保持稳定运行。如果只是想试用，看快速开始会更快。

环境要求#

• 一台 Linux 服务器或虚拟机，并有一个指向它的公网域名。
• Docker 及 Compose 2.24 或更高版本；如果从源码构建，则需要 Go 1.27 和 Bun。
• PostgreSQL。compose 文件会帮你运行 PostgreSQL 18，也可以使用托管数据库。
• 可选：如果想让 Keygate 托管你应用的发布版本，需要 S3 兼容存储（AWS S3、Cloudflare R2、MinIO）；如果运行多个实例，需要 Redis 或 Valkey。

Docker Compose#

这是推荐的运行方式。把下面两个文件下载到同一个文件夹：

mkdir keygate && cd keygate
curl -O https://raw.githubusercontent.com/tabloy/keygate/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/tabloy/keygate/main/.env.example

编辑 .env。至少要把 JWT_SECRET 和 LICENSE_SIGNING_KEY 设为随机值（可以用 openssl rand -hex 32 生成），并把 BASE_URL 设为用户实际访问的地址，例如 https://licenses.example.com。然后启动：

docker compose up -d

.env 里的所有配置都会传进容器。有几项是在 compose 文件里直接设置的，优先级高于 .env：端口、ENVIRONMENT=production，以及指向内置 PostgreSQL 的数据库地址。要使用自己的数据库，修改 docker-compose.yml 里的 DATABASE_URL，并删除 postgres 服务。

所有配置项见配置参考。

从源码构建#

如果不想用 Docker，可以从源码构建 Keygate。需要 Go 1.27 和 Bun：

git clone https://github.com/tabloy/keygate.git
cd keygate
cp .env.example .env
make build
./bin/keygate

make build 会把服务端构建到 bin/keygate，把管理后台构建到 web/dist。请在仓库目录下启动：它会从启动目录读取 .env、db/migrations 里的数据库迁移和 web/dist 里的管理后台，真实的环境变量优先于 .env。建议用 systemd 或其他进程管理工具来运行，并把这个目录设为工作目录，这样进程崩溃或机器重启后都能自动拉起。

HTTPS 与域名#

Keygate 监听普通 HTTP，默认端口 9000。在它前面放一个反向代理来处理 HTTPS。用 Caddy 的话，下面就是全部配置，证书也不用另外处理：

licenses.example.com {
	reverse_proxy localhost:9000
}

不管用哪种代理，都要把 BASE_URL 设为公网 HTTPS 地址。Keygate 用它生成链接：邮件里的链接、Stripe Checkout 完成后的返回地址、它向 Stripe 注册的 webhook 地址，以及后台发布管理的更新设置里显示的更新 feed 地址。BASE_URL 还指向 localhost 时，更新设置会给出提醒。建议用产品域名下的子域名，例如 licenses.yourapp.com，因为客户会在门户和邮件里看到它。

管理员账号#

所有者账号在第一次打开 Keygate 时的设置页面里创建，见快速开始。其他管理员可以在后台设置的 Team 里邀请，也可以把他们的邮箱写进 ADMIN_EMAILS，这样他们首次登录时就会成为管理员。所有人都用邮件收到的一次性验证码登录，所以在邀请别人之前，先配置好邮件发送。

备份#

除了对象存储里的发布文件，所有状态都保存在 PostgreSQL 中。数据库要定期备份。使用内置数据库时：

docker compose exec postgres pg_dump -U keygate keygate > keygate-backup.sql

下面这些密钥要和备份一起保存，放在安全的地方，并且和服务器分开：

• LICENSE_SIGNING_KEY 用于签名应用校验的离线 token。一旦更换，保存了旧公钥的应用会拒绝所有新 token。
• RELEASE_KEY_ENCRYPTION_KEY 用于加密发布签名密钥、邮件服务商凭据和已存储的许可证密钥。没有它，这些数据就无法解密。
• JWT_SECRET 用于签名登录会话。更换它只会让所有人退出登录。

升级#

先阅读发布说明，做好备份，然后拉取新镜像并重启：

docker compose pull
docker compose up -d

新版本启动时会自动执行数据库迁移。compose 文件跟随的是 latest，这是保持最新版本最省事的方式。如果你想自己决定什么时候升级，就把 latest 换成发布说明里的某个版本号：

image: ghcr.io/tabloy/keygate:x.y.z

回滚

被新版本迁移过的数据库，旧版本通常也能正常启动。如果发布说明里另有说明，就恢复升级前做的备份。

运行多个实例#

多个 Keygate 实例可以放在负载均衡后面，共用一个数据库。所有实例都要设置 REDIS_URL，这样限流才会合并计数；不设置的话，每个实例各算各的，三个实例实际允许的请求量就是配置上限的三倍。提醒邮件这类后台任务通过数据库认领，所以两个实例不会把同一封邮件发两次。

上线前检查#

• BASE_URL 是你的公网 HTTPS 地址，而且站点在这个地址能正常打开。
• 密钥都是随机生成的，已妥善保存，并且包含在备份里。
• 邮件可用：在邮件设置里给自己发一封测试邮件。
• 数据库备份按计划运行，并且你至少实际恢复过一次。
• 如果通过 Stripe 销售，一次测试购买能生成许可证。参见通过 Stripe 销售。