文档目录▾

快速开始

用 Docker Compose 在本机运行 Keygate，调用一次初始化接口，签发第一个许可证密钥，再用 curl 演示激活、校验和释放设备，不需要 Stripe 和邮件服务器。

这一页带你在本机跑起 Keygate，并让一个许可证密钥走完整个生命周期：签发、激活、校验，再释放。整个过程不需要 Stripe，也不需要邮件服务器，这两样以后再加就行。

准备工作

  • Docker，Compose 版本 2.24 或更高。
  • curl 和 openssl，大多数系统都自带。

启动服务器

新建一个文件夹，把 compose 文件和示例配置下载进去：

bash
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

缺少两个密钥时 Keygate 会拒绝启动。分别生成一个随机值，填进 .env 的 JWT_SECRET 和 LICENSE_SIGNING_KEY：

bash
openssl rand -hex 32
openssl rand -hex 32

然后启动：

bash
docker compose up -d

Compose 会同时启动 PostgreSQL 和 Keygate，Keygate 首次启动时会自动建表。健康检查有响应，就说明可以用了：

bash
curl http://localhost:9000/health
{"checks":{"database":"ok"},"status":"ok","version":"x.y.z"}

创建账号

打开 http://localhost:9000。全新安装会显示一个设置页面，填写你的姓名和邮箱、站点名称和第一个产品。邮箱填你自己的；这一页请把产品类型保留为 Desktop，因为后面的激活调用需要支持设备的产品。Keygate 会创建所有者账号、这个产品和一个名为 Pro 的订阅套餐，然后跳转到登录页。

Keygate 没有密码。输入同一个邮箱，Keygate 会发送一次性验证码。目前还没有配置邮件服务器，所以验证码会输出到服务器日志里：

bash
docker compose logs keygate | grep "OTP code"

日志行的 code 字段就是验证码。输入后即可进入管理后台。

bash
curl -X POST http://localhost:9000/api/v1/setup/initialize \
  -H "Content-Type: application/json" \
  -d '{"admin_email":"[email protected]","admin_name":"Your Name",
       "site_name":"My Licenses","product_name":"My App",
       "product_slug":"my-app","product_type":"desktop"}'

签发许可证

进入 Licenses，选择 Issue License。选中设置时创建的产品和 Pro 套餐，随便填一个邮箱地址，然后保存。Keygate 会显示新密钥：

KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789

在正式环境中，客户付款后这一步会自动完成，具体做法见 Stripe 指南。

激活许可证

下面这些调用本该由你的应用发出。这里用 curl 演示，方便你看清实际传输的内容。identifier 用来标识设备，目前随便用一个固定不变的字符串就行。

Activate
curl -X POST http://localhost:9000/api/v1/license/activate \
  -H "Content-Type: application/json" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789",
       "identifier":"my-laptop","label":"My laptop"}'

返回结果表明设备已激活，并附带一个签名过的 token。应用会保存这个 token，之后校验许可证时就不必每次都请求服务器。

json
{
  "success": true,
  "data": {
    "status": "activated",
    "license_id": "4f0c6c1e-2a7b-4d4e-9a55-0d3b7e1f2c11",
    "token": "eyJsaWQiOiI0ZjBj...J9.5jW2kC0..."
  }
}

应用启动时会校验许可证。这个接口还会返回套餐、套餐包含的功能，以及一个新的 token：

Verify
curl -X POST http://localhost:9000/api/v1/license/verify \
  -H "Content-Type: application/json" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789","identifier":"my-laptop"}'

用户换了新电脑时，旧电脑要把占用的名额释放出来：

Deactivate
curl -X POST http://localhost:9000/api/v1/license/deactivate \
  -H "Content-Type: application/json" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789","identifier":"my-laptop"}'

下一步

  1. 把 Keygate 安装到服务器上，配好正式域名和 HTTPS。
  2. 选择授权模式，并配置你的套餐。
  3. 在应用中加入许可证校验，包括离线使用的情况。
  4. 接入 Stripe，让用户付款后自动生成许可证。

最后更新 2026年10月4日