CLI 本地调试

CLI 本地调试用于把 EdgeCron 的 Delivery Attempt 临时交给你电脑上的 CLI 执行。CLI 会从本机请求每个已配置的 Endpoint URL，因此公网 Endpoint、本机服务、Task Run、Event fan-out 和重试逻辑都可以通过这条链路验证，不需要额外的隧道服务。

工作原理

完整链路如下：

1. 在管理后台生成一个 CLI Debug Token。
2. 在本机运行 edgecron-cli login --token ... 或 edgecron-cli listen --token ...。
3. CLI 向 CLI Gateway 登录，创建一个 Debug Session，并保持 WebSocket 长连接。
4. 当 EdgeCron Worker 执行 Task Run 时，会先检查这个 App 或 Endpoint 是否有在线 CLI Session。
5. 如果命中，Worker 通过 Gateway 把完整 Endpoint URL 和请求发给 CLI；CLI 从本机请求这个 URL。
6. HTTP 状态码、响应体和耗时会写回 Delivery Attempt。

如果 CLI 不在线、Debug Token 已撤销、请求没有命中转发范围，或 CLI 超时没有返回结果，EdgeCron 会回到正常的 HTTP 投递路径。

这里的“命中”取决于你生成 Debug Token 时选择的范围：App 范围会拦截该 App 下所有 Endpoint 的 Delivery Attempt；Endpoint 范围只拦截你选中的 Endpoint。Endpoint URL 可以是公网地址，也可以是本机地址，请求由你电脑上的 CLI 进程发起。

实时投递以 Endpoint URL 为准，CLI 的回退端口不会覆盖实时 Endpoint URL：

Core、CLI Gateway 和 CLI 必须一起使用包含 endpoint_url 的 v0.1.2 转发契约。只更新 CLI 二进制、但 Core 或 Gateway 仍发送旧消息时，CLI 无法恢复已经丢失的 host 和 port，只能使用回退地址。

可靠性行为

CLI Gateway 会在推送 WebSocket 请求之前先注册 pending request，因此即使本地服务非常快、CLI 立即返回结果，也不会因为竞态丢失响应。如果 CLI 在投递超时时间内没有返回，Gateway 会记录 CLI timeout，EdgeCron 再回到正常 HTTP 投递路径。

关闭 CLI Session 也是显式语义：如果 Gateway 关闭 session 失败，API 会返回错误，而不是静默报告成功。这样管理后台、Gateway、Redis session 状态和本地 CLI 行为更容易保持一致。

准备工作

开始前请确认：

• 你已经有一个 EdgeCron App，并能登录管理后台。
• 你已经创建至少一个 Endpoint。例如 https://example.com/webhooks/edgecron 会由你的电脑使用这个完整 URL 发起请求。
• http://127.0.0.1:7749/ping 这类本机 URL 可以用于 CLI-only 本地调试；普通云端投递会被 SSRF 防护拦截，不能直接投递到 loopback 或 private 地址。
• 公网 Endpoint URL 必须能从你的电脑访问；本机 Endpoint URL 对应的服务和端口必须已经启动。
• 管理员已经启用 CLI Gateway，并在 EdgeCron Core 中启用 CLI Hook。自托管环境请看本文最后的部署检查项。

1. 下载并安装 CLI

优先从管理后台提供的 CLI 下载入口下载与你系统匹配的安装包。如果当前部署还没有开放下载入口，请使用团队发布的 CLI 二进制包。

当前安装包命名格式是：

edgecron-cli_<version>_<os>_<arch>

例如 v0.1.3 可以发布到 /downloads/edgecron-cli/v0.1.3/：

如果不确定自己的 CPU 架构：

uname -m

Apple Silicon Mac 和 ARM 服务器选 arm64，Intel/AMD x86_64 机器选 amd64。

macOS

下载、校验并安装：

curl -LO https://docs.edgecron.com/downloads/edgecron-cli/v0.1.3/edgecron-cli_0.1.3_darwin_arm64.tar.gz
curl -LO https://docs.edgecron.com/downloads/edgecron-cli/v0.1.3/checksums.txt
grep 'edgecron-cli_0.1.3_darwin_arm64.tar.gz' checksums.txt | shasum -a 256 -c -
tar -xzf edgecron-cli_0.1.3_darwin_arm64.tar.gz
cd edgecron-cli_0.1.3_darwin_arm64
chmod +x edgecron-cli
./edgecron-cli version

