AgentBay Linux 桌面迁移 FC Agent Sandbox Desktop 指南

"""Linux Desktop + noVNC WebSDK 集成 demo（后端）。

配套三文件：demo.py（本文件）、index.html（前端）、.env（凭证）。

依赖：pip install "e2b>=2.31.0" e2b-desktop==2.4.1 python-dotenv
运行：python demo.py   （浏览器打开打印的 http://127.0.0.1:<port>/ 即可看到实时桌面）
"""
from __future__ import annotations

import json
import os
import signal
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path

from dotenv import load_dotenv
from e2b import Template, default_build_logger
from e2b_desktop import Sandbox

BASE_DIR = Path(__file__).resolve().parent
load_dotenv(BASE_DIR / ".env")

TEMPLATE = os.environ["E2B_DESKTOP_TEMPLATE"]
IMAGE = os.environ.get("E2B_DESKTOP_IMAGE", "")
HOST = "127.0.0.1"


def ensure_template() -> str:
    if Template.exists(TEMPLATE):
        print(f"[demo] 复用模板: {TEMPLATE}", flush=True)
        return TEMPLATE
    if not IMAGE:
        raise SystemExit(
            f"[demo] 模板 {TEMPLATE!r} 不存在，请在 .env 配置 E2B_DESKTOP_IMAGE 以自动构建"
        )
    print(f"[demo] 从镜像构建模板 {TEMPLATE!r}: {IMAGE}", flush=True)
    build = Template.build(
        Template().from_image(IMAGE),
        name=TEMPLATE,
        cpu_count=4,
        memory_mb=8192,
        on_build_logs=default_build_logger(),
    )
    return build.template_id


class Handler(BaseHTTPRequestHandler):
    stream_url: str = ""

    def do_GET(self) -> None:
        if self.path == "/api/sandbox/vnc-url":
            body = json.dumps({"streamUrl": Handler.stream_url}).encode("utf-8")
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return
        if self.path in ("/", "/index.html"):
            body = (BASE_DIR / "index.html").read_bytes()
            self.send_response(200)
            self.send_header("Content-Type", "text/html; charset=utf-8")
            self.send_header("Content-Length", str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return
        if self.path == "/favicon.ico":
            self.send_response(204)
            self.end_headers()
            return
        self.send_error(404)

    def log_message(self, *args) -> None:
        pass  # 不输出访问日志，避免任何 URL（含 query 参数）落盘


def _stop(_signum, _frame) -> None:
    raise KeyboardInterrupt


def main() -> None:
    signal.signal(signal.SIGTERM, _stop)

    template = ensure_template()
    print("[demo] 创建桌面沙箱（Xvfb + xfce4 + x11vnc + noVNC）...", flush=True)
    desktop = Sandbox.create(template=template, timeout=600, secure=True)
    server: ThreadingHTTPServer | None = None
    try:
        desktop.stream.start()
        stream_url = desktop.stream.get_url()
        # 若数据面要求 traffic access token，FC 后端支持以 query 参数方式传递，在此拼接：
        # token = getattr(desktop, "traffic_access_token", None)
        # if token:
        #     stream_url += f"&traffic_access_token={token}"

        Handler.stream_url = stream_url
        server = ThreadingHTTPServer((HOST, 0), Handler)
        print(f"[demo] 浏览器打开: http://127.0.0.1:{server.server_port}/", flush=True)
        print("[demo] Ctrl-C 退出（自动停止流并销毁沙箱）", flush=True)
        server.serve_forever()
    except KeyboardInterrupt:
        print("\n[demo] 退出中...", flush=True)
    finally:
        if server is not None:
            server.server_close()
        try:
            desktop.stream.stop()
        except Exception:
            pass
        desktop.kill()
        print("[demo] 已停止 VNC 流并销毁沙箱", flush=True)


if __name__ == "__main__":
    main()

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>FC Linux Desktop (noVNC)</title>
  <style>
    html, body { margin: 0; height: 100%; }
    #vnc-screen { width: 100vw; height: 100vh; }
  </style>
</head>
<body>
  <div id="vnc-screen"></div>

  <script type="module">
    // ESM 引入 noVNC 官方构建（固定版本；npm 包 lib/rfb.js 为 CJS，不能用 <script src> 直载）
    import RFB from 'https://cdn.jsdelivr.net/gh/novnc/noVNC@v1.6.0/core/rfb.js';

    async function initVNC() {
      // 从后端 API 获取 stream_url（沙箱生命周期与凭证都在后端，前端不接触）
      const resp = await fetch('/api/sandbox/vnc-url');
      const { streamUrl } = await resp.json();

      const rfb = new RFB(
        document.getElementById('vnc-screen'),
        // https://{sandbox-host}/vnc.html?... —— 同一 URL 双重角色：-
        // 浏览器直接打开是该 noVNC 页面文件；RFB 会升级为 wss://.../vnc.html 作为 WebSocket 端点
        streamUrl,
        { credentials: { password: '' } }  // stream.start() 未开鉴权时为空
      );

      rfb.scaleViewport = true;
      rfb.resizeSession = false;
    }

    initVNC();
  </script>
</body>
</html>

# Linux Desktop + noVNC demo 配置（填入真实值后本文件即含密钥：勿提交版本库、勿分享、勿粘贴进聊天/工单）
E2B_API_KEY=
E2B_API_URL=https://api.cn-beijing.e2b.fc.aliyuncs.com
E2B_DOMAIN=cn-beijing.e2b.fc.aliyuncs.com

# 桌面模板名：已存在则复用；不存在时用 E2B_DESKTOP_IMAGE 自动构建一次
E2B_DESKTOP_TEMPLATE=my-desktop-template
E2B_DESKTOP_IMAGE=fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/desktop:v0.0.44