Svix 1.102.1 常用 CLI 命令与工具详解

目标：讲清 Svix 自托管环境下的两套命令行工具——服务端自带 svix-server CLI（令牌/密钥/迁移/清理/健康检查）与独立 svix CLI v2.9.0（应用/端点/消息 CRUD、投递查询、签名验签），全部命令配实测回显，并完成一次从发消息到验签的端到端演示。实测于 Ubuntu 22.04 + svix-server 1.102.1 + svix-cli 2.9.0。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
svix-server：1.102.1（CLI 二进制随镜像内置，无需单独安装）
svix CLI：2.9.0（独立工具，与 SDK 同版本发布节奏）
服务端点：http://127.0.0.1:8071（本机部署）；示例 JWT 由 SVIX_JWT_SECRET=q1w2e3r4 派生
实测应用/端点：应用 app_3L7Zxp4qhRw1RxdY6I7X25jzIRo（订单中心），端点 ep_3L7ZzBypYypBHXtf07zsAiiVqDi（内网接收服务 http://10.89.56.6:9080/hook，需配置 whitelist_subnets 放行内网网段）
部署前置见《Svix Docker Compose 部署指南》，配置项含义见《Svix 1.102.1 配置参数详解》

二、工具概览

工具	获取方式	定位	典型用途
`svix-server`	随服务端二进制内置，装好即有	服务端管理	生成 JWT、端点签名密钥、跑迁移、清数据、健康检查
`svix`	独立安装（见第三章）	API 客户端	日常管理应用/端点/消息、查投递尝试、验签、本地调试转发

两套工具的分工：svix-server 只做「服务自身」的管理（不连 API，直接读服务端配置或操作数据库）；svix 是纯 API 客户端，连任何 Svix 实例（自托管或 SaaS，用 SVIX_SERVER_URL 区分）。

三、前置条件

3.1 svix-server CLI

随服务端自带，直接验证：

svix-server --version

实测回示：

svix-server 1.102.1

3.2 安装 svix CLI（v2.9.0）

Linux 官方安装途径（仓库 README 实查）：Snap（snap install svix）、AUR（yay -S svix-cli）、deb/rpm 包与预编译二进制（GitHub Releases）。通用性最好的是预编译二进制（musl 静态链接，任何 x86_64/aarch64 Linux 可跑）：

curl -sSL -o svix-cli.tar.xz \
  https://github.com/svix/svix-webhooks/releases/download/v2.9.0/svix-cli-x86_64-unknown-linux-musl.tar.xz
tar xf svix-cli.tar.xz
sudo mv svix-cli-x86_64-unknown-linux-musl/svix /usr/local/bin/
svix version

实测回示：

svix-cli 2.9.0

💡 说明：macOS 用 brew install svix/svix/svix，Windows 用 scoop install svix；Releases 产物清单里还有 svix-cli-installer.sh 一键脚本。历史仓库 github.com/svix/svix-cli 已停止独立发版（最后版本 v0.21.1，2023-09-29），以主仓库 Releases 的 svix-cli-* 产物为准。

3.3 svix CLI 连接自托管服务端

svix CLI 默认连 Svix 云，自托管需两个环境变量：

export SVIX_SERVER_URL=http://127.0.0.1:8071
export SVIX_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3OTI4MDcyNjIsImV4cCI6MjEwODE2NzI2MiwibmJmIjoxNzkyODA3MjYyLCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.ma_HOf_9O5LhV_KQAS4lF9AiMrNCyrzMDWuzOe3Cfcc

SVIX_AUTH_TOKEN 用 svix-server jwt generate 生成（见 4.2）；
也可 svix login 交互式写入配置文件（自托管场景环境变量更直接）；
验证连通：

svix health get

实测回示：无输出、退出码 0（成功即静默）；服务停止时输出连接错误且退出码非 0。

四、svix-server 服务端 CLI 详解

4.1 命令总览

svix-server --help

实测回显（完整）：

Svix webhooks server

Usage: svix-server [OPTIONS] [COMMAND]