如果想在任意目录运行，可以放到系统 PATH 中：

sudo mv edgecron-cli /usr/local/bin/edgecron-cli
edgecron-cli version

macOS 可能会对新下载或未签名的 CLI 显示安全提示。建议先用 checksums.txt 校验文件。第一次运行如果被 Gatekeeper 拦截，可以打开 系统设置 -> 隐私与安全性，允许被拦截的 edgecron-cli，然后再次运行命令。如果公司设备有统一管控，请让 IT 管理员放行，不要绕过公司策略。

Linux

下载与你 CPU 匹配的安装包：

curl -LO https://docs.edgecron.com/downloads/edgecron-cli/v0.1.3/edgecron-cli_0.1.3_linux_amd64.tar.gz
curl -LO https://docs.edgecron.com/downloads/edgecron-cli/v0.1.3/checksums.txt
grep 'edgecron-cli_0.1.3_linux_amd64.tar.gz' checksums.txt | shasum -a 256 -c -
tar -xzf edgecron-cli_0.1.3_linux_amd64.tar.gz
cd edgecron-cli_0.1.3_linux_amd64
chmod +x edgecron-cli
./edgecron-cli version

安装到当前用户可写的 PATH 目录：

mkdir -p ~/.local/bin
mv edgecron-cli ~/.local/bin/edgecron-cli
edgecron-cli version

如果提示找不到 edgecron-cli，把 ~/.local/bin 加到你的 shell PATH。

Windows

下载 edgecron-cli_0.1.3_windows_amd64.zip，解压后运行：

.\edgecron-cli.exe version

在 PowerShell 中校验下载文件：

Get-FileHash .\edgecron-cli_0.1.3_windows_amd64.zip -Algorithm SHA256

把输出结果和 checksums.txt 对比。

Windows SmartScreen 或杀毒软件可能会提示新发布的命令行程序风险，尤其是文件还没有积累下载信誉时。请只从 EdgeCron 文档站或管理后台下载，先校验 SHA-256；只有在你的组织允许时，才选择 更多信息 -> 仍要运行。如果是受管控电脑，请让 IT 将 edgecron-cli.exe 加入允许列表。

从源码构建

源码部署或内部开发环境可以直接构建：

cd cli
make build
./edgecron-cli version

2. 需要时准备本地回调服务

如果测试的是公网 Endpoint URL，可以跳过本节。如果测试 localhost Endpoint，下面是一个不依赖第三方包的 Node.js 示例。它会接收任意路径的请求，打印请求内容，然后返回 200。

// server.mjs
import http from "node:http";

const server = http.createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const body = Buffer.concat(chunks).toString("utf8");

  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  console.log("x-edgecron-request-id:", req.headers["x-edgecron-request-id"]);
  console.log("body:", body);

  res.setHeader("Content-Type", "application/json");
  res.end(JSON.stringify({ ok: true, received_at: new Date().toISOString() }));
});

server.listen(3000, "127.0.0.1", () => {
  console.log("local webhook listening on http://127.0.0.1:3000");
});

启动它：

node server.mjs

先用 curl 自测本地服务：

curl -X POST 'http://127.0.0.1:3000/webhooks/edgecron' \
  -H 'Content-Type: application/json' \
  --data '{"hello":"local"}'

在 EdgeCron 中把 Endpoint 配置为这个完整本机 URL，例如 http://127.0.0.1:3000/webhooks/edgecron。如果真实项目已经有本机回调接口，请使用它实际监听的端口和路径。

3. 在管理后台生成 Debug Token

进入管理后台后：

1. 打开 API Key 管理。
2. 切换到 CLI Debug Tokens。
3. 点击 生成 Debug Token。
4. 选择 App。普通用户通常只会看到自己的 App；超级管理员需要明确选择目标 App。
5. 填写名称，例如 local debug - billing webhook。
6. 选择转发范围。
7. 设置有效期。
8. 创建后立即复制 Token。关闭弹窗后，明文 Token 不会再次显示。

转发范围怎么选

