远程调试

CycBox 通过一个名为 cycbox-edge 的轻量无界面代理程序实现远程调试。您在能够物理访问目标设备的机器上运行 cycbox-edge（即边缘机器——例如紧邻 Modbus 传感器的树莓派，或实验室里的工作站），然后从您自己的笔记本电脑上使用 CycBox UI 连接它。UI 的使用体验与本地模式完全一致——只不过引擎、编解码器、Lua 脚本和仪表盘运行在边缘机器上，而非本地。

适用场景：

设备位于其他地点（实验室、车间、客户现场），您无法亲临现场。
设备连接在没有显示器的无头网关上。
您希望有一个长期无人值守运行的引擎，并能不时通过 GUI 进行检查。

remote-debugging

安全性说明

UI 与 cycbox-edge 之间的链路建立在 P2P 网络之上，提供以下保障：

端到端加密传输（QUIC + TLS 1.3）。 UI 与边缘代理之间交换的每一个字节，都使用基于两端长期身份派生的密钥进行加密。中继服务器只能看到密文，无法解密流量。
基于公钥的身份认证。 边缘代理的 endpoint_id 是首次运行时生成的 Ed25519 密钥对的公钥部分。UI 通过该公钥验证代理身份，因此中间人若未窃取边缘机器上的私钥，便无法冒充代理。
无需开放入站端口。 双方都通过 NAT/防火墙发起出站连接，并使用打洞技术建立 P2P 通道，必要时回退到中继服务器。您无需在边缘机器的路由器上开放端口，也无需将任何服务暴露到公网。
强制密码握手。 在密码学身份认证之上，cycbox-edge 还要求连接方提供密码后才会响应任何 RPC 请求。首次运行时会自动生成一个 16 位随机密码；未提供正确密码的连接将被立即拒绝。

简而言之：即便流量经过公共中继，连接也始终是私密的；并且代理只接受同时拥有正确公开 endpoint id 和正确密码的调用方。

第 1 步 —— 在边缘机器上安装 `cycbox-edge`

cycbox-edge 以单个二进制文件的形式随 CycBox 一同发布。请前往 GitHub Releases 页面下载与边缘机器操作系统和架构相匹配的版本，解压后放置在 PATH 路径下（例如 /usr/local/bin/cycbox-edge）。

可以通过以下命令确认安装是否成功：

cycbox-edge --help

第 2 步 —— 生成配置文件

首次运行 cycbox-edge 时，如果指定路径下不存在配置文件，它会生成一份示例配置（包含全新的密钥和密码）并打印到标准输出，然后直接退出，不会启动服务。

执行一次以初始化配置：

cycbox-edge

输出示例：

# No config found. Save the following to config.yaml and re-run:
# endpoint_id: 5f4a9c...e1b2
debug: false
edge_key: 9b3a...c7
relays:
  - https://us.cycbox.io/
  - https://eu.cycbox.io/
  - https://cn.cycbox.com/
password: aB3xK9mQ7nP2wL5v
data: ./data
auto_start: false

将这段 YAML 保存为 config.yaml。其中有两个值在从 UI 端连接时尤为重要：

endpoint_id（以注释形式打印在配置上方）—— 该代理的公开身份。它由 edge_key 派生而来，只要不更换 edge_key，该值就不会变化。
password —— 任何连接此代理的 UI 都必须提供。

请妥善保管这些凭据

任何同时获得 endpoint id 和密码的人都可以操作引擎——启动/停止引擎、修改配置、读取实时数据并注入消息。请像对待 SSH 凭据一样对待它们。切勿在公开聊天、截图或工单中泄露。

配置字段说明

字段	用途
`edge_key`	32 字节 Ed25519 私钥的十六进制编码，是代理的身份标识。首次运行时自动生成。
`password`	连接 UI 必须提供的密码，强制启用。首次运行时自动生成。
`relays`	用于在直连 P2P 失败时进行打洞的中继服务器 URL 列表。默认值覆盖美国、欧洲和中国节点。
`data`	用于持久化引擎状态和 `config.lua`（导出的工作流）的数据目录，默认为 `./data`。
`auto_start`	若为 `true` 且 `data/config.lua` 存在，启动时会自动运行该工作流。
`debug`	启用详细日志。

