故障排查

下面每一条都是真实发生过的故障及其原因，按"最容易被误判成别的东西"排序。

no available local poder found

创建找不到 worker。消息里说 local 是因为 provider 是 local，不是因为机队坏了。

原因	怎么查
没有任何 worker 注册过	sandrpod-cli poder list
地域不一致 —— 客户端默认 local，worker 注册成 hk	select id, region from poders，两边必须一致
worker 到了容器上限	看 worker 行的 usage_containers / max_containers；删掉已停止的沙箱
重启后 worker 离线	心跳停了；看 docker logs sandrpod-worker
租户不匹配	为一个工作区签的 join token 不能承载另一个工作区的沙箱

最后一条是故意的：拒绝，好过把两个租户挤在一起。

sandbox tunnel not available（503）

沙箱存在，但持有它隧道的 worker 没有连在收到请求的那个实例上。

• 单实例：worker 离线，或者隧道断了正在重连（它每几秒重试一次）。
• 多实例：owner 记录过期了。检查持有方实例的 -node-url 非空且在收心跳； tunnel_owners.updated_at 应该是几秒前，而不是几分钟前。

worker capability unavailable（409）

请求需要的能力没有任何可用 worker 具备 —— 出网策略需要带 egress 能力的 worker。 部署这样的 worker，或者去掉策略。

沙箱卡在 PENDING

创建没有到达 worker。job 行会说明原因：

sandrpod-cli job get <job-id>

no available local poder found → 见上。什么都没有 → 进程死在投递中途；恢复器会在 大约一分钟内接过去，而一条超过这个时间又没有错误的 job 值得查一下。

create egress proxy container: No such image

worker 上没有 ghcr.io/sandrpod/egress-proxy。拉取之后重建 —— 失败的那次已经写入了 记录，所以先把它删掉。

删掉的沙箱又回来了

删除会清掉记录和容器；一条仍然 PENDING 的创建 job 曾被恢复器重新投递。0.7.1 已修： 沙箱记录不存在、或已处于终态的 job 会判失败而不是重放。旧版本上如果遇到，升级。

用 E2B SDK 时 commands.run 返回 401

SDK 不会把 API key 发给 envd。它把创建响应里的 envdAccessToken 作为 X-Access-Token 发出去，而托管部署必须接受这个 token，不能只认自己的工作区 key。0.7.1 已修；更早的 版本上只有 create 和 kill 能用。

E2B SDK 在发请求之前就拒绝密钥

Invalid API key format: expected "e2b_" followed by hex characters。密钥必须用这种 拼写签发 —— 同一张表、同样吊销、只是前缀不同。见 E2B 直接替换。

envd 主机返回了 200，但健康文档不是 envd 的

主机没有路由到 E2B 面。只按路径挂载（/sandboxes）足以支持创建和删除，不足以支持 <端口>-<id>.<域名>；请求落到了控制面。托管构建在 0.7.1 已修；检查你的反向代理是否 原样传递 Host 头。

自签部署上 TLS 失败

证书通常只签了一个名字。用 IP 连接、而证书上是主机名时，即使 CA 被信任也会验证失败。 用证书上的名字连接，或者把 CA 加进进程的信任库（SSL_CERT_FILE）。

整体很慢，或者主机干脆不响应

先看内存，再看 CPU。同一台机器上的 go build 拖垮过整台主机；同一台机器上既跑门户又 跑一批沙箱也一样。

free -h; uptime; ps aux --sort=-%mem | head

解决办法几乎总是"别再合租"：worker 单独机器、控制面小、数据库托管。见 生产部署。

该看哪里

问题	命令
平台健康吗	curl -s https://…/healthz | jq
机队在干什么	sandrpod-cli poder list
这次创建做了什么	sandrpod-cli job get <job-id>
容器在干什么	sandrpod-cli logs <名字> --tail 100
worker 在干什么	docker logs sandrpod-worker