新增固定 LXDE 桌面分頁：Xvfb + x11vnc + noVNC，看門狗維持恰好一個

README.md

@@ -19,8 +19,8 @@ OpenCode 在啟動時安裝，並重設使用者層級設定為預設值。
 
 ## 檔案
 
-- `app.py` — FastAPI + xterm.js 終端機、檔案瀏覽器與 `/ws` session 管理
-- `packages.txt` — 系統套件（`tmux`）
+- `app.py` — FastAPI + xterm.js 終端機、檔案瀏覽器、`/ws` session 管理與固定 LXDE 桌面
+- `packages.txt` — 系統套件（`tmux`、`xvfb`、`x11vnc`、`lxde-core`、`novnc`、`x11-utils`）
 - `requirements.txt` — Python 相依套件
 
 ## 終端機分頁（全部共用、全部長存）
@@ -44,6 +44,24 @@ OpenCode 在啟動時安裝，並重設使用者層級設定為預設值。
 `installpi.sh` 已從 Space 流程中移除（不再自動執行），檔案本身保留在 repo 作為紀錄，
 需要時手動執行。
 
+## 固定桌面分頁（Xvfb + LXDE + x11vnc + noVNC）
+
+終端機分頁之外，最左側有一個 **固定** 的「桌面 1（LXDE，共用）」分頁：
+
+- 伺服器永遠維持 **恰好一個** `Xvfb`（`:99`）＋ 一個 LXDE session ＋ 一個 `x11vnc`
+  （只監聽 `127.0.0.1:5900`）。看門狗每 3 秒檢查，任何一個程序死掉會自動補回，
+  重複的程序會被清掉。
+- 瀏覽器是透過 `/vnc` WebSocket 橋接到同一個桌面，所有裝置看到完全相同、可同時操作的
+  LXDE 畫面；關掉瀏覽器分頁不會終止桌面，重新整理或重新連線都會接回原畫面。
+- 這個分頁是固定的：按它的 `×` 不會刪除分頁，而是重新啟動一份新的桌面
+  （`POST /api/desktop/restart`），永遠維持一個。
+- 舊的 tmux 終端機分頁、上傳／下載／複製／貼上等行為完全沒有改變。
+- 除錯端點：`GET /api/desktop/status`、`POST /api/desktop/restart`（程序 pid、VNC port、
+  健康狀態）；桌面 log 在 `/tmp/webterm-desktop.log`。
+- 可用 Space 變數覆寫：`DESKTOP_DISPLAY`（預設 `:99`）、`DESKTOP_GEOMETRY`
+  （預設 `1440x900x24`）、`DESKTOP_VNC_PORT`（預設 `5900`）、`DESKTOP_NOVNC_ROOT`
+  （預設 `/usr/share/novnc`）。noVNC 靜態檔由 `/novnc/*` 提供，缺少時前端自動改用 CDN。
+
 ## 記憶體守衛（memguard）
 
 每次 Space 啟動時，`app.py` 的 `install_memguard()` 會自動：

app.py

@@ -1,6 +1,7 @@
 import os
 import pty
 import shutil
+import socket
 import subprocess
 import signal
 import struct
@@ -10,6 +11,7 @@ import asyncio
 import json
 import base64
 import logging
+import mimetypes
 import time
 import uuid
 