全部 Endpoint 转发到本地 是当前管理后台的默认选项，也是不熟悉 CLI 时最容易跑通的选项。只要 CLI 在线，当前 App 下所有 Endpoint 的投递都会经过你的 CLI，每个 Endpoint 仍使用自己配置的完整 URL。它不需要再选择 Endpoint。

仅指定 Endpoint 转发到本地 是更严格的选项。选择它以后，Endpoint 下拉列表才会变成必填；只有所选 Endpoint 的投递会经过你的 CLI，其他 Endpoint 不受影响。

如果列表里看到历史的 仅测试登录 Token，它只用于验证 CLI 登录链路，不会拦截或转发 Delivery Attempt。

4. 登录 CLI

推荐先保存登录状态：

./edgecron-cli login --token edc_dbg_your_debug_token

成功后会把 Gateway 短期登录态保存到本机配置文件。默认配置目录：

macOS/Linux: ~/.edgecron/config.yaml
Windows: %APPDATA%\edgecron\config.yaml

自托管或私有化部署如果 Gateway 不在默认地址，需要指定 endpoint：

./edgecron-cli login \
  --token edc_dbg_your_debug_token \
  --endpoint https://cli-gateway.your-edgecron.example.com

本地联调时，CLI 不会自动猜测本地 Gateway；默认会连接生产 Gateway：https://cli-gateway.edgecron.com。请显式指定本地 Gateway：

./edgecron-cli --endpoint http://127.0.0.1:7750

如果你直接从源码运行交互式 onboarding：

cd cli
go run main.go --endpoint http://127.0.0.1:7750

也可以使用环境变量：

EDGECRON_ENDPOINT=http://127.0.0.1:7750 go run main.go

也可以不保存登录态，直接开启一次性会话：

./edgecron-cli listen --token edc_dbg_your_debug_token --port 3000

如果希望一次性会话也把登录态保存下来，加 --save：

./edgecron-cli listen --token edc_dbg_your_debug_token --port 3000 --save

直接运行没有子命令的 edgecron-cli 时，交互流程会在需要时读取 Debug Token，然后立即创建在线 CLI Session，不再等待用户按 Enter，也不会等待输入回退端口。配置中的回退地址只用于 replay 和旧版 Gateway 消息。

5. 启动监听

登录后，在本机启动 CLI Session：

./edgecron-cli listen --port 3000 --name billing-local

看到类似输出说明已经连接：

Connected to EdgeCron CLI Gateway
Session: dbg_sess_xxx
Fallback Target: http://127.0.0.1:3000
Waiting for requests...

常用参数：

CLI 发出请求时会额外添加这些请求头：

X-EdgeCron-Debug: true
X-EdgeCron-Session-ID: dbg_sess_xxx
X-EdgeCron-Request-ID: req_xxx

6. 触发一次真实投递

CLI 只接收 EdgeCron Worker 执行的 Delivery Attempt。你可以任选一种方式触发：

• 在管理后台打开 任务，创建一个立即执行的 Task Run，选择 Debug Token 范围内要调试的 Endpoint。
• 在管理后台打开 事件，发布一个能匹配 Endpoint 订阅规则的 Event。
• 创建或等待一个 Schedule 触发。
• 使用公开 API 或 SDK 创建 Task Run、发布 Event。

举例：如果 Endpoint 配置的是 https://www.baidu.com，并且 Debug Token 范围命中了这个 Endpoint 或它所属的 App，那么 Delivery Attempt 会先通过 CLI Gateway 发到 CLI，再由 CLI 从你的电脑请求 https://www.baidu.com/。如果 Endpoint 是 http://127.0.0.1:7749/ping，即使 CLI 回退端口是 3000，也会请求这个完整的本机 URL。如果 Debug Token 没有命中这个 Endpoint，或者 CLI 不在线，EdgeCron 会回到普通云端投递路径；公网 URL 由 Core 直接请求，loopback/private URL 会被 SSRF 防护拒绝。

触发后，CLI 终端会打印请求：

POST /webhooks/edgecron [req_abc123]
← 200 OK 12ms

Endpoint 会收到请求体和 X-EdgeCron-Request-ID。如果返回 2xx，对应 Delivery Attempt 会被标记为成功；如果返回 4xx、5xx 或 CLI 请求失败，会按失败结果写回，并继续遵循 Endpoint 的重试策略。

