代码沙箱 / 远程浏览器

代码沙箱（sandbox-service）和远程浏览器（browser-service）是两个可选的高级服务，默认关闭。两者都通过平台的 OAuth 流程登录。本页介绍如何启用、OAuth client 自动注册，以及外部 ingress 场景下的公网 URL 覆盖。

两个服务

服务	能力	依赖
代码沙箱	让 agent 运行代码并提供临时 web 预览	第三方 OpenSandbox（你自行安装；平台通过 `OPENSANDBOX_URL` 指向它）
远程浏览器	让 agent 驱动真实浏览器，用户通过 WebRTC 实时观看	内置的 TURN relay（coturn），随 `BROWSER_ENABLED` 一起启用

在配置生成器中切换对应模块即可生成带这些段落的 values.env，或手动把 SANDBOX_ENABLED / BROWSER_ENABLED 设为 true。

启用

把相应的 values.env 开关设为 true，填好必填项，下一次 install.sh 即生效：

# Code Sandbox
SANDBOX_ENABLED=true
SANDBOX_NODE_PORT=30086
SANDBOX_JWT_SECRET=      # openssl rand -hex 32
SANDBOX_SERVICE_KEY=     # openssl rand -hex 32, shared between browser and sandbox

# Remote Browser (incl. TURN)
BROWSER_ENABLED=true
BROWSER_NODE_PORT=30085
BROWSER_JWT_SECRET=      # openssl rand -hex 32
TURN_HOST=               # public / LAN IP browsers can reach, required
TURN_AUTH_SECRET=        # openssl rand -hex 32

SANDBOX_JWT_SECRET / BROWSER_JWT_SECRET 分别是各自服务的会话签名密钥；SANDBOX_SERVICE_KEY 是 browser 调用 sandbox 时使用的共享密钥（两个模块都开时由 browser 复用）。关于 TURN_HOST 及其排障，见 Ingress 接入和下文”排障”。

安装 OpenSandbox

代码沙箱由 OpenSandbox（github.com/alibaba/OpenSandbox）驱动，这是一个第三方组件，平台安装器不会为你安装。当 SANDBOX_ENABLED=true 时，install.sh 部署 nap-sandbox，并假定 OpenSandbox 已安装好且可在 OPENSANDBOX_URL 处访问。

从 OpenSandbox 上游 Helm charts 安装它（controller + server），然后把平台指向它：

git clone https://github.com/alibaba/OpenSandbox && cd OpenSandbox/kubernetes/charts
helm dependency build opensandbox
helm install opensandbox ./opensandbox \
  --namespace nap --create-namespace \
  -f <path-to>/optional/sandbox/opensandbox-values.yaml

把 OpenSandbox 装在 nap namespace 里，平台默认的 OPENSANDBOX_URL 才能解析。如果你把 OpenSandbox 装到独立 namespace，需显式设置 OPENSANDBOX_URL（例如 http://opensandbox-server.opensandbox-system.svc:80）。完整参考（包括挂载平台的 sandbox pod 模板）见 self-host README 的 “Enabling Code Sandbox”。

OAuth client 自动注册

两个服务都通过平台 OAuth 流程登录，使用固定的 client_id（sandbox-service / browser-service）—— 它们是 PKCE public client，没有 client_secret。这些 client 必须存在于控制面的 oauth_clients 表中，否则登录时 GET /api/oauth/authorize 会返回 400 invalid_client。

seed 完 admin 后，install.sh 运行一个 nap-seed-oauth-clients Job，根据已启用的模块自动注册这两行 —— 无需在”应用”页面手动创建。注册的 redirect_uri 与服务自身计算回调用的 origin 一致，因此不会漂移：

client_id	默认 redirect_uri
`sandbox-service`	`http://<TOS_HOST>:<SANDBOX_NODE_PORT>/api/auth/callback`
`browser-service`	`http://<TOS_HOST>:<BROWSER_NODE_PORT>/api/auth/callback`

该 Job 是幂等的：改了 NodePort 或公网 URL 后，重新执行 install.sh（或 install.sh --seed-only）会自动同步 redirect_uris。

可选：公网 URL 覆盖

服务地址默认从 NodePort 派生。当你通过自己的 ingress / 自定义域名暴露服务时（通常是 INGRESS_MODE=external，见 Ingress 接入），NodePort 形式的地址既不是对外正确的地址，也与 OAuth 回调不匹配。用 *_PUBLIC_URL 覆盖它：

SANDBOX_PUBLIC_URL=https://sandbox.example.com
BROWSER_PUBLIC_URL=https://browsers.example.com

该覆盖同时作用于服务自身的回调地址和注册的 redirect_uri，让两者保持同步。留空则保持原有的 NodePort 行为，不影响既有部署。地址末尾不带斜杠。

排障

登录跳转报 400 invalid_client —— oauth_clients 中缺少匹配行。确认 seed Job 已运行且成功：kubectl -n <ns> logs job/nap-seed-oauth-clients；日志会打印 registered "sandbox-service" → ...。手动重跑：install.sh --seed-only。
登录回调报 400 invalid_redirect_uri —— 注册的 redirect_uri 与服务实际的回调地址不匹配。常见于配置了外部 ingress 但没设 *_PUBLIC_URL，或改了 NodePort 却没重新 seed。设置 *_PUBLIC_URL 并重新执行 install.sh --seed-only。
浏览器无画面 / 黑屏 —— 通常是 TURN 不可达。确认 TURN_HOST 是浏览器端实际能访问到的 IP（kubelet 自动探测在多网卡节点上不可靠，所以要显式设置），并确认 coturn 已就绪：kubectl -n <ns> get pod -l app=coturn。
Sandbox 起不来 —— 先检查 OpenSandbox 是否已安装：kubectl -n <ns> get pod -l app.kubernetes.io/name=opensandbox。