跳转到内容
EasyTier-ESP EasyTier-ESP

配置诊断

组件不缓存解析诊断，失败原因只出现在串口 Error 日志里。本页按日志关键字给出对照。

先做三件事

Section titled “先做三件事”
  1. 打开 EASYTIER_ESP_LOG_LEVEL=Error（或 Info）；
  2. 抓取构造前后的完整日志；
  3. 找到第一条 ET.TOML / ET.CONFIG 的 Error，而不是最后一条。

TOML 解析错误

Section titled “TOML 解析错误”
日志关键字原因修复
config field 'instance_name' must be a string类型不是字符串加引号
config field 'hostname' must be a string类型错误加引号
config field 'instance_id' must be a UUID stringUUID 格式不对32 个十六进制位，可带连字符
config field 'network_identity' must be a table写成了字符串/数组使用 [network_identity]
network_identity.network_name must be a string类型错误加引号
network_identity.network_name must not be empty空字符串填网络名
network_identity.network_name is required表存在但缺字段补 network_name
peer must be an array of tablespeer 不是数组用 [[peer]]
peer[0] must be a table元素不是表每个入口一个 [[peer]]
peer[0].uri is missing or not a supported tcp:// endpoint缺 uri、协议错误、IPv6、端口非法改为 tcp://host:port
config field 'flags' must be a tableflags 类型错误使用 [flags]
flags.mtu must be an integer in [576,1380]MTU 越界/不是整数改到 576..1380
flags.enable_encryption must be a boolean不是布尔true / false
config field 'dhcp' must be a boolean or an IPv4 CIDR string类型/格式错误true 或 "10.126.126.0/24"
config field 'dhcp' prefix must be in [0,30]前缀太大改到 0..30

结构校验错误

Section titled “结构校验错误”

这些错误发生在 TOML 解析成功之后：

日志关键字原因修复
no usable entry peer configured[[peer]] 为空至少加一个入口
neither ipv4 nor dhcp is configured没写地址，或 ipv4 内容非法被忽略写 ipv4 或 dhcp
mtu ... out of rangeMTU 越界576..1380
network_name must not be empty网络名为空填非空值
entry peer 0 is incompletehost 为空或 port 为 0检查 URI

内存/运行错误

Section titled “内存/运行错误”
日志关键字原因修复
context allocation failed (…)堆不足开 PSRAM、降低队列/连接槽
queue/semaphore allocation failed队列分配失败降低深度、开 PSRAM
TcpConn slot N allocation failed连接槽分配失败降低 MAX_CONNECTED_PEERS
control-plane AEAD init failedPSA/mbedTLS 问题检查配置与组件依赖
cannot create et_io task任务创建失败降低栈或开 PSRAM

运行期不兼容

Section titled “运行期不兼容”
日志关键字原因修复
compressed data-plane flags are not supported对端压缩数据面关闭对端压缩
peer used zstd compression, which this profile does not supportRPC 使用 Zstd上游关闭 data_compress_algo
virtual subnet overlaps the physical LAN虚拟网段与 Wi-Fi STA 冲突换虚拟网段

核对生效配置

Section titled “核对生效配置”
et::Settings cfg = inst.get_config_info();
ESP_LOGI(TAG, "network=%s secret_len=%u mtu=%u enc=%d dhcp=%d ipv4=%08x peers=%u",
         cfg.network_name.c_str(),
         static_cast<unsigned>(cfg.network_secret.size()),  // 恒为 0
         cfg.mtu, cfg.enable_encryption, cfg.dhcp,
         cfg.static_ipv4, static_cast<unsigned>(cfg.peers.size()));

如果 get_config_info() 的值和 TOML 预期不一致，优先怀疑：

  • 字段名拼错，被当作未知键忽略；
  • ipv4 内容非法被静默忽略；
  • 同时写了 ipv4 与 dhcp，静态优先。

打开 Debug

Section titled “打开 Debug”
CONFIG_EASYTIER_ESP_LOG_DEBUG=y

Debug 会输出解析阶段与逐槽连接细节，但增加日志量与固件体积。生产固件建议 Info 或 Warning。

不要做的事

Section titled “不要做的事”
  • 不要只打印 last_error() 而不看日志；
  • 不要把所有错误都归因于“内存不够”；
  • 不要用旧 ELF 解析回溯；
  • 不要在事件回调里做阻塞式诊断。