Tyk 5.15 常用 CLI 命令详解

目标：实测讲清 Tyk Gateway 5.15.1 的 tyk 主命令（start/version/lint/import/bundle build/plugin load）与 Gateway 自带管理 REST API（Control API）的关键端点，覆盖命令参数、真实回显、典型工作流与踩坑记录。文末给出 API 端点实测总表与 FAQ。

一、环境信息

• 实测系统：Ubuntu 22.04.5 LTS（systemd 托管），示例主机名 gw01
• Tyk Gateway：5.15.1（deb 包安装，安装方法见 《Ubuntu 22.04 安装 Tyk 指南》）
• 管理密钥：tyk-gw-2026-secret（tyk.conf 的 secret 值，配置方法见 《Tyk 5.15 配置参数详解》）
• 实测前已预置：Redis 8.10.2（本机）、3 个 API 定义（/tyk-api-test/、/authed/、/demo/）、1 个文件策略 demo-policy-01
• 全文回显均为真实输出；个别环境差异处单独注明

二、tyk 命令行总览

Tyk 5.15.1 的主二进制位于 /opt/tyk-gateway/tyk（deb 安装未放入 PATH，需用绝对路径或自行加软链）。tyk --help 实测输出：

usage: tyk [<flags>] <command> [<args> ...]

Tyk Gateway


Flags:
  -h, --[no-]help     Show context-sensitive help (also try --help-long and
                      --help-man).
      --[no-]version  Show application version.

Commands:
help [<command>...]
    Show help.

start* [<flags>]
    Starts the Tyk Gateway

lint
    Runs a linter on Tyk configuration file

version [<flags>]
    Version and build information

import [<flags>] [<input file>]
    Imports a BluePrint/Swagger/WSDL file

bundle build [<flags>]
    Build a new plugin bundle using a manifest file and its specified files

plugin load [<flags>]
    Load a plugin

开源 5.15.1 的完整命令集就是上述 6 个（start 带 * 表示默认命令）。注意：社区资料中常提到的 tyk init、tyk migrate 子命令在 5.15.1 开源版中不存在（--help 全量输出为准），配置初始化直接编辑 tyk.conf、数据迁移属商业版 Dashboard/MDCB 链路。

版本与构建信息用 version 子命令（实测）：

/opt/tyk-gateway/tyk version

Release version: 5.15.1
Built by:        goreleaser
Build date:      2026-10-02T21:39:25Z

三、tyk start：启动网关

systemd 生产托管用 systemctl start tyk-gateway（单元内部即调用 tyk start）；手工/调试场景直接前台运行。可用参数（tyk start --help 实测）：

      --conf=FILE          load a named configuration file
      --port=PORT          listen on PORT (overrides config file)
      --[no-]debug         enable debug mode
      --[no-]memprofile    generate a memory profile
      --[no-]cpuprofile    generate a cpu profile
      --[no-]blockprofile  generate a block profile
      --[no-]mutexprofile  generate a mutex profile
      --[no-]httpprofile   expose runtime profiling data via HTTP

前台启动实测（--port=8091 覆盖配置端口，避免与已运行的 systemd 实例冲突）：

timeout 6 /opt/tyk-gateway/tyk start --port=8091

启动横幅节选（实测，完整日志较长）：

time="2026-10-20T18:11:21Z" level=info message="Tyk API Gateway 5.15.1" prefix=main
time="2026-10-20T18:11:21Z" level=info message="storage: connected to redis" prefix=main
time="2026-10-20T18:11:21Z" level=info message="Starting Poller" prefix=host-check-mgr
time="2026-10-20T18:11:21Z" level=warning message="The control_api_port should be changed for production" prefix=main
time="2026-10-20T18:11:21Z" level=info message="Initialising Tyk REST API Endpoints" prefix=main
time="2026-10-20T18:11:21Z" level=info message="--> Standard listener (http)" port=":8091" prefix=main
time="2026-10-20T18:11:21Z" level=warning message="Starting HTTP server on:[::]:8091" prefix=main
time="2026-10-20T18:11:21Z" level=info message="[RATELIMIT] DRL with Redis Rate Limiter enabled (using transactions)"
time="2026-10-20T18:11:21Z" level=info message="Initialising distributed rate limiter" prefix=main