@@ -79,6 +81,10 @@ html,body{height:100%;overflow:hidden;background:#1e1e1e;color:#ccc;font-family:
 #term-box{flex:1;overflow:hidden;padding:2px}
 .tw{width:100%;height:100%;display:none}
 .tw.active{display:block}
+.desktop-wrap{background:#000}
+.desktop-frame{width:100%;height:100%;border:0;display:block;background:#000}
+.tab.fixed{border-color:#3a5f8a}
+.tab.fixed .tab-title::before{content:"固定 · ";color:#7fb0e8;font-size:11px}
 body{display:flex;flex-direction:column}
 #file-picker{width:min(1040px,96vw);height:min(700px,90vh);max-height:90vh;padding:0;margin:auto;border:1px solid #aeb7c2;border-radius:8px;background:#f3f5f8;color:#20242a;box-shadow:0 18px 60px #0005;overflow:hidden;font-family:"Segoe UI",Arial,sans-serif}
 #file-picker::backdrop{background:#10182088;backdrop-filter:blur(2px)}
@@ -338,6 +344,66 @@ function createTab(sessionId = null, title = null, activateIt = true) {
   return obj;
 }
 
+function ensureDesktopTab() {
+  if (tabs.some(t => t.type === 'desktop')) return;
+  const id = ++cnt;
+  const el = document.createElement('div');
+  el.className = 'tab fixed';
+  el.dataset.id = id;
+  el.innerHTML = `<span class="status-dot down"></span><span class="tab-title"></span><span class="x" title="重新啟動桌面">×</span>`;
+  el.querySelector('.tab-title').textContent = '桌面 1（LXDE，共用）';
+  bar.insertBefore(el, addBtn.nextSibling);
+
+  const wrap = document.createElement('div');
+  wrap.className = 'tw desktop-wrap';
+  wrap.dataset.id = id;
+  const frame = document.createElement('iframe');
+  frame.className = 'desktop-frame';
+  frame.title = 'LXDE 共用桌面';
+  frame.src = '/desktop?ts=' + Date.now();
+  frame.setAttribute('allow', 'clipboard-read; clipboard-write; fullscreen');
+  wrap.appendChild(frame);
+  box.appendChild(wrap);
+
+  const obj = {id, type: 'desktop', el, wrap, frame, ws: null, closed: false,
+               currentDir: '/home/user/app', sessionId: 'desktop'};
+  tabs.unshift(obj);
+  el.onclick = e => {
+    if (e.target.classList.contains('x')) closeTab(id);
+    else activate(id);
+  };
+  refreshDesktopStatus();
+}
+
+async function refreshDesktopStatus() {
+  const t = tabs.find(t => t.type === 'desktop');
+  if (!t) return;
+  try {
+    const r = await fetch('/api/desktop/status');
+    const s = await r.json();
+    const dot = t.el.querySelector('.status-dot');
+    if (dot) dot.classList.toggle('down', !s.alive);
+    t.alive = !!s.alive;
+    if (!s.alive && s.last_error) setAppStatus('桌面：' + s.last_error, 'warning');
+  } catch (e) { /* 狀態查詢失敗不影響終端機 */ }
+}
+
+async function restartDesktop() {
+  const t = tabs.find(t => t.type === 'desktop');
+  if (!t) return;
+  setAppStatus('正在重新啟動桌面（Xvfb + LXDE + x11vnc）…', 'info');
+  try {
+    const r = await fetch('/api/desktop/restart', {method: 'POST'});
+    const s = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(s.error || '無法重新啟動桌面');
+    t.frame.src = '/desktop?ts=' + Date.now();
+    setAppStatus(s.alive ? '桌面已重新啟動' : '桌面已重新啟動，等待就緒', s.alive ? 'success' : 'warning');
+    refreshDesktopStatus();
+  } catch (err) {
+    setAppStatus(err.message, 'error');
+  }
+}
+
 function activate(id) {
   activeId = id;
   saveActive();
@@ -345,7 +411,16 @@ function activate(id) {
     const on = t.id === id;
     t.el.classList.toggle('active', on);
     t.wrap.classList.toggle('active', on);
-    if (on && t.term) setTimeout(() => { t.fit.fit(); t.term.focus(); }, 30);
+    if (on && t.type === 'desktop') {
+      setTimeout(() => {
+        try {
+          t.frame.focus();
+          t.frame.contentWindow.dispatchEvent(new Event('resize'));
+        } catch (e) { /* ignore */ }
+      }, 30);
+    } else if (on && t.term) {
+      setTimeout(() => { t.fit.fit(); t.term.focus(); }, 30);
+    }
   });
 }
 
@@ -354,6 +429,7 @@ function removeLocalTab(id) {
   const i = tabs.findIndex(t => t.id === id);
   if (i < 0) return;
   const t = tabs[i];
+  if (t.type === 'desktop') return;
   t.closed = true;
   if (t.ws) { try { t.ws.close(); } catch (e) {} }
   if (t.term) t.term.dispose();
@@ -368,7 +444,12 @@ function removeLocalTab(id) {
 async function closeTab(id) {
   const t = tabs.find(t => t.id === id);
   if (!t) return;
-  if (tabs.length <= 1) {
+  if (t.type === 'desktop') {
+    if (!confirm('重新啟動「桌面 1（LXDE，共用）」？\n\n這是固定分頁，關閉後會自動重開一個新的桌面，永遠維持恰好一個。')) return;
+    await restartDesktop();
+    return;
+  }
+  if (tabs.filter(t => t.type === 'terminal').length <= 1) {
     setAppStatus('至少要保留一個終端機分頁', 'warning');
     return;
   }
@@ -400,7 +481,7 @@ async function doSyncTabs(data = null) {
     const res = data || await apiTabs();
     const serverIds = res.tabs.map(t => t.id);
     [...tabs].forEach(t => {
-      if (t.sessionId && !serverIds.includes(t.sessionId)) removeLocalTab(t.id);
+      if (t.type === 'terminal' && t.sessionId && !serverIds.includes(t.sessionId)) removeLocalTab(t.id);
     });
     res.tabs.forEach(t => {
       const local = tabs.find(l => l.sessionId === t.id);
@@ -411,7 +492,10 @@ async function doSyncTabs(data = null) {
         createTab(t.id, t.title, false);
       }
     });
-    if (!activeId && tabs.length) activate(tabs[0].id);
+    if (!activeId && tabs.length) {
+      const firstTerminal = tabs.find(t => t.type === 'terminal') || tabs[0];
+      activate(firstTerminal.id);
+    }
   } catch (err) {
     setAppStatus('分頁同步失敗：' + err.message, 'warning');
   }
@@ -432,6 +516,10 @@ addBtn.onclick = async () => {
 copyBtn.onclick = async () => {
   const t = activeTab();
   if (!t) return;
+  if (t.type === 'desktop') {
+    setAppStatus('桌面分頁請直接在畫面內選取／複製，或使用桌面內應用程式的剪貼簿', 'info');
+    return;
+  }
   const text = t.term.getSelection();
   if (text) {
     try {
@@ -448,6 +536,10 @@ copyBtn.onclick = async () => {
 pasteBtn.onclick = async () => {
   const t = activeTab();
   if (!t) return;
+  if (t.type === 'desktop') {
+    setAppStatus('桌面分頁請使用桌面內應用程式的貼上功能', 'info');
+    return;
+  }
   try {
     const text = await navigator.clipboard.readText();
     if (t.ws && t.ws.readyState === WebSocket.OPEN) t.ws.send(JSON.stringify({type: 'input', data: text}));
@@ -456,7 +548,14 @@ pasteBtn.onclick = async () => {
   }
 };
 
-uploadBtn.onclick = () => fileInput.click();
+uploadBtn.onclick = () => {
+  const t = activeTab();
+  if (t && t.type === 'desktop') {
+    setAppStatus('桌面分頁請直接在 LXDE 內使用檔案管理員或瀏覽器操作檔案', 'warning');
+    return;
+  }
+  fileInput.click();
+};
 fileInput.onchange = (e) => {
   const file = e.target.files[0];
   if (!file) return;
@@ -661,16 +760,18 @@ document.addEventListener('keydown', e => {
   try {
     let res = await apiTabs();
     if (!res.tabs.length) res = await apiNewTab();
+    ensureDesktopTab();
     await syncTabs(res);
     const wanted = loadActive();
-    const local = tabs.find(t => String(t.sessionId) === wanted) || tabs[0];
+    const local = tabs.find(t => t.type === 'terminal' && String(t.sessionId) === wanted)
+      || tabs.find(t => t.type === 'terminal') || tabs[0];
     if (local) activate(local.id);
   } catch (err) {
     setAppStatus('初始化失敗：' + err.message, 'error');
   }
-  setInterval(() => { if (!document.hidden) syncTabs(); }, 4000);
-  window.addEventListener('focus', () => syncTabs());
-  document.addEventListener('visibilitychange', () => { if (!document.hidden) syncTabs(); });
+  setInterval(() => { if (!document.hidden) { syncTabs(); refreshDesktopStatus(); } }, 4000);
+  window.addEventListener('focus', () => { syncTabs(); refreshDesktopStatus(); });
+  document.addEventListener('visibilitychange', () => { if (!document.hidden) { syncTabs(); refreshDesktopStatus(); } });
 })();
 </script>
 </body>
@@ -731,6 +832,110 @@ async def download_route(path: str):
     return FileResponse(safe, filename=os.path.basename(safe))
 
 
+# ──────────────────────────── 固定桌面分頁路由 ──────────────────────────────
+
+@app.get("/desktop")
+async def desktop_page():
+    """noVNC 用戶端；固定桌面分頁的 iframe 會載入這一頁。"""
+    return HTMLResponse(DESKTOP_PAGE)
+
+
+@app.get("/api/desktop/status")
+async def api_desktop_status():
+    return desktop_manager.status()
+
+
+@app.post("/api/desktop/restart")
+async def api_desktop_restart():
+    try:
+        ok = await desktop_manager.restart()
+    except Exception as exc:
+        log.exception("[desktop] 重新啟動失敗")
+        return JSONResponse({"error": f"無法重新啟動桌面：{exc}"}, status_code=500)
+    return {"ok": ok, **desktop_manager.status()}
+
+
+@app.get("/novnc/{asset_path:path}")
+async def novnc_asset(asset_path: str):
+    """把系統的 noVNC 靜態檔（apt: novnc）提供給瀏覽器；缺少時前端會改用 CDN。"""
+    root = os.path.realpath(DESKTOP_NOVNC_ROOT)
+    target = os.path.realpath(os.path.join(root, asset_path))
+    if not (target == root or target.startswith(root + os.sep)) or not os.path.isfile(target):
+        return JSONResponse({"error": "not found"}, status_code=404)
+    media = mimetypes.guess_type(target)[0] or "application/octet-stream"
+    return FileResponse(target, media_type=media)
+
+
+@app.websocket("/vnc")
+async def vnc_proxy(websocket: WebSocket):
+    """把 noVNC 的 WebSocket 流量橋接到本機 x11vnc（只監聽 127.0.0.1）。"""
+    offered = websocket.headers.get("sec-websocket-protocol", "")
+    protocols = [p.strip() for p in offered.split(",") if p.strip()]
+    subprotocol = "binary" if "binary" in protocols else (protocols[0] if protocols else None)
+    await websocket.accept(subprotocol=subprotocol)
+
+    if not await desktop_manager.ensure():
+        try:
+            await websocket.close(code=1011, reason="desktop unavailable")
+        except Exception:
+            pass
+        return
+
+    try:
+        reader, writer = await asyncio.open_connection("127.0.0.1", DESKTOP_VNC_PORT)
+    except OSError as exc:
+        log.warning("[desktop] VNC 連線失敗：%s", exc)
+        try:
+            await websocket.close(code=1011, reason="vnc unavailable")
+        except Exception:
+            pass
+        return
+
+    async def ws_to_tcp():
+        try:
+            while True:
+                message = await websocket.receive()
+                if message.get("type") == "websocket.disconnect":
+                    break
+                data = message.get("bytes")
+                if data is None:
+                    text = message.get("text")
+                    data = text.encode("utf-8") if text is not None else b""
+                if data:
+                    writer.write(data)
+                    await writer.drain()
+        except (WebSocketDisconnect, RuntimeError, OSError):
+            pass
+
+    async def tcp_to_ws():
+        try:
+            while True:
+                data = await reader.read(65536)
+                if not data:
+                    break
+                await websocket.send_bytes(data)
+        except (WebSocketDisconnect, RuntimeError, OSError):
+            pass
+
+    tasks = [asyncio.create_task(ws_to_tcp()), asyncio.create_task(tcp_to_ws())]
+    try:
+        _done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        for task in pending:
+            task.cancel()
+    finally:
+        for task in tasks:
+            task.cancel()
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except Exception:
+            pass
+        try:
+            await websocket.close()
+        except Exception:
+            pass
+
+
 @app.get("/api/sessions")
 async def api_sessions():
     """列出目前伺服器上的終端機工作階段（除錯／確認跨裝置是否共用）。"""
@@ -959,6 +1164,503 @@ async def run_installpi_script():
         return False
 
 
+# ──────────────────────────── 固定桌面分頁（Xvfb + LXDE + x11vnc）─────────────────
+# 這是一個「固定」分頁，和 tmux 終端機完全獨立：
+#   * 伺服器永遠維持恰好一個 Xvfb（:99）＋ 一個 LXDE session ＋ 一個 x11vnc
+#   * 瀏覽器只是透過 /vnc 這條 WebSocket 橋接到同一個桌面（可多台裝置同時觀看）
+#   * 關掉頁面、重新整理、或任何一個程序意外死亡，看門狗都會把桌面重新拉起來
+#   * 所有邏輯都包在 try/except 裡，桌面壞掉不會影響原本的 tmux 終端機分頁
+DESKTOP_ID = "desktop"
+DESKTOP_TITLE = "桌面 1（LXDE，共用）"
+DESKTOP_DISPLAY = os.environ.get("DESKTOP_DISPLAY", ":99")
+DESKTOP_GEOMETRY = os.environ.get("DESKTOP_GEOMETRY", "1440x900x24")
+DESKTOP_VNC_PORT = int(os.environ.get("DESKTOP_VNC_PORT", "5900"))
+DESKTOP_NOVNC_ROOT = os.environ.get("DESKTOP_NOVNC_ROOT", "/usr/share/novnc")
+DESKTOP_LOG = "/tmp/webterm-desktop.log"
+DESKTOP_APT_PACKAGES = "xvfb x11vnc lxde-core novnc x11-utils"
+DESKTOP_WATCHDOG = None
+
+DESKTOP_PAGE = r"""<!DOCTYPE html>
+<html lang="zh-TW">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>LXDE 桌面（共用）</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:100%;height:100%;overflow:hidden;background:#000;font-family:'Segoe UI',system-ui,sans-serif}
+#screen{width:100%;height:100%;outline:none;background:#000}
+#screen canvas{display:block;margin:auto}
+#bar{position:fixed;left:10px;top:10px;z-index:10;display:flex;align-items:center;gap:8px;
+     padding:6px 10px;border-radius:6px;background:#111c;color:#ddd;font-size:12px;
+     backdrop-filter:blur(4px);border:1px solid #ffffff22;pointer-events:none}
+#dot{width:8px;height:8px;border-radius:50%;background:#e0a800;flex:none}
+#dot.ok{background:#3fbf50}#dot.bad{background:#c0392b}
+#retry{pointer-events:auto;display:none;border:1px solid #ffffff33;background:#2d2d2d;color:#ddd;
+       border-radius:4px;padding:4px 9px;cursor:pointer;font-size:12px}
+#retry:hover{background:#3c3c3c;color:#fff}
+</style>
+</head>
+<body>
+<div id="screen" tabindex="0"></div>
+<div id="bar"><span id="dot"></span><span id="msg">正在連線到共用桌面…</span><button id="retry" type="button">重新連線</button></div>
+<script type="module">
+const screenEl = document.getElementById('screen');
+const dot = document.getElementById('dot');
+const msg = document.getElementById('msg');
+const retry = document.getElementById('retry');
+let rfb = null, delay = 800, disposed = false, connecting = false;
+
+function setState(state, text) {
+  dot.className = state;
+  msg.textContent = text;
+  retry.style.display = state === 'bad' ? 'inline-block' : 'none';
+}
+
+async function loadRFB() {
+  try { return (await import('/novnc/core/rfb.js')).default; }
+  catch (e) { return (await import('https://cdn.jsdelivr.net/gh/novnc/noVNC@v1.5.0/core/rfb.js')).default; }
+}
+
+function scheduleReconnect() {
+  if (disposed) return;
+  setState('bad', `桌面連線中斷，${(delay / 1000).toFixed(1)} 秒後自動重連…`);
+  setTimeout(connect, delay);
+  delay = Math.min(delay * 1.6, 8000);
+}
+
+async function connect() {
+  if (disposed || connecting) return;
+  connecting = true;
+  setState('', '正在連線到共用桌面…');
+  try {
+    if (rfb) { try { rfb.disconnect(); } catch (e) { /* ignore */ } rfb = null; }
+    const RFB = await loadRFB();
+    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const url = `${proto}//${location.host}/vnc`;
+    const client = new RFB(screenEl, url, {
+      shared: true,
+      scaleViewport: true,
+      resizeSession: false,
+      viewOnly: false,
+      clipViewport: false,
+      dragViewport: false,
+      background: '#000',
+    });
+    rfb = client;
+    client.addEventListener('connect', () => {
+      delay = 800;
+      connecting = false;
+      setState('ok', `已連線（${client._fbWidth || ''}x${client._fbHeight || ''}）`);
+      client.focus();
+    });
+    client.addEventListener('disconnect', () => {
+      if (rfb !== client) return;
+      connecting = false;
+      rfb = null;
+      try { client.disconnect(); } catch (e) { /* ignore */ }
+      scheduleReconnect();
+    });
+    client.addEventListener('securityfailure', e => {
+      if (rfb !== client) return;
+      connecting = false;
+      setState('bad', '桌面驗證失敗：' + ((e.detail && e.detail.reason) || ''));
+    });
+  } catch (err) {
+    connecting = false;
+    setState('bad', '無法載入桌面用戶端：' + err.message);
+    scheduleReconnect();
+  }
+}
+
+retry.onclick = () => { delay = 800; connect(); };
+screenEl.addEventListener('click', () => { if (rfb) rfb.focus(); });
+window.addEventListener('beforeunload', () => {
+  disposed = true;
+  try { if (rfb) rfb.disconnect(); } catch (e) { /* ignore */ }
+});
+connect();
+</script>
+</body>
+</html>"""
+
+
+def _desktop_port_open() -> bool:
+    try:
+        with socket.create_connection(("127.0.0.1", DESKTOP_VNC_PORT), timeout=0.4):
+            return True
+    except OSError:
+        return False
+
+
+def _desktop_binaries_present() -> bool:
+    if not (shutil.which("Xvfb") and shutil.which("x11vnc")):
+        return False
+    return any(shutil.which(x) for x in ("startlxde", "lxsession", "openbox"))
+
+
+class DesktopManager:
+    """維持唯一一個 Xvfb + LXDE + x11vnc；死了就補、重複就砍。"""
+
+    SESSION_NAMES = ("lxsession", "startlxde", "openbox", "lxpanel", "pcmanfm", "lxterminal")
+
+    def __init__(self):
+        self._lock = asyncio.Lock()
+        self.pids = {"xvfb": None, "session": None, "vnc": None}
+        self.started_at = 0.0
+        self.last_error = ""
+        self._logf = None
+        self._last_install = 0.0
+
+    # ── 基本工具 ──────────────────────────────────────────────
+    def _log(self, message: str, level: int = logging.INFO):
+        line = f"[desktop] {message}"
+        log.log(level, "%s", line)
+        try:
+            f = self._logfd()
+            if hasattr(f, "write"):
+                f.write(time.strftime("%Y-%m-%d %H:%M:%S ") + line + "\n")
+                f.flush()
+        except OSError:
+            pass
+
+    def _logfd(self):
+        if self._logf is None:
+            try:
+                self._logf = open(DESKTOP_LOG, "a", buffering=1)
+            except OSError:
+                self._logf = subprocess.DEVNULL
+        return self._logf
+
+    @staticmethod
+    def _pid_alive(pid) -> bool:
+        if not pid:
+            return False
+        try:
+            os.kill(int(pid), 0)
+            return True
+        except (ProcessLookupError, ValueError):
+            return False
+        except PermissionError:
+            return True
+
+    @staticmethod
+    def _cmdline(pid: int) -> str:
+        try:
+            with open(f"/proc/{pid}/cmdline", "rb") as f:
+                return f.read().replace(b"\0", b" ").decode("utf-8", "replace").strip()
+        except OSError:
+            return ""
+
+    def _has_display(self, pid: int) -> bool:
+        wanted = ("DISPLAY=" + DESKTOP_DISPLAY).encode()
+        try:
+            with open(f"/proc/{pid}/environ", "rb") as f:
+                return wanted in f.read().split(b"\0")
+        except OSError:
+            return False
+
+    def _env(self) -> dict:
+        env = os.environ.copy()
+        env["DISPLAY"] = DESKTOP_DISPLAY
+        env["XDG_SESSION_TYPE"] = "x11"
+        env["XDG_CURRENT_DESKTOP"] = "LXDE"
+        env["DESKTOP_SESSION"] = "LXDE"
+        env.pop("SESSION_MANAGER", None)
+        runtime = os.path.join("/tmp", f"xdg-runtime-{os.getuid()}")
+        try:
+            os.makedirs(runtime, mode=0o700, exist_ok=True)
+            os.chmod(runtime, 0o700)
+        except OSError:
+            pass
+        env["XDG_RUNTIME_DIR"] = runtime
+        return env
+
+    def _spawn(self, argv, env=None):
+        self._log("spawn: " + " ".join(argv))
+        return subprocess.Popen(
+            argv, env=env or self._env(),
+            stdin=subprocess.DEVNULL, stdout=self._logfd(), stderr=subprocess.STDOUT,
+            start_new_session=True, close_fds=True,
+        )
+
+    # ── 掃描／清理 ────────────────────────────────────────────
+    def _scan(self):
+        xvfb, vnc, session = [], [], []
+        try:
+            entries = os.listdir("/proc")
+        except OSError:
+            return xvfb, vnc, session
+        for entry in entries:
+            if not entry.isdigit():
+                continue
+            pid = int(entry)
+            if pid == os.getpid():
+                continue
+            cmd = self._cmdline(pid)
+            if not cmd:
+                continue
+            low = cmd.lower()
+            if "xvfb" in low and DESKTOP_DISPLAY in cmd:
+                xvfb.append(pid)
+            elif "x11vnc" in low and DESKTOP_DISPLAY in cmd:
+                vnc.append(pid)
+            elif any(name in low for name in self.SESSION_NAMES) and (
+                    DESKTOP_DISPLAY in cmd or self._has_display(pid)):
+                session.append(pid)
+        return xvfb, vnc, session
+
+    def _kill_pids(self, pids, sig=signal.SIGTERM):
+        for pid in pids:
+            if not self._pid_alive(pid):
+                continue
+            try:
+                pgid = os.getpgid(pid)
+                if pgid > 1 and pgid != os.getpgid(0):
+                    os.killpg(pgid, sig)
+                else:
+                    os.kill(pid, sig)
+            except (ProcessLookupError, PermissionError, OSError):
+                try:
+                    os.kill(pid, sig)
+                except OSError:
+                    pass
+
+    def _stop_all(self):
+        xvfb, vnc, session = self._scan()
+        pids = set(xvfb) | set(vnc) | set(session)
+        pids |= {p for p in self.pids.values() if p}
+        if pids:
+            self._log(f"停止桌面程序：{sorted(pids)}")
+            self._kill_pids(pids, signal.SIGTERM)
+            time.sleep(0.5)
+            self._kill_pids(pids, signal.SIGKILL)
+        self.pids = {"xvfb": None, "session": None, "vnc": None}
+
+    def _clean_display_files(self):
+        num = DESKTOP_DISPLAY.lstrip(":") or "99"
+        for path in (f"/tmp/.X{num}-lock", f"/tmp/.X11-unix/X{num}"):
+            try:
+                os.remove(path)
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                self._log(f"無法移除 {path}: {exc}", logging.WARNING)
+
+    def _display_socket(self) -> str:
+        num = DESKTOP_DISPLAY.lstrip(":") or "99"
+        return f"/tmp/.X11-unix/X{num}"
+
+    def _healthy(self) -> bool:
+        return (
+            _desktop_port_open()
+            and all(self._pid_alive(self.pids[k]) for k in ("xvfb", "session", "vnc"))
+            and os.path.exists(self._display_socket())
+        )
+
+    # ── 啟動各元件 ────────────────────────────────────────────
+    async def _wait_for(self, predicate, timeout: float) -> bool:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            try:
+                if predicate():
+                    return True
+            except Exception:
+                pass
+            await asyncio.sleep(0.2)
+        return False
+
+    async def _start_xvfb(self) -> bool:
+        self._log(f"啟動 Xvfb {DESKTOP_DISPLAY}（{DESKTOP_GEOMETRY}）")
+        try:
+            proc = self._spawn([
+                "Xvfb", DESKTOP_DISPLAY, "-screen", "0", DESKTOP_GEOMETRY,
+                "-nolisten", "tcp", "-ac", "-noreset",
+            ])
+        except OSError as exc:
+            self.last_error = f"無法啟動 Xvfb：{exc}"
+            self._log(self.last_error, logging.ERROR)
+            return False
+        self.pids["xvfb"] = proc.pid
+        ok = await self._wait_for(
+            lambda: os.path.exists(self._display_socket()) and self._pid_alive(proc.pid), 8)
+        if not ok:
+            self.last_error = f"Xvfb 啟動失敗（returncode={proc.poll()}）"
+            self._log(self.last_error, logging.ERROR)
+            return False
+        return True
+
+    async def _start_session(self) -> bool:
+        last_error = "找不到 startlxde / lxsession / openbox"
+        for launcher in ("startlxde", "lxsession", "openbox"):
+            path = shutil.which(launcher)
+            if not path:
+                continue
+            self._log(f"啟動 LXDE session：{launcher}")
+            try:
+                proc = self._spawn([path])
+            except OSError as exc:
+                last_error = f"{launcher} 啟動失敗：{exc}"
+                continue
+            await asyncio.sleep(1.2)
+            pid = proc.pid if self._pid_alive(proc.pid) else None
+            if not pid:
+                _x, _v, found = self._scan()
+                pid = found[0] if found else None
+            if pid:
+                self.pids["session"] = pid
+                self._log(f"LXDE session 就緒（{launcher}，pid {pid}）")
+                return True
+            last_error = f"{launcher} 啟動後立即結束（returncode={proc.poll()}）"
+            self._log(last_error, logging.WARNING)
+        self.last_error = last_error
+        return False
+
+    async def _start_vnc(self) -> bool:
+        self._log(f"啟動 x11vnc（127.0.0.1:{DESKTOP_VNC_PORT}）")
+        try:
+            proc = self._spawn([
+                "x11vnc", "-display", DESKTOP_DISPLAY,
+                "-rfbport", str(DESKTOP_VNC_PORT), "-localhost",
+                "-forever", "-shared", "-nopw", "-noxdamage",
+                "-repeat", "-wait", "10", "-defer", "10", "-no6",
+            ])
+        except OSError as exc:
+            self.last_error = f"無法啟動 x11vnc：{exc}"
+            self._log(self.last_error, logging.ERROR)
+            return False
+        self.pids["vnc"] = proc.pid
+        ok = await self._wait_for(
+            lambda: _desktop_port_open() and self._pid_alive(proc.pid), 10)
+        if not ok:
+            self.last_error = f"x11vnc 啟動失敗（returncode={proc.poll()}）"
+            self._log(self.last_error, logging.ERROR)
+            self.pids["vnc"] = None
+            self._kill_pids([proc.pid], signal.SIGKILL)
+            return False
+        return True
+
+    async def _full_restart(self) -> bool:
+        await asyncio.to_thread(self._stop_all)
+        self._clean_display_files()
+        if not await self._start_xvfb():
+            return False
+        if not await self._start_session():
+            return False
+        if not await self._start_vnc():
+            return False
+        self.started_at = time.time()
+        self.last_error = ""
+        self._log("桌面已就緒（Xvfb + LXDE + x11vnc）")
+        return self._healthy()
+
+    async def _install_binaries(self) -> bool:
+        now = time.time()
+        if now - self._last_install < 300:
+            return False
+        self._last_install = now
+        self._log("缺少桌面套件，嘗試安裝：" + DESKTOP_APT_PACKAGES, logging.WARNING)
+        cmd = ("DEBIAN_FRONTEND=noninteractive apt-get update -y && "
+               "DEBIAN_FRONTEND=noninteractive apt-get install -y "
+               "--no-install-recommends " + DESKTOP_APT_PACKAGES)
+        for prefix in ("", "sudo "):
+            try:
+                rc, _out, err = await _run(prefix + cmd)
+            except Exception as exc:
+                self._log(f"桌面套件安裝例外：{exc}", logging.WARNING)
+                continue
+            if rc == 0 and _desktop_binaries_present():
+                self._log("桌面套件安裝完成")
+                return True
+            self._log(f"桌面套件安裝失敗（prefix={prefix!r}）：{(err or '')[-300:]}", logging.WARNING)
+        return False
+
+    async def ensure(self) -> bool:
+        async with self._lock:
+            if self._healthy():
+                return True
+            if not _desktop_binaries_present():
+                ok = await self._install_binaries()
+                if not ok:
+                    self.last_error = "缺少 Xvfb / x11vnc / LXDE 套件"
+                    return False
+            self._log("桌面未就緒，開始檢查與修復")
+            xvfb, vnc, session = await asyncio.to_thread(self._scan)
+
+            if len(xvfb) > 1:
+                self._kill_pids(xvfb[1:], signal.SIGKILL)
+                xvfb = xvfb[:1]
+            if len(vnc) > 1:
+                self._kill_pids(vnc[1:], signal.SIGKILL)
+                vnc = vnc[:1]
+
+            if not xvfb or not self._pid_alive(xvfb[0]):
+                self._log("找不到 Xvfb，重建整個桌面")
+                return await self._full_restart()
+            self.pids["xvfb"] = xvfb[0]
+            if not os.path.exists(self._display_socket()):
+                self._log("X11 socket 不存在，重建整個桌面")
+                return await self._full_restart()
+
+            if session:
+                self.pids["session"] = session[0]
+            else:
+                if not await self._start_session():
+                    return False
+
+            if vnc and not _desktop_port_open():
+                self._kill_pids(vnc, signal.SIGKILL)
+                vnc = []
+            if vnc:
+                self.pids["vnc"] = vnc[0]
+            else:
+                if not await self._start_vnc():
+                    return False
+
+            if not self._healthy():
+                self.last_error = "桌面元件存在但健康檢查未通過"
+                return False
+            self.started_at = self.started_at or time.time()
+            self.last_error = ""
+            self._log("桌面已修復並就緒")
+            return True
+
+    async def restart(self) -> bool:
+        async with self._lock:
+            self._log("收到重新啟動桌面要求")
+            return await self._full_restart()
+
+    def status(self) -> dict:
+        alive = self._healthy()
+        return {
+            "id": DESKTOP_ID,
+            "title": DESKTOP_TITLE,
+            "alive": alive,
+            "display": DESKTOP_DISPLAY,
+            "geometry": DESKTOP_GEOMETRY,
+            "vnc_port": DESKTOP_VNC_PORT,
+            "pids": dict(self.pids),
+            "started_at": round(self.started_at, 3) if self.started_at else None,
+            "last_error": self.last_error,
+            "novnc": os.path.isdir(DESKTOP_NOVNC_ROOT),
+        }
+
+
+desktop_manager = DesktopManager()
+
+
+async def desktop_watchdog():
+    """每 3 秒確認桌面還在，且永遠只有一份；不影響終端機流程。"""
+    await asyncio.sleep(1)
+    while True:
+        ok = False
+        try:
+            ok = await desktop_manager.ensure()
+        except Exception as exc:
+            log.warning("[desktop] 看門狗例外（終端機不受影響）：%s", exc)
+        await asyncio.sleep(3 if ok else 5)
+
+
 @spaces.GPU(duration=1, queue=False)
 def dummy_gpu():
     """空函數，僅用於讓平台識別 GPU 裝飾器（若無 GPU 可忽略）。"""
@@ -967,10 +1669,17 @@ def dummy_gpu():
 
 @app.on_event("startup")
 async def startup_event():
+    global DESKTOP_WATCHDOG
     _load_tabs()
     _write_shell_launcher()
     await ensure_tmux()
     _reconcile_tmux()
+    # 固定桌面分頁（Xvfb + LXDE + x11vnc）。獨立背景任務，失敗不影響終端機。
+    try:
+        if DESKTOP_WATCHDOG is None or DESKTOP_WATCHDOG.done():
+            DESKTOP_WATCHDOG = asyncio.create_task(desktop_watchdog())
+    except Exception as _desktop_err:  # pragma: no cover
+        log.warning("[desktop] 無法啟動看門狗（終端機照常運作）：%r", _desktop_err)
     dummy_gpu()
     if SKIP_INSTALL:
         log.info("WEBTERM_SKIP_INSTALL=1：跳過 opencode / 編輯器安裝")

packages.txt

@@ -1 +1,6 @@
 tmux
+xvfb
+x11vnc
+lxde-core
+novnc
+x11-utils