7. 查看会话和请求记录

在管理后台打开 CLI 调试 页面，可以看到：

• 当前和历史 Debug Session。
• 每个 Session 的状态、回退地址、连接时间、最后心跳和过期时间。
• CLI 请求记录，包括 request ID、Endpoint、状态码、耗时和错误。
• 需要时可以手动关闭 Session。

在 API Key 管理 的 CLI Debug Tokens Tab 中，可以查看 Token 状态、过期时间、尾号和撤销操作。

在 投递记录 中，可以查看最终写回的 Delivery Attempt 结果。

8. 本地重放请求

如果你已经登录过 CLI，可以用 request_id 重放某次请求到本地服务：

./edgecron-cli replay req_abc123 --port 3000

修改请求体后重放：

./edgecron-cli replay req_abc123 \
  --port 3000 \
  --body '{"invoice_id":"inv_123","status":"paid"}'

从文件读取请求体：

./edgecron-cli replay req_abc123 --port 3000 --body-file payload.json

replay 会优先使用当前 CLI 进程缓存；找不到时会向 Gateway 查询请求详情。它只重放到你的本地服务，不会新建 Task Run，也不会修改线上 Delivery Attempt。

排查问题

安全建议

• CLI Debug Token 不是公开 API Key，不能替代 ak_xxx / sk_xxx 调用 /v1 API。它只用于 CLI Gateway 登录和本地调试会话。
• Token 明文只展示一次。不要提交到 Git、CI 日志、截图或工单。
• 调试结束后撤销 Token，并关闭不再使用的 CLI Session。
• App 范围会影响该 App 下所有 Endpoint。多人共用环境时，请使用 Endpoint 范围。
• Endpoint 会从你的电脑收到真实 payload。生产数据联调时，请按团队的数据安全要求处理日志和脱敏。

发布 CLI 下载文件

如果通过文档站托管 CLI 下载文件，先在 cli/ 中构建安装包：

make release VERSION=0.1.3
make verify-release

然后把产物复制到 docs 的 public 目录：

edgecron-docs/public/downloads/edgecron-cli/v0.1.3/

保持这样的目录结构：

downloads/
  edgecron-cli/
    v0.1.3/
      edgecron-cli_0.1.3_darwin_amd64.tar.gz
      edgecron-cli_0.1.3_darwin_arm64.tar.gz
      edgecron-cli_0.1.3_linux_amd64.tar.gz
      edgecron-cli_0.1.3_linux_arm64.tar.gz
      edgecron-cli_0.1.3_windows_amd64.zip
      checksums.txt

public/ 下的文件会作为静态资源提供下载，因此文档站可以直接暴露这样的链接：

https://docs.edgecron.com/downloads/edgecron-cli/v0.1.3/edgecron-cli_0.1.3_darwin_arm64.tar.gz

只要每个安装包没有超过 Cloudflare Pages 的单文件限制，这就是最简单的方案。如果后续安装包变大，或者想使用独立下载域名，可以把同样的目录结构上传到 Cloudflare R2，并绑定自定义域名，例如：

https://downloads.edgecron.com/edgecron-cli/v0.1.3/edgecron-cli_0.1.3_darwin_arm64.tar.gz

生产环境建议使用 R2 自定义域名，不要使用 r2.dev 开发链接，这样可以统一在 Cloudflare 上管理缓存、访问控制和安全规则。

自托管部署检查项

如果你维护的是私有化或自托管 EdgeCron，请确认：

• cli-gateway/config/config.prod.yml 中 public_ws_url 是浏览器和 CLI 都能访问的公网 wss:// 地址。
• cli-gateway 的 auth.allow_dev_fallback 在生产环境为 false。
• cli-gateway 和 edgecron 使用同一个 Redis 实例和相同 Redis DB，才能共享在线 Session 绑定。本地 dev 配置默认都应使用 Redis DB 0。
• edgecron/config/config.prod.yml 中 cli_hook.enabled 已按灰度计划开启。
• edgecron 与 cli-gateway 的 Redis channel 配置一致，默认是 cli:task:push 和 cli:task:result:。
• 管理后台、Gateway、Core 都使用同一套 cli_debug_tokens、cli_sessions、cli_requests 表结构。