Commands:
  jwt                          JWT utilities
  asymmetric-key               Asymmetric Key utilities
  migrate                      Run database migrations and exit
  revert-background-migration  Revert a background migration by id
  wipe
  prune                        Prune messages and their attempts older than a given date
  generate-openapi             Generate OpenAPI JSON specification and exit
  healthcheck                  Health check command
  help                         Print this message or the help of the given subcommand(s)

Options:
      --run-migrations       Run database migrations before starting
      --wait-for <WAIT_FOR>  The time to wait for a successful connection to the database before timing out in seconds
  -h, --help                 Print help
  -V, --version              Print version

4.2 jwt generate：生成 API 访问令牌

最高频命令。JWT 由 SVIX_JWT_SECRET 派生，携带组织身份，服务重启后旧令牌仍有效（除非换密钥）：

svix-server jwt generate

实测回示：

Token (Bearer): eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3OTI4MDcyNjIsImV4cCI6MjEwODE2NzI2MiwibmJmIjoxNzkyODA3MjYyLCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.ma_HOf_9O5LhV_KQAS4lF9AiMrNCyrzMDWuzOe3Cfcc

可选参数 [ORG_ID]：为指定组织生成令牌（默认用配置派生的主组织）。给多租户各开发环境发独立令牌时用。

4.3 asymmetric-key generate：生成 Ed25519 端点密钥

svix-server asymmetric-key generate

实测回示：

Secret key: whsk_/OtWLHIMHgN9z9M9BLw1HYg3Oa8WRI/WjvgDDqREQ7esQ88mcuJHqIo7Snz+8XmqNABpfCgEIocihUpZjclDMQ==
Public key: whpk_rEPPJnLiR6iKO0p8/vF5qjQAaXwoBCKHIoVKWY3JQzE=

whsk_ 私钥留在服务端用于签名；whpk_ 公钥交给接收方验签，可公开分发；
用途：配合 default_signature_type = "ed25519"（配置项）切换非对称签名方案，接收方无法伪造消息。

4.4 migrate / revert-background-migration：数据库迁移

svix-server migrate

migrate 执行全量库表迁移后退出，用于「迁移与运行分离」的部署形态（K8s InitContainer 等）。默认无需手动执行——启动参数 --run-migrations（官方镜像启动脚本默认带）已自动完成。revert-background-migration <id> 回滚指定后台迁移，仅在升级失败时按官方指引使用。

4.5 prune / wipe：数据清理（高危）

svix-server prune --help

实测回显（完整）：

Prune messages and their attempts older than a given date.

The cutoff must be at least 3 months in the past. Records are deleted in batches to avoid long-running transactions.

Usage: svix-server prune [OPTIONS] --older-than <OLDER_THAN>

Options:
      --older-than <OLDER_THAN>
          Cutoff timestamp in RFC 3339 format (e.g. "2024-01-01T00:00:00Z"). All messages created before this time (and their attempts) will be deleted. Must be at least 3 months in the past

      --batch-size <BATCH_SIZE>
          Number of rows to delete per batch. Defaults to 10,000

          [default: 10000]

      --yes-i-know-what-im-doing
          Confirm that you understand this operation is irreversible

  -h, --help
          Print help (see a summary with '-h')

要点：截止时间必须早于 3 个月前；分批删除（默认 1 万行/批）避免长事务；必须带 --yes-i-know-what-im-doing 才执行，不可逆。执行示例（删除 2026-07-01 前的消息）：

svix-server prune --older-than "2026-07-01T00:00:00Z" --yes-i-know-what-im-doing

wipe <ORG_ID> 清空整个组织的全部数据，同样需要 --yes-i-know-what-im-doing，测试环境重置时用。

4.6 generate-openapi：导出 API 规范

svix-server generate-openapi