读横幅的三个要点：storage: connected to redis 确认存储连通；--> Standard listener (http) port=":8091" 确认监听端口（--port 参数确实覆盖了配置文件）；启动检查器（prefix=checkup）会给出生产建议——实测出现过「control_api_port 应为生产环境修改」「文件描述符 65535 低于建议值 80000」等 warning，属官方加固提示而非故障。

排障参数：--debug 输出逐请求调试日志；--conf 可加载另一份配置做多实例测试（注意 Redis database 需错开，见配置篇 storage.database 一节）。

四、tyk lint：配置检查（⚠️ 实测发现）

按官方设计，tyk lint 对 tyk.conf 做模式校验。但在 5.15.1 deb 包中实测不可用——从任意目录执行均报错：

/opt/tyk-gateway/tyk lint

tyk: error: open cli/linter/schema.json: no such file or directory, try --help

原因：lint 依赖相对路径 cli/linter/schema.json，而该文件未包含在 deb 包内（实测 ls /opt/tyk-gateway/cli/ 不存在）。即使 cd /opt/tyk-gateway 后执行结果相同。变通方案：配置校验用 JSON 语法检查 python3 -m json.tool /opt/tyk-gateway/tyk.conf 代替，语义校验以「改配置 → 重启 → 看 journalctl」闭环完成。

五、tyk import：从 OpenAPI/Swagger 生成 API 定义

import 支持 Swagger 2.0 / API Blueprint / WSDL 输入，--create-api 可直接生成 Tyk API 定义。常用参数（tyk import --help 实测）：

      --[no-]swagger           Use Swagger mode
      --[no-]blueprint         Use BluePrint mode
      --[no-]wsdl              Use WSDL mode
      --[no-]create-api        Creates a new API definition from the blueprint
      --org-id=ORG-ID          assign the API Definition to this org_id
      --upstream-target=URL    set the upstream target for the definition
      --[no-]as-mock           creates the API as a mock based on example fields
      --for-api=PATH           adds blueprint to existing API Definition as version
      --as-version=VERSION     the version number to use when inserting

实测完整工作流（输入为最小 Swagger 文件）：

cd /opt/tyk-gateway
/opt/tyk-gateway/tyk import --swagger --create-api \
  --org-id=default --upstream-target=http://127.0.0.1:9099 \
  /tmp/petstore-mini.json > /opt/tyk-gateway/apps/petstore-api.json

命令把生成的 API 定义 JSON 写到标准输出（实测确认：不会自动落盘到 apps 目录，需手动重定向）。生成后有两处需要修正（均为实测踩坑）：

1. proxy.listen_path 生成值为 /<api_id>/（随机 API ID），需改成业务路径；
2. Swagger 的 info.version 会变成 API 版本键（实测生成 "versions": {"1.0.0": ...}），直接热加载后访问报 {"error": "Version information not found"}——把 version_data 换成标准的 Default 版本结构即可。

修正后热重载并验证（实测）：

curl -s -H 'x-tyk-authorization: tyk-gw-2026-secret' http://127.0.0.1:8080/tyk/reload
# -> {"status":"ok","message":""}
curl -s http://127.0.0.1:8080/petstore/pets
# -> {"path": "/pets", "method": "GET"}

import 适合把既有 Swagger 资产批量转成 Tyk 定义；若上游是 OpenAPI 3.x，官方更推荐原生 Tyk OAS 方式（Gateway 直接识别 OAS 文档）。

六、tyk bundle build：插件打包

为 JSVM 中间件制作分发包（bundle），实测步骤：

mkdir -p /tmp/bundle-demo && cd /tmp/bundle-demo
cat > handler.js <<'EOF'
var testMiddleware = new TykJS.TykMiddleware.NewMiddleware({});

testMiddleware.NewProcessRequest(function(request, session, spec) {
    request.SetHeader("X-Bundle-Demo", "tyk-5-15-1");
    return testMiddleware.ReturnData(request, session);
});
EOF
cat > manifest.json <<'EOF'
{
  "file_list": ["handler.js"],
  "custom_middleware": {
    "driver": "lua",
    "pre": [{"name": "testMiddleware", "path": "handler.js"}]
  }
}
EOF
/opt/tyk-gateway/tyk bundle build -y -o bundle-demo.zip

实测回显：

time="2026-10-20T18:11:34Z" level=info message="Building bundle using 'manifest.json'" prefix=tyk
time="2026-10-20T18:11:34Z" level=warning message="The bundle will be unsigned" prefix=tyk
time="2026-10-20T18:11:34Z" level=info message="Wrote 'bundle-demo.zip' (690 bytes)" prefix=tyk

