安装部署
用 Docker Compose 或从源码构建,自托管 Keygate 许可证服务器,包括 HTTPS 反向代理、管理员账号、数据库备份、版本说明与回滚,以及多实例部署。
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/keygatemake 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,因为客户会在门户和邮件里看到它。
客户端地址
限流和暴力破解锁定都按客户端地址计算。这个地址就是连接的来源地址,除非连接来自 TRUSTED_PROXIES 里列出的代理:这时 Keygate 采用代理在 X-Forwarded-For 或 X-Real-Ip 里报告的地址。不设置时,可信代理是内网地址段(10.x、172.16 到 172.31、192.168.x、fc00::/7)。
只信任会设置或追加 X-Forwarded-For、并覆盖 X-Real-Ip 的 HTTP 代理。Caddy 默认就会这样做。用 nginx 的话,要自己加上:
location / {
proxy_pass http://localhost:9000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}然后填写代理连接 Keygate 时使用的地址:
| 部署方式 | TRUSTED_PROXIES |
|---|---|
| nginx 或 Caddy 和 Keygate 在同一台机器,Keygate 从源码运行 | 127.0.0.1,::1 |
| 代理在宿主机上,Keygate 在 Docker 容器里 | Docker 网络的网关,例如 172.18.0.1 |
| 代理在同一个 Docker 网络的另一个容器里 | 这个网络,例如 172.18.0.0/16 |
| 没有代理,直接对外开放 9000 端口 | none |
不确定是哪个地址?在设置 TRUSTED_PROXIES 之前,Keygate 的请求日志里每个请求的客户端地址,就是代理的地址。
不要把纯 TCP 转发填进去,例如 socat、SSH 隧道或 TCP 模式的负载均衡:它们会把客户端自己填的请求头原样转发,客户端就能决定自己按哪个地址计算。放在 Cloudflare 后面时,所有请求都来自 Cloudflare 的地址,客户会共用一个地址。Cloudflare 的地址段默认不信任,因为 Cloudflare Worker 和 WARP 客户端也能自己填写这些请求头。
管理员账号
所有者账号在第一次打开 Keygate 时的设置页面里创建,见快速开始。如果这时已经设置了 ADMIN_EMAILS,设置页面只接受其中的邮箱。其他管理员可以在后台设置的 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 会等迁移完成后再开始提供服务。单条迁移语句最多运行五分钟;超时的话,这个迁移会被回滚,Keygate 随即停止,并在日志里写明原因。
版本说明
大多数版本只需要拉取新镜像,不用做别的。需要额外步骤的版本,会在发布说明的 Upgrade notes 部分写明。如果你跨了几个版本升级,要把中间每个版本的说明都看一遍。下面列出需要额外步骤的版本。
v0.1.19 新增两个数据库迁移。回滚到 v0.1.18 只需要换回旧镜像,旧版能在新的表结构上运行:
20261030_audit_product给audit_logs加了产品列和索引,执行时会锁住这张表,每百万行约 0.4 到 1.3 秒,其他表不受影响。审计表很大时,可以先在不阻塞读写的情况下建好:ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS product_id TEXT;然后CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_product ON audit_logs(product_id, created_at);- 全额退还当期款项现在会取消 Stripe 订阅;争议败诉会取消订阅并吊销许可证。退还已经结束的周期,或者只能通过客户对应到许可证的退款,不再吊销许可证。详见 取消与退款。
- 受限的 Stripe 密钥请开启 Charges 的读取权限:处理争议败诉需要读取 charge。
- 不由 Stripe 计费、方案也没有试用回退方案的试用,在验证结果和 token 的
grc里宽限天数为 0:每小时的检查本来就在到期日结束它。 - v0.1.19 之前通过管理 API 创建的按席位许可证,数量是 1。方案卖的席位更多时,用
POST /admin/licenses/:id/quantity调高。
v0.1.18 没有数据库迁移,回滚到 v0.1.17 只需要换回旧镜像:
- flag 类型的功能(
value_type为flag,通过管理 API 设置)在验证结果和 token 的ftr里改为 JSON 布尔值,和 bool 类型一致。v0.1.17 签发的 token 在过期前仍是字符串,所以这段时间里应用要两种写法都能处理。 - flag 只有值为
false时才算关闭,1、yes这类旧值都算开启。可以这样查出来:SELECT feature, value FROM entitlements WHERE value_type = 'flag' AND value NOT IN ('true', 'false'); - 更新许可证失败的 Stripe webhook 现在会返回 500,让 Stripe 重新发送。v0.1.17 仍然返回 200,所以新旧版本同时运行的时间要尽量短。
v0.1.17 新增了成员许可证密钥、按席位销售的方案和试用回退方案:
- 启动 v0.1.17 之前,先停掉所有旧版本实例,运行多个实例时也一样。旧版本不认识成员密钥和试用回退方案,两个版本不能同时运行。
- 方案的最大席位数现在包含所有者,表示一个许可证能容纳的人数。升级时,所有最大席位数为 2 及以上的方案都会自动加一,这些许可证的容量保持不变。最大席位数为 1 的方案现在只容纳所有者本人,这类许可证上已有的成员会被暂停,直到你调高方案的最大席位数。如果你用脚本或管理端 API 设置最大席位数,今后要把所有者算进去。0 仍然表示不限。
- 每位成员第一次打开客户门户时(或者管理员在后台查看时),会得到自己的许可证密钥。在那之前,成员可以继续使用许可证密钥。成员用共用密钥激活过的设备,在成员用自己的密钥激活时会转到成员名下。
- 成员的管理员角色已经取消。只有许可证所有者可以管理成员,原来是管理员的成员变成普通成员。
- 等所有实例都运行 v0.1.17 之后,再设置试用回退方案。如果你自定义过 Trial Expired 或 License Expiring 邮件模板,请加上
{{.FallbackPlan}},让客户知道试用结束后会转到哪个方案。
回滚
被新版本迁移过的数据库,旧版本通常也能正常启动。如果发布说明里另有说明,就按说明里的步骤操作,或者恢复升级前做的备份。
从 v0.1.17 回到 v0.1.16 就属于这种情况。Keygate 只会向前执行迁移,所以在启动 v0.1.16 之前,要自己按从新到旧的顺序,执行 v0.1.17 的回退迁移(down migration),从 20261029 到 20261025,并在每个执行成功后从 schema_migrations 里删除它的记录:Keygate 会跳过已记录的迁移,不删的话,以后再升级时这些迁移就不会重新执行。脚本遇到第一个错误就会停止,所以不会删掉没有执行成功的迁移记录。使用自带数据库时:
set -euo pipefail
docker compose stop keygate
for m in 20261029_plan_trial_fallback 20261028_member_keys 20261027_per_seat_quantity \
20261026_license_key_prefix 20261025_seats_include_owner; do
curl -fsSL "https://raw.githubusercontent.com/tabloy/keygate/v0.1.17/db/migrations/$m.down.sql" |
docker compose exec -T postgres psql -U keygate -d keygate -v ON_ERROR_STOP=1
docker compose exec -T postgres psql -U keygate -d keygate -v ON_ERROR_STOP=1 -c \
"DELETE FROM schema_migrations WHERE filename = '$m.up.sql'"
done如果你是从源码构建的,用 psql 对你的数据库执行 v0.1.17 的 db/migrations 里同样的文件。然后把镜像改成 ghcr.io/tabloy/keygate:0.1.16并启动。v0.1.17 新增的内容会丢失:
- 成员自己的密钥失效,成员改回使用许可证密钥。他们激活过的设备仍留在许可证上,但每台设备上的应用都需要重新输入许可证密钥。
- 按席位销售的方案上的许可证会丢失已购席位数。这类方案保存的最大席位数是 1,最大激活数是每席位的设备数,所以回到 v0.1.16 后,这些许可证只能有所有者加一名成员、一个席位的设备数,而 Stripe 仍按购买的席位数收费。
- 试用回退方案被清除,试用结束后会重新直接过期。
- 产品的密钥前缀被删除,新密钥重新以
KG开头。已经用其他前缀签发的密钥照常可用。 - 最大席位数为 3 及以上的方案会减一,回到 v0.1.16 不含所有者的算法。原来是管理员的成员仍然是普通成员。
运行多个实例
多个 Keygate 实例可以放在负载均衡后面,共用一个数据库。所有实例都要设置 REDIS_URL,这样限流才会合并计数;不设置的话,每个实例各算各的,三个实例实际允许的请求量就是配置上限的三倍。提醒邮件这类后台任务通过数据库认领,所以两个实例不会把同一封邮件发两次。
多个实例同时启动时(比如升级之后),由其中一个执行迁移,其余实例等它完成后再启动,最多等十分钟。迁移会在它的数据库连接上持有一把锁,所以如果 PostgreSQL 前面有 PgBouncer 这类连接池,要让 Keygate 使用 session 模式,或者让它直连 PostgreSQL:transaction 模式保不住这把锁。
有些版本不能和旧版本实例同时运行。这些版本的升级说明会写明:在第一个新实例启动前,停掉所有旧实例。版本说明里列出了这些版本。
上线前检查
BASE_URL是你的公网 HTTPS 地址,而且站点在这个地址能正常打开。- 密钥都是随机生成的,已妥善保存,并且包含在备份里。
- 邮件可用:在邮件设置里给自己发一封测试邮件。
- 数据库备份按计划运行,并且你至少实际恢复过一次。
- 如果通过 Stripe 销售,一次测试购买能生成许可证。参见通过 Stripe 销售。
最后更新 2026年10月27日