输出当前版本完整 OpenAPI JSON（重定向到文件留存，用于生成客户端代码或对接网关）。实测输出为数 MB 的规范文档，以 {"openapi":"3.1.0" 类规范头开始，此处不整段照抄。

4.7 healthcheck：依赖连通性检查

svix-server healthcheck http://localhost:8071

实测回示：无输出、退出码 0。它内部请求目标 URL 的健康接口，官方镜像的 healthcheck 即基于此命令。

五、svix CLI 命令详解（API 客户端）

5.1 命令总览

svix --help

实测回显（完整）：

A CLI to interact with the Svix API.

Usage: svix [OPTIONS] <COMMAND>

Commands:
  application              List, create & modify applications
  authentication           Manage authentication tasks such as getting dashboard URLs
  autoconfig-subscription  Create and rotate AutoConfig subscriptions
  completion               Generate the autocompletion script for the specified shell
  connector                List, create & modify connectors
  destination              List, create & modify destinations
  endpoint                 List, create & modify endpoints
  environment              Import or export environments
  event-type               List, create & modify event types
  health                   Check server healthiness
  ingest                   List, create & modify Svix Ingest sources and endpoints
  integration              List integrations by app id
  listen                   Forward webhook requests to a local url
  login                    Interactively configure your Svix API credentials
  message                  List & create messages
  message-attempt          List, lookup & resend message attempts
  open                     Quickly open Svix pages in your browser
  operational-webhook      List, create & modify operational webhook endpoints
  streaming                List, create & modify Svix Stream resources
  seed                     Generate a test application with sample endpoints and event types
  signature                Verifying and signing webhooks with the Svix signature scheme
  show-config              Show the loaded CLI configuration, with all interpolated environment variables
  version                  Get the version of the Svix CLI
  wizard                   Guided setup flows for getting started with Svix
  help                     Print this message or the help of the given subcommand(s)

Options:
      --color <WHEN>  Controls when to use color [default: auto] [possible values: auto, always, never]
  -v, --verbose...    Log more. This option may be repeated up to 3 times
  -h, --help          Print help
  -V, --version       Print version

💡 说明：connector/destination/streaming/ingest 等子命令对应 Svix 商业版特性（高级目的地、事件流等），自托管开源版调用会返回功能不可用；核心可用的资源管理命令是 application/endpoint/message/event-type/message-attempt/signature。

5.2 application：应用管理

svix application list

实测回示：

{
  "data": [
    {
      "name": "订单中心",
      "id": "app_3L7Zxp4qhRw1RxdY6I7X25jzIRo",
      "createdAt": "2026-10-24T02:01:55.490792Z",
      "updatedAt": "2026-10-24T02:01:55.494224Z",
      "metadata": {}
    }
  ],
  "iterator": "app_3L7Zxp4qhRw1RxdY6I7X25jzIRo",
  "prevIterator": "-app_3L7Zxp4qhRw1RxdY6I7X25jzIRo",
  "done": true
}

创建应用（JSON 体作位置参数）：

svix application create '{"name": "用户中心"}'

实测回示：

{
  "name": "用户中心",
  "id": "app_3L7dSRHyINggcb3Iw4G3xoKYZxO",
  "createdAt": "2026-10-24T02:30:39.210838Z",
  "updatedAt": "2026-10-24T02:30:39.214596Z",
  "metadata": {}
}

其余子命令：get <ID>、delete <ID>、upsert <ID>（按 uid 幂等创建/更新）、patch <ID>。

5.3 endpoint：端点管理

svix endpoint list app_3L7Zxp4qhRw1RxdY6I7X25jzIRo

实测回示：

{
  "data": [
    {
      "id": "ep_3L7ZzBypYypBHXtf07zsAiiVqDi",
      "metadata": {},
      "url": "http://10.89.56.6:9080/hook",
      "description": "测试接收端",
      "disabled": false,
      "createdAt": "2026-10-24T02:02:06.384075Z",
      "updatedAt": "2026-10-24T02:02:06.384386Z"
    }
  ],
  "iterator": "ep_3L7ZzBypYypBHXtf07zsAiiVqDi",
  "prevIterator": "-ep_3L7ZzBypYypBHXtf07zsAiiVqDi",
  "done": true
}

创建端点、取签名密钥：

svix endpoint create app_3L7Zxp4qhRw1RxdY6I7X25jzIRo \
  '{"url": "http://10.89.56.6:9080/hook2", "version": 1, "description": "第二接收端"}'

实测回示：

{
  "id": "ep_3L7dSRTQ6uxyJbXSkM4LizX0HKy",
  "metadata": {},
  "url": "http://10.89.56.6:9080/hook2",
  "description": "第二接收端",
  "disabled": false,
  "createdAt": "2026-10-24T02:30:39.238898Z",
  "updatedAt": "2026-10-24T02:30:39.239275Z"
}

svix endpoint get-secret app_3L7Zxp4qhRw1RxdY6I7X25jzIRo ep_3L7ZzBypYypBHXtf07zsAiiVqDi

实测回示：

{
  "key": "whsec_Ni2BOvIXe51CdvsuQFGqLMQjjIB6H33p"
}

rotate-secret <APP_ID> <ID> 轮换签名密钥（可配 --previous-secret-expiration 让新旧密钥并存过渡）。其余高频子命令：replay-missing（重放失败消息）、get-stats（端点统计）、delete。

⚠️ 踩坑实录：get-secret/get 传错应用 ID 会报 Http error (status=404 Not Found) Entity not found——端点属于哪个应用就必须用哪个应用的 ID 查询，跨应用引用一律 404（本次实测中端点建在 A 应用、却拿 B 应用 ID 查密钥，连续 404 排查后才发现是应用 ID 串号）。

5.4 message：消息管理

svix message create app_3L7Zxp4qhRw1RxdY6I7X25jzIRo \
  '{"eventType": "order.shipped", "payload": {"orderId": "SO-2026-1024-003"}}'

实测回示：

{
  "eventType": "order.shipped",
  "payload": {},
  "id": "msg_3L7dSRbkJHfuAuPLozWRnC5eyq5",
  "timestamp": "2026-10-24T02:30:39.253484Z"
}

svix message list app_3L7Zxp4qhRw1RxdY6I7X25jzIRo --limit 2

实测回示：

{
  "data": [
    {
      "eventType": "order.paid",
      "payload": {},
      "id": "msg_3L7acZ1kBgbwYTlQr1d7qr1pK2x",
      "timestamp": "2026-10-24T02:07:19.695806Z"
    },
    {
      "eventType": "order.paid",
      "payload": {},
      "id": "msg_3L7aJ3wNLbjVAzaZZtr44SfgCVe",
      "timestamp": "2026-10-24T02:04:44.507540Z"
    }
  ],
  "iterator": "msg_3L7aJ3wNLbjVAzaZZtr44SfgCVe",
  "prevIterator": "-msg_3L7acZ1kBgbwYTlQr1d7qr1pK2x",
  "done": false
}

⚠️ 实测发现：CLI 的 message create/list/get 输出中 payload 恒为空对象 {}，消息本体 payload 需用 API 查询（GET /api/v1/app/{app}/msg/{id}/ 返回完整 payload，实测 {"amount":8800,"orderId":"SO-2026-1024-002"}）。这是 CLI 2.9.0 的输出特性，不影响投递正确性。

其余子命令：get <APP_ID> <MSG_ID>、expunge-content（抹除消息内容，满足数据合规删除诉求）。

5.5 message-attempt：投递尝试查询与重发

排查「客户说没收到 Webhook」的主力命令：

svix message-attempt list-by-msg app_3L7Zxp4qhRw1RxdY6I7X25jzIRo msg_3L7aJ3wNLbjVAzaZZtr44SfgCVe

实测回示（完整，一条消息三次尝试的完整生命周期）：

{
  "data": [
    {
      "url": "http://10.89.56.6:9080/hook",
      "response": "{}",
      "responseStatusCode": 200,
      "responseDurationMs": 6,
      "status": 0,
      "statusText": "success",
      "triggerType": 0,
      "msgId": "msg_3L7aJ3wNLbjVAzaZZtr44SfgCVe",
      "endpointId": "ep_3L7ZzBypYypBHXtf07zsAiiVqDi",
      "id": "atmpt_3L7b0UrTJWmCUH3pfPrQiuq49e4",
      "timestamp": "2026-10-24T02:10:30.125120Z"
    },
    {
      "url": "http://10.89.56.6:9080/hook",
      "response": "{}",
      "responseStatusCode": 0,
      "responseDurationMs": 0,
      "status": 2,
      "statusText": "fail",
      "triggerType": 0,
      "msgId": "msg_3L7aJ3wNLbjVAzaZZtr44SfgCVe",
      "endpointId": "ep_3L7ZzBypYypBHXtf07zsAiiVqDi",
      "id": "atmpt_3L7aJvAgaGC51Llta4kaSgipfEB",
      "timestamp": "2026-10-24T02:04:51.332157Z"
    },
    {
      "url": "http://10.89.56.6:9080/hook",
      "response": "{}",
      "responseStatusCode": 0,
      "responseDurationMs": 0,
      "status": 2,
      "statusText": "fail",
      "triggerType": 0,
      "msgId": "msg_3L7aJ3wNLbjVAzaZZtr44SfgCVe",
      "endpointId": "ep_3L7ZzBypYypBHXtf07zsAiiVqDi",
      "id": "atmpt_3L7aJ3ycADQCSs6PXV3JzGn2XAh",
      "timestamp": "2026-10-24T02:04:44.511103Z"
    }
  ],
  "iterator": "atmpt_3L7aJ3ycADQCSs6PXV3JzGn2XAh",
  "prevIterator": "-atmpt_3L7b0UrTJWmCUH3pfPrQiuq49e4",
  "done": true
}

读法：responseStatusCode=0 表示连接层失败（没拿到 HTTP 响应）；status 0=success 2=fail；triggerType 0=自动投递，手动重发为其他枚举值。这条消息前两次失败（5 秒间隔重试），第三次重试自动恢复——重试机制实锤。

手动重发：svix message-attempt resend <APP_ID> <MSG_ID> <ENDPOINT_ID>。按端点查：list-by-endpoint；查一条消息投递过哪些目的地：list-attempted-destinations。

5.6 signature：签名生成与验证（离线）

不连服务器，纯本地 HMAC 计算，接收端联调利器：

svix signature sign \
  --secret Ni2BOvIXe51CdvsuQFGqLMQjjIB6H33p \
  --msg-id msg_3L7a0azuko57GzJjVh2NkyWu689 \
  --timestamp 1792807337 \
  '{"orderId": "SO-2026-1024-001", "amount": 19900, "user": "root"}'

实测回示：

v1,NYSWF17VbegeRnqbBF+GEe58oxtdUjcIew83DMQ2En0=

与接收端实际收到的 svix-signature 头逐字符一致，证明自托管服务端签名方案与官方工具完全兼容。

验签（正确签名）：

svix signature verify \
  --secret Ni2BOvIXe51CdvsuQFGqLMQjjIB6H33p \
  --msg-id msg_3L7a0azuko57GzJjVh2NkyWu689 \
  --timestamp 1792807337 \
  --signature "v1,NYSWF17VbegeRnqbBF+GEe58oxtdUjcIew83DMQ2En0=" \
  '{"orderId": "SO-2026-1024-001", "amount": 19900, "user": "root"}'

实测回示：无输出，退出码 0（通过即静默）。错误签名对照实测：

svix signature verify \
  --secret Ni2BOvIXe51CdvsuQFGqLMQjjIB6H33p \
  --msg-id msg_x --timestamp 1792807337 \
  --signature "v1,BOGUS=" '{}'

实测回示：

Error: signature invalid

退出码 1。签名方案的拼接规则（{msg_id}.{timestamp}.{payload} 的 HMAC-SHA256）与各语言 SDK 验签示例见官方文档「Webhook Verification」。

5.7 listen：本地调试转发

svix listen <本地URL> 向 Svix 云申请一个公网临时地址，把外部 Webhook 转发到你本机（ngrok 的免费替代）：

svix listen --help

实测回示（完整）：

Forward webhook requests to a local url

Usage: svix listen [OPTIONS] <URL>

Arguments:
  <URL>  The local URL to forward webhooks to

Options:
      --color <WHEN>              Controls when to use color [default: auto] [possible values: auto, always, never]
  -t, --token <TOKEN>             Connect to an existing Play token instead of creating a new one
      --disable-tls-verification  Disable TLS certificate verification when connecting to the local URL
  -h, --help                      Print help

⚠️ 注意：listen 的转发通道经 Svix 云（play.svix.com）中继，生产数据请勿走此通道；它只用于开发期接收外部系统（Stripe/GitHub 等）的 Webhook 到本机调试。自托管 svix-server 的接收方是「你的下游客户」，与 listen 场景无关。

5.8 其余常用子命令速记

svix event-type list/create/upsert/delete：事件类型字典管理（给消息 eventType 建目录与 Schema）；
svix authentication dashboard：生成终端用户的临时 Dashboard 访问 URL（商业版完整 UI；开源版简化界面可用性有限）；
svix environment import/export：环境配置迁移；
svix show-config：打印 CLI 实际加载的配置（排查 SVIX_SERVER_URL/SVIX_AUTH_TOKEN 是否生效）；
svix completion bash|zsh|fish：生成 shell 补全。

六、端到端实操演练

从零走一遍「CLI 创建资源 → CLI 发消息 → CLI 查投递 → CLI 验签」闭环（环境变量已按 3.3 导出）。第 1 步应用创建沿用 5.2 的演示商店 app_3L7dV6kuOPYeSQVqLdXx7A1otEq（svix application create '{"name": "演示商店"}'，实测回示见 5.2 同型输出）：

# 2. 创建端点
svix endpoint create app_3L7dV6kuOPYeSQVqLdXx7A1otEq \
  '{"url": "http://10.89.56.6:9080/hook", "version": 1}'

实测回示：

{
  "id": "ep_3L7eAuqBVEkK6ARFdPF90pjVexp",
  "metadata": {},
  "url": "http://10.89.56.6:9080/hook",
  "description": "",
  "disabled": false,
  "createdAt": "2026-10-24T02:36:33.132112Z",
  "updatedAt": "2026-10-24T02:36:33.132429Z"
}

# 3. 发送消息
svix message create app_3L7dV6kuOPYeSQVqLdXx7A1otEq \
  '{"eventType": "demo.ping", "payload": {"n": 1}}'

实测回示：

{
  "eventType": "demo.ping",
  "payload": {},
  "id": "msg_3L7eAuwLWziPkdMQ4O3XbnsXqgr",
  "timestamp": "2026-10-24T02:36:33.146016Z"
}

# 4. 查投递尝试（应看到一次 success）
svix message-attempt list-by-msg app_3L7dV6kuOPYeSQVqLdXx7A1otEq msg_3L7eAuwLWziPkdMQ4O3XbnsXqgr

实测回示（节选）：

{
  "data": [
    {
      "url": "http://10.89.56.6:9080/hook",
      "responseStatusCode": 200,
      "responseDurationMs": 4,
      "status": 0,
      "statusText": "success"
    }
  ],
  "done": true
}

# 5. 取端点密钥并离线重算签名（用接收端记录的 webhook-* 头原值）
svix endpoint get-secret app_3L7dV6kuOPYeSQVqLdXx7A1otEq ep_3L7eAuqBVEkK6ARFdPF90pjVexp

实测回示：

{
  "key": "whsec_Osc9BiRJb0y0dyayHK8HeJrN8uaQfPsZ"
}

接收端实收头（本机已开启 whitelabel_headers = true，故前缀为 webhook-）：

H webhook-id: msg_3L7eAuwLWziPkdMQ4O3XbnsXqgr
H webhook-timestamp: 1792809393
H webhook-signature: v1,RIPmhfjmauz0uMncW0xYMeg7a0gGHWOVpZuAViHpVhk=
BODY: {"n":1}

svix signature sign \
  --secret Osc9BiRJb0y0dyayHK8HeJrN8uaQfPsZ \
  --msg-id msg_3L7eAuwLWziPkdMQ4O3XbnsXqgr \
  --timestamp 1792809393 \
  '{"n":1}'

实测回示：

v1,RIPmhfjmauz0uMncW0xYMeg7a0gGHWOVpZuAViHpVhk=

与接收端实收签名头逐字符一致，闭环成立。

⚠️ 踩坑实录：首次重算时用了 {"n": 1}（冒号带空格）得到不同签名——签名对 payload 原始字节敏感，必须用与投递时完全一致的原始 body（空格/键序/换行都会改变结果）。排查签名不符时第一步就是把接收端记录的 body 逐字节复制。

七、注意事项

令牌安全：svix-server jwt generate 的令牌无限期有效（由密钥派生，无独立过期控制），按人员/环境分发不同令牌并定期轮换 SVIX_JWT_SECRET（轮换即全员失效重发）；
CLI 版本对齐：svix CLI 与服务端独立演进，遇到字段不兼容（如自托管版本落后）优先核对两侧版本；本文实测组合为 server 1.102.1 + CLI 2.9.0；
高危命令双确认：svix-server prune/wipe 必须显式 --yes-i-know-what-im-doing，且 prune 截止时间硬性早于 3 个月，防止误删近期数据；
商业版子命令：connector/destination/streaming/ingest 在开源版不可用，报错不代表部署坏了；
CLI 输出 payload 为空（实测特性）：核对消息内容用 API 而非 CLI 的 message list/get。

八、常见问题

Q1：svix application list 报连接错误？

依次检查：SVIX_SERVER_URL 是否指向正确地址（默认连 Svix 云）；SVIX_AUTH_TOKEN 是否为 svix-server jwt generate 的产物（SaaS 令牌在自托管无效）；服务是否存活（curl http://127.0.0.1:8071/api/v1/health/）。用 svix show-config 确认 CLI 实际加载值。

Q2：svix-server jwt generate 报错或缺配置？

该命令读取完整服务端配置（不只 jwt_secret），在无 config.toml 又无环境变量的裸终端执行会报 missing field jwt_secret。解决：在与服务端相同的环境变量上下文执行（compose 部署用 docker compose exec backend svix-server jwt generate）。

Q3：signature verify 显示 Error: signature invalid 但消息确实是我发的？

三个常见原因：--secret 带了 whsec_ 前缀（要去掉）；payload 字符串与服务端发送的不完全一致（空格/键序差异——签名对原始字节敏感，从接收端原样复制 body，见第六章踩坑实录）；--timestamp 用了当前时间而非头里的 svix-timestamp/webhook-timestamp 原值。

Q4：查投递尝试返回 404「Entity not found」，消息明明存在？

两种实测踩过的情形：应用 ID 与消息不匹配（消息挂在哪个应用就得用哪个应用查，见 5.3 踩坑实录）；消息没有任何投递尝试（应用下无端点，或消息尚未调度），list-by-msg 同样 404——先用 message get 确认归属，再确认端点存在。

Q5：prune 执行后磁盘没变小？

prune 删行不回收磁盘，PostgreSQL 的死元组由 autovacuum 回收；数据量大的历史表可再执行 VACUUM FULL（锁表，安排停机窗口）。

九、参考链接

svix-server 命令源码：https://github.com/svix/svix-webhooks/tree/main/server/svix-server/src
svix CLI 仓库：https://github.com/svix/svix-cli
CLI 下载（主仓库 Releases）：https://github.com/svix/svix-webhooks/releases
签名方案文档：https://docs.svix.com/receiving/verifying-payloads/how-manual
站内相关：《Svix 1.102.1 介绍与选型指南》、《Svix Docker Compose 部署指南》、《Svix 1.102.1 配置参数详解》