产物包含 handler.js 与 manifest.json（实测 zipfile 校验）。要点：

• driver 字段必填，JSVM 中间件用 "lua"；实测漏写时构建直接报错 tyk: error: No driver specified, try --help；
• -y/--skip-signing 跳过签名（免密钥，产物带 unsigned warning）；生产分发用 -k <签名密钥> 签名，API 定义侧配置同一密钥校验；
• -o 指定输出文件（默认 bundle.zip），-m 指定 manifest 路径（默认 manifest.json）。

tyk plugin load -f <插件.so> -s <符号名> 用于运行期加载 Go 插件共享库（帮助信息实测见 --help；因 Go 插件必须用与 Gateway 一致的 Go 1.25 工具链编译，本文未实测加载环节）。

七、Gateway 管理 REST API（Control API）关键端点

7.1 鉴权与基础约定

所有 /tyk/* 端点要求请求头 x-tyk-authorization: <tyk.conf 的 secret>，缺失或错误统一返回（实测）：

{"status":"error","message":"Attempted administrative access with invalid or missing key!"}

进程级健康端点 /hello 无需鉴权（实测）：curl http://127.0.0.1:8080/hello → {"status":"pass","version":"5.15.1","description":"Tyk GW"}。

7.2 /tyk/apis：API 定义 CRUD（实测全通过）

单查（GET /tyk/apis/{api_id}）、列表（GET /tyk/apis）、创建（POST /tyk/apis）、修改（PUT /tyk/apis/{api_id}）、删除（DELETE /tyk/apis/{api_id}）实测回显：

POST /tyk/apis         -> {"key":"via-rest-03","status":"ok","action":"added"}
PUT  /tyk/apis/{id}    -> {"key":"via-rest-03","status":"ok","action":"modified"}
DELETE /tyk/apis/{id}  -> {"key":"via-rest-03","status":"ok","action":"deleted"}

创建的 API 定义与文件型定义结构相同（api_id、proxy.listen_path、proxy.target_url 等）。变更后必须触发热重载才生效（下一节），实测创建 /via-api/ 并 reload 后代理正常、删除并 reload 后访问返回 404。

7.3 /tyk/reload：热重载（⚠️ 方法与旧资料相反）

实测 5.15.1 的 reload 接口矩阵：

GET  /tyk/reload        -> {"status":"ok","message":""}
GET  /tyk/reload/group  -> {"status":"ok","message":""}
POST /tyk/reload        -> {"status":"error","message":"Method not supported"}
POST /tyk/reload/group  -> {"status":"error","message":"Method not supported"}

即 5.15.1 用 GET 触发热重载，POST 会被拒绝——这与大量旧版教程/脚本的 POST /tyk/reload/group 相反，自动化脚本迁移时务必核对（实测直接复现了 Method not supported）。热重载会重新加载 app_path 文件与 REST 下发的 API、策略文件；listen_port、storage 等基础参数不在热重载范围。

7.4 /tyk/keys：密钥管理

• 创建（自动 ID）：POST /tyk/keys，返回 JWT 形态密钥与哈希（实测）：

curl -s -X POST -H 'x-tyk-authorization: tyk-gw-2026-secret' -H 'Content-Type: application/json' \
  -d '{"org_id":"default","access_rights":{"demo-auth-02":{"api_id":"demo-auth-02","api_name":"Demo Auth API","versions":["Default"]}}}' \
  http://127.0.0.1:8080/tyk/keys

{"key":"eyJvcmciOiJkZWZhdWx0IiwiaWQiOiJmNmIwZTMyNzg4NWI0MDg3YWEwMTgxOWVlNDdlZDgyMSIsImgiOiJtdXJtdXI2NCJ9","status":"ok","action":"added","key_hash":"5363aa4396956fe0"}

key 是调用方使用的明文令牌（base64 包装 org/id/哈希算法），Redis 中仅存 key_hash（见配置篇 hash_keys 一节）。另一等价端点 POST /tyk/keys/create 行为相同（实测）。

• 创建（引用策略）：body 增加 "apply_policies": ["demo-policy-01"]，实测成功创建并可用（限流压测闭环见配置篇策略组）。

• ⚠️ 自定义密钥 ID 在 5.15.1 不可用（实测）：PUT /tyk/keys/fixed-key-2026 无论 body 是否带 key 字段，统一返回 {"status":"error","message":"Key is not found"}；POST /tyk/keys body 中的 "key": "fixed-key-2026" 也会被忽略（照常生成随机 ID）。在 hash_keys=true 的默认哈希存储下，密钥 ID 一律由网关生成，自定义明文密钥需关闭哈希或走其他方式（未实测）。

• 读取：GET /tyk/keys/{key_id} 返回完整会话对象（rate/quota/access_rights 等，实测）。

• 删除：DELETE /tyk/keys/{key_id} → {"status":"ok","action":"deleted"}（实测）；删除后带该密钥访问返回 403，再 GET 返回 {"status":"error","message":"Key not found"}。

7.5 /tyk/org/keys：组织级密钥

用于设置 org 全局限流/配额（对该 org 全部 API 生效的全局节流）。实测 PUT/GET/DELETE 均正常：

PUT /tyk/org/keys/org-key-2026  -> {"key":"org-key-2026","status":"ok","action":"modified"}
GET /tyk/org/keys/org-key-2026  -> {"rate":100,"per":60,"quota_max":10000,"quota_renewal_rate":3600,"org_id":"default","last_updated":"1792520023"}
DELETE /tyk/org/keys/org-key-2026 -> {"key":"org-key-2026","status":"ok","action":"deleted"}

7.6 /tyk/policies 与 /tyk/cache

• GET /tyk/policies：在 policy_source=file 的开源模式下实测返回 []（文件策略只进内存存储，不经该接口回显）；策略是否加载看启动日志 Policies found (N total) 与密钥创建行为。
• 缓存失效：实测 POST /tyk/cache/{api_id} 返回 Method not supported，正确方法是 DELETE：curl -X DELETE ... /tyk/cache/demo-echo-01 → {"status":"ok","message":"cache invalidated"}。

7.7 /tyk/health 与未挂载端点

• GET /tyk/health?api_id={id}：返回指定 API 的健康指标（须开 health_check 且带 api_id，实测回显见配置篇）。
• 实测发现 /tyk/metrics（Prometheus）、/tyk/liveness、/tyk/ready 在本安装形态下未挂载：无鉴权访问统一被管理鉴权拦截（403），带正确密钥访问则 404。进程存活探针用 /hello 替代；Prometheus 指标在开源链路下需自消费分析队列或引入 Pump（商业组件）。

八、实测记录总表

九、常见问题（FAQ）

Q1：tyk: error: open cli/linter/schema.json 是什么问题？ 5.15.1 deb 包未包含 lint 所需的模式文件（详见第四章），属包内缺件而非配置错误；用 JSON 语法校验替代即可。

Q2：管理请求全部 403？ 核对请求头名 x-tyk-authorization 与 tyk.conf 的 secret 值；若设置过 control_api_port，管理请求须打到该端口（数据端口上这些路径直接 404）。

Q3：照旧教程 POST /tyk/reload/group 报 Method not supported？ 5.15.1 的热重载是 GET（/tyk/reload 或 /tyk/reload/group 均可），POST 全部拒绝（实测矩阵见 7.3）。

Q4：想创建自定义 ID 的密钥被拒？ 5.15.1 + 默认 hash_keys=true 下密钥 ID 由网关自动生成（JWT 形态），PUT /tyk/keys/{id} 实测恒报 Key is not found。把返回的 key 值当作令牌分发给调用方，运维侧用 key_hash/别名管理映射。

Q5：import 生成的 API 访问报 Version information not found？ Swagger 的 info.version 被当作 API 版本键且未设默认版本（实测复现）。把 version_data 改为 {"not_versioned": true, "versions": {"Default": {"name": "Default"}}} 再热重载即可。

Q6：REST 下发的 API 重启后还在吗？ REST API 创建的定义存 Redis，重启不丢；文件型定义（app_path）重启后从文件重读。删除操作（DELETE /tyk/apis/{id}）必须配一次 GET /tyk/reload 才会真正从数据面摘除（实测）。

十、参考链接

1. Gateway 管理 API 参考：https://tyk.io/docs/tyk-gateway-api/
2. tyk 命令行（官方文档）：https://tyk.io/docs/tyk-oss-gateway/cli/
3. Tyk Gateway 5.15 发布说明：https://github.com/TykTechnologies/tyk/releases
4. 站内相关文档：《Tyk 5.15 介绍与选型指南》、《Ubuntu 22.04 安装 Tyk 指南》、《Tyk 5.15 配置参数详解》