网络端口与服务预览

SeaCloud Sandbox 通过 sandbox-router 暴露沙箱端口。当前生产环境使用 path-style URL：端口和 Sandbox ID 放在第一个 path segment 中，例如 https://sandbox-router.cloud.seaart.ai/3000-sandbox-.../。

运行时 API 通常使用模板默认端口，托管运行时一般是 9000；普通业务模板可能使用自己的默认端口，例如 9001。你的应用应监听独立端口，例如 3000。

URL 模型

当前生产环境：

https://sandbox-router.cloud.seaart.ai/{port}-{sandboxID}/

URL	含义
`envdUrl`，例如 `https://sandbox-router.cloud.seaart.ai/9000-{sandboxID}`	模板默认端口。托管运行时通常用于 Runtime API、健康检查、文件和进程。
`https://sandbox-router.cloud.seaart.ai/3000-{sandboxID}/`	直接访问同一沙箱内监听 `3000` 端口的应用。
`sandbox.getHost(3000)`	SDK 推荐方式。SDK 会基于 `envdUrl` 返回可访问的代理 URL，不需要你手拼路由。

旧模板如果把 envdBaseDomain 配成纯域名，可能仍返回历史子域名形式 https://{port}-{sandboxID}.{domain}/。新模板和当前生产环境应按 https://sandbox-router.cloud.seaart.ai/{port}-{sandboxID}/ 理解。

await sandbox.files.makeDir("/root/workspace/site");
await sandbox.files.write(
  "/root/workspace/site/index.html",
  "<!doctype html><h1>Hello SeaCloud</h1>",
);

await sandbox.commands.run("python3", {
  args: ["-m", "http.server", "3000", "--bind", "0.0.0.0", "--directory", "/root/workspace/site"],
  background: true,
});

console.log(sandbox.getHost(3000));

sandbox.files.make_dir("/root/workspace/site")
sandbox.files.write(
    "/root/workspace/site/index.html",
    "<!doctype html><h1>Hello SeaCloud</h1>",
)
sandbox.commands.run(
    "python3",
    args=["-m", "http.server", "3000", "--bind", "0.0.0.0", "--directory", "/root/workspace/site"],
    background=True,
)
print(sandbox.get_host(3000))

Vite 类开发服务

await sandbox.commands.run("sh", {
  cwd: "/root/workspace",
  args: ["-lc", "npm run dev -- --host 0.0.0.0 --port 3000"],
  background: true,
});

console.log(sandbox.getHost(3000));

curl 推导 URL

使用原始 API 且已有 sandboxID 时，可以直接构造 path-style 应用 URL。

APP_URL="https://sandbox-router.cloud.seaart.ai/3000-${SANDBOX_ID}/"
echo "${APP_URL}"

如果你只有当前生产环境的 envdUrl，也可以把第一个 path segment 中的端口替换成应用端口：

APP_URL=$(printf '%s' "${ENVD_URL}" | sed -E 's#/([0-9]+)-#/3000-#')
echo "${APP_URL}"

运行时健康检查与 Proxy

用运行时健康检查区分 runtime 可达和应用就绪：

curl -i "${ENVD_URL}/health"

托管运行时健康检查通常返回 204 No Content。GET {envdUrl}/ 可能返回类似 { "status": "ok" } 的轻量 JSON；这不代表你的应用运行在 9000 端口。

运行时也支持 proxy 路由：

GET {envdUrl}/proxy/3000/

原始公网端口 URL 使用 sandbox-router path-style：

https://sandbox-router.cloud.seaart.ai/3000-{sandboxID}/

出网策略

公网预览解决的是从互联网访问沙箱端口。沙箱主动访问外部网络由模板、环境和账户策略单独控制。

目标	预期行为
公网 API	当所选模板和账户策略允许出网时可访问。
SeaCloud API	由 SDK 使用。不要硬编码服务地址。
私有基础设施网段	不属于公开契约，可能被网络策略阻断。

如果工作负载需要访问私有服务，应通过你的后端或明确的产品集成转发，不要依赖沙箱网络可达性。

排障

现象	检查项
`9000` 返回健康检查，但应用不存在	`9000` 是运行时 API 端口，不是应用端口。
应用 URL 返回 `502`	进程退出、端口错误，或服务只绑定 `127.0.0.1`。
页面空白	HTML 已返回，但静态资源缺失或 base path 错误。
WebSocket 失败	确认框架使用同一主机和公网端口路由。
`readyCmd` 通过但预览失败	确认 `readyCmd` 检查的端口和用户打开的端口一致。