跳到正文
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
浏览文档

帮助

故障排查

解决常见的 Docker、构建、令牌、网关、网络、会话与导出问题。

本页内容+

无法连接 Docker

如果启动器或镜像列表报告 Docker 连接错误，请在同一个 shell 中验证守护进程并检查 DOCKER_HOST。provider 使用 Docker Engine API，并遵循该端点配置。

Shell
docker info
printf '%s\n' "${DOCKER_HOST:-<default Docker endpoint>}"
sandbox-manager-cli list_docker_images

启动 Docker Desktop 或系统守护进程；在尝试创建沙箱前，先重新运行镜像列表。

网关无法启动

在前台运行启动器，直到读到明确的错误。它会构建主机二进制文件、验证已打包的守护进程、检查两个 Git 工具链归档，之后才会启动后台网关。

Shell
start-sandbox-docker-gateway --rebuild-binary
tail -n 100 "${SANDBOX_GATEWAY_LOG:-/tmp/eos-gateway.log}"

缺失的 dist/sandbox-daemon-linux-* 构件可通过 cargo run -p xtask -- package 修复。如果 dist/git/linux-arm64.tar 或 dist/git/linux-amd64.tar 缺失，请先停止：仓库目前没有记录从源码生成这些归档的命令。

客户端认证失败

仓库包装脚本会读取私有令牌文件并导出凭据。确认文件路径，并使用 bin 中的包装脚本；不要把令牌复制到 YAML 或浏览器代码。

Shell
export PATH="$PWD/bin:$PATH"
sandbox-gateway-token path
ls -l "$(sandbox-gateway-token path)"
sandbox-manager-cli list_sandboxes

如果你有意设置 SANDBOX_GATEWAY_AUTH_TOKEN，它必须与配置的令牌文件一致。还要确认 SANDBOX_GATEWAY_SOCKET 指向创建该令牌的同一个网关。

沙箱创建失败

通过控制台使用的同一组公开发现操作验证镜像引用和工作区。配置了 manager.workspace_roots 允许列表后，不在其中绝对路径下的根目录会被拒绝。

Shell
sandbox-manager-cli list_docker_images
sandbox-manager-cli list_workspace_directories
sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root /absolute/workspace

如果创建操作留下了记录，请先检查再销毁。生命周期状态和错误信息比盲目重试更有帮助。

Shell
sandbox-manager-cli list_sandboxes
sandbox-manager-cli inspect_sandbox --sandbox-id eos-abc
sandbox-manager-cli destroy_sandbox --sandbox-id eos-abc

命令或网络失败

先区分 shell 失败与网络失败。运行一条本地命令，再检查沙箱快照和近期领域事件。当前生产配置允许 RFC1918 出站，并注入 Docker Desktop HTTP 代理变量；本地覆盖配置可能替换其中任一策略。

Shell
sandbox-runtime-cli --sandbox-id eos-abc exec_command "id && pwd"
sandbox-observability-cli snapshot --sandbox-id eos-abc
sandbox-observability-cli events --sandbox-id eos-abc --last-n 30

命令无法看到 runner.mount_mask.hidden_paths 遮蔽的路径；基线配置会隐藏 /eos。修改网络或挂载策略前，请先查看 配置参考。

会话或发布停滞

使用可观测性接口，而不是内部生命周期路由。最后一条 trace 会展示操作耗时；层栈和 cgroup 查询则会暴露租约、预留、磁盘用量和资源压力。

Shell
sandbox-observability-cli trace --sandbox-id eos-abc --trace-id last
sandbox-observability-cli layerstack --sandbox-id eos-abc --window-ms 60000
sandbox-observability-cli cgroup --sandbox-id eos-abc --window-ms 60000

发布冲突会拒绝候选更改，而不是覆盖更新的持久状态。读取最新快照，再从新的自动会话重新执行预期更改；详情参阅 捕获与冲突。

导出失败

目标路径必须是绝对路径。目录格式会把增量应用到一个目录；tar 和 tar-zst 需要归档文件路径。只有已发布的层会被导出。

Shell
sandbox-manager-cli export_changes --sandbox-id eos-abc --dest /tmp/sandbox-delta.tar --format tar

如果预期文件缺失，请在导出前用 file_read 验证。不要直接调用内部层栈导出或分块操作。

控制台无法打开

启动受支持的控制台栈，再检查 loopback catalog 与控制台日志。默认监听地址是 127.0.0.1:7880，默认日志是 /tmp/eos-console.log。

Shell
start-sandbox-console-stack
curl --fail http://127.0.0.1:7880/api/catalog
tail -n 100 "${SANDBOX_CONSOLE_LOG:-/tmp/eos-console.log}"

API 路由返回 401 或 502，通常表示控制台与网关的端点或令牌不一致。直接访问守护进程路径返回 404 可能是正确行为：守护进程 HTTP 允许列表仅包含健康检查、预览转发和 POST /files/list。参阅 守护进程 HTTP 边界。

18 个结果