第 3 步 —— 运行 `cycbox-edge`

前台启动代理：

cycbox-edge --config ./config.yaml

您应看到类似如下输出：

[INFO] Starting CycBoxEdge...
[INFO] ================================
[INFO] Endpoint ID: 5f4a9c...e1b2
[INFO] ================================

让进程保持运行。对于长期部署，建议使用 systemd、tmux、screen、Docker 或您熟悉的服务管理器进行守护。

访问串口设备

如果目标设备通过 USB 串口连接到边缘机器，请确认运行 cycbox-edge 的用户拥有访问该串口设备的权限（在 Linux 上，通常需要将用户加入 dialout 或 uucp 组，然后重新登录）。

第 4 步 —— 从 CycBox UI 连接

在您的笔记本电脑上打开 CycBox，将后端切换到远程代理：

打开切换至远程调试对话框。
将后端模式选为远程。
填写连接信息：
- Endpoint ID —— 粘贴 cycbox-edge 启动日志中打印的值（或配置文件中 # endpoint_id: 注释的值）。
- 密码 —— 粘贴代理配置中的 password。
- 中继 —— 每行一个 URL。除非您的网络有特殊要求，否则建议保持配置文件中默认的三个中继。
点击应用。

CycBox 将建立加密的 P2P 通道，使用密码完成身份认证，并从远程引擎重新加载配置清单。连接建立后，所有界面——终端、设置、仪表盘、Lua 脚本编辑器——都会像操作本地引擎一样操作远程引擎。

对话框还会保留最近使用过的 endpoint 历史记录，方便您在不同代理之间快速切换，无需重复输入连接信息。

远程后端是高级版功能

将 UI 切换到远程后端需要有效的 CycBox Pro 高级版授权。但运行 cycbox-edge 本身不需要授权。

切换回本地

再次打开切换后端对话框，选择本地并点击应用。UI 会重新连接到内置于应用中的本地引擎。

可选：开机自动启动工作流

如果您希望远程引擎在没有任何 UI 连接的情况下也能自动启动特定工作流，可以预先放置一份 Lua 配置文件：

从 CycBox UI 将工作流导出为 .lua 文件（文件格式参见 Docker 部署）。
将其拷贝到边缘机器的 <data>/config.lua（默认 ./data/config.lua）。
在 config.yaml 中设置 auto_start: true。
重启 cycbox-edge。

启动时，代理会加载 config.lua，在默认配置清单的基础上合并这些值，并自动启动引擎。之后 UI 仍可随时连接以查看实时数据或修改配置。

故障排查

UI 一直停留在"切换中..."且无法连接。

确认代理仍在运行且网络可达。边缘机器和您的笔记本都需要能够出站访问至少一个已配置的中继服务器。
仔细核对 UI 中的 endpoint_id 是否与 cycbox-edge 打印的一致。哪怕错一个字符也会被路由到不存在的节点。
确保 UI 中的中继 URL 与代理使用的中继有交集。

身份认证立即失败。

UI 中的密码与代理配置中的 password: 不一致。密码区分大小写。

忘记密码或需要轮换凭据。

停止 cycbox-edge，编辑 config.yaml 中的 password: 字段（任意非空值均可），然后重启代理。所有已连接的 UI 都需要重新输入新密码。
如需轮换身份本身，将 edge_key: 置空后重启——程序会生成全新的密钥和 endpoint id。注意此操作会使 UI 中保存的历史记录失效。

安全性说明​

第 1 步 —— 在边缘机器上安装 cycbox-edge​

第 2 步 —— 生成配置文件​

配置字段说明​

第 3 步 —— 运行 cycbox-edge​

访问串口设备​

第 4 步 —— 从 CycBox UI 连接​

切换回本地​

可选：开机自动启动工作流​

故障排查​