cdp-tunnel 3.4.0 → 3.6.0

package/server/modules/port-pool.js

@@ -24,9 +24,10 @@ class PortPoolManager {
     this.idCounter = 0; // 全局唯一 id 计数器  // 现有 proxy 的引用（拿 plugin 连接）
     this.createServers = [];      // [http.Server] 每个 create 端口一个
     this.createWss = [];          // [WebSocket.Server] 每个 create 端口一个
-    this.portSessions = [];       // [PortSession] 每个 create 端口一个
+    this.portSessions = [];       // [PortSession] 每个 create 端口一个（端口池端口用）
+    this.keySessions = new Map(); // apiKey → PortSession（主端口按 key 隔离，一 key 一 session）
+    this._keyToPortIndex = new Map();  // apiKey → portIndex（key 到端口池端口的映射）
     this.takeoverServer = null;
-    this.takeoverWss = null;
     this.targetToPort = new Map();   // targetId → portIndex（事件路由用）
     this.sessionToPort = new Map();  // CDP sessionId → portIndex
   }
@@ -51,16 +52,57 @@ class PortPoolManager {
   };
 
   start() {
-    // 启动 create 端口（9222-9230）
+    // 端口池第 0 个端口 = 主端口（9221），复用主 server 的 /client 入口（不另开 http.Server）
+    this._setupMainPortSession(0, CONFIG.PORT);
+
+    // 启动 create 端口（9231-9239），portIndex 从 1 开始（0 留给主端口）
     for (let i = 0; i < CONFIG.POOL_SIZE; i++) {
       const port = CONFIG.POOL_START + i;
-      this._startCreatePort(i, port);
+      this._startCreatePort(i + 1, port);
     }
 
     // 启动 takeover 端口（9220）
     this._startTakeoverPort();
 
-    console.log(`\n[PORT POOL] Started: takeover=${CONFIG.POOL_TAKEOVER_PORT}, create=${CONFIG.POOL_START}-${CONFIG.POOL_START + CONFIG.POOL_SIZE - 1}`);
+    console.log(`\n[PORT POOL] Started: takeover=${CONFIG.POOL_TAKEOVER_PORT}, create=${CONFIG.PORT}(main) + ${CONFIG.POOL_START}-${CONFIG.POOL_START + CONFIG.POOL_SIZE - 1}`);
+  }
+
+  /**
+   * 主端口（9221）作为端口池第 0 个端口：只建 PortSession，不开 http.Server。
+   * 9221 的 HTTP 和 upgrade 由主 proxy-server 处理，但走端口池的隔离逻辑。
+   */
+  _setupMainPortSession(portIndex, port) {
+    const session = new PortPoolManager.PortSession(portIndex, port);
+    this.portSessions[portIndex] = session;
+    console.log(`[CREATE PORT ${portIndex}] Main port ${port} (reuses main server)`);
+  }
+
+  /**
+   * 按 key 获取/分配独立的端口池端口 session（一 key 一 session，完全隔离）
+   * 主端口(9221)的 /client 连接按 key 路由到端口池端口(9231+)的 session。
+   * 复用端口池端口的全部隔离逻辑（targetIds/事件路由/分组），不动 handlePluginMessage。
+   *
+   * @returns PortSession 或 null（无可用端口时）
+   */
+  _getKeySession(apiKey) {
+    if (!this._keyToPortIndex) this._keyToPortIndex = new Map();
+    // 已分配过 → 直接返回
+    if (this._keyToPortIndex.has(apiKey)) {
+      return this.portSessions[this._keyToPortIndex.get(apiKey)];
+    }
+    // 找一个未分配的端口池端口（portIndex >= 1）
+    const usedIndexes = new Set(this._keyToPortIndex.values());
+    for (let i = 1; i < this.portSessions.length; i++) {
+      if (this.portSessions[i] && !usedIndexes.has(i)) {
+        this._keyToPortIndex.set(apiKey, i);
+        this.portSessions[i].apiKey = apiKey;  // 标记这个 session 属于哪个 key
+        console.log(`[KEY SESSION] key=${apiKey.slice(0, 16)}... → portIndex=${i} (port ${this.portSessions[i].port})`);
+        return this.portSessions[i];
+      }
+    }
+    // 端口池满（所有端口都已分配）→ 复用主端口 session（降级，不隔离）
+    console.warn(`[KEY SESSION] port pool exhausted, key=${apiKey.slice(0, 16)}... falling back to shared main session`);
+    return null;
   }
 
   _startCreatePort(portIndex, port) {
@@ -140,7 +182,7 @@ class PortPoolManager {
     const url = new URL(req.url, `http://localhost:${session.port}`);
     const path = url.pathname;
 
-    if (path === '/json/version') {
+    if (path === '/json/version' || path === '/json/version/') {
       // 返回版本信息，webSocketDebuggerUrl 指向当前端口
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({
@@ -152,7 +194,7 @@ class PortPoolManager {
       return;
     }
 
-    if (path === '/json' || path === '/json/list') {
+    if (path === '/json' || path === '/json/' || path === '/json/list' || path === '/json/list/') {
       // 返回这个端口创建的 tab 列表
       // 从 session.targetIds 构建（这些是 createTarget 时记录的）
       const targets = [];
@@ -184,11 +226,40 @@ class PortPoolManager {
    * Client WebSocket 连接处理
    */
   _handleClientConnect(ws, req, session) {
+    // 鉴权：从 URL 提取 key，找到对应的 plugin（一 key 一浏览器）
+    let apiKey = null;
+    try {
+      const url = new URL(req.url, `http://localhost:${session.port}`);
+      apiKey = url.searchParams.get('key') || null;
+    } catch {}
+
+    // 如果有 SaaS 鉴权（HAS_SAAS），校验 key
+    if (this.mainProxy.validateClientKey) {
+      const valid = this.mainProxy.validateClientKey(apiKey);
+      if (!valid) {
+        ws.close(4001, 'Invalid or missing API key');
+        return;
+      }
+    }
+
+    ws.apiKey = apiKey;  // 记录到 ws，后续命令转发时带上
+
+    // 主端口（portIndex === 0）：按 key 路由到独立的端口池端口 session
+    // 每个 key 分配一个端口池端口（portSessions[1..N]），实现完全隔离
+    //   - targetIds 独立（listtabs 只看自己的）
+    //   - 事件路由用现有 targetToPort（按 portIndex，不动 handlePluginMessage）
+    //   - 分组名按 key（阶段1已实现）
+    // 无 key 或端口池满时，fallback 到主端口共享 session（兼容）
+    if (session.portIndex === 0 && apiKey) {
+      const keySession = this._getKeySession(apiKey);
+      if (keySession) session = keySession;
+    }
+
     session.clients.add(ws);
 
-    const pluginWs = this.mainProxy.getPluginConnection();
+    const pluginWs = this.mainProxy.getPluginConnection(apiKey);
     if (!pluginWs) {
-      ws.close(1011, 'No extension connected');
+      ws.close(1011, apiKey ? 'No browser connected for this key' : 'No extension connected');
       return;
     }
 
@@ -209,12 +280,15 @@ class PortPoolManager {
 
     // 通知扩展有 client 连接（带端口号作为分组标识）
     // clientId 固定为 pool_{port}，让扩展为每个端口建一个独立分组
+    // __groupName 带 key 名称，让扩展用 key 名称命名 Chrome 分组（一眼看出是谁的浏览器）
     const poolClientId = `pool_${session.port}`;
+    pluginWs._lastPoolClientId = poolClientId;
     pluginWs.send(JSON.stringify({
       type: 'client-connected',
       clientId: poolClientId,
       __mode: 'create',
-      __connectionTag: String(session.port)
+      __connectionTag: String(session.port),
+      __groupName: pluginWs.apiKeyName || null
     }));
 
     // 合成输入命令需要 ensureVisible（和 forward.js 的逻辑一致）
@@ -357,13 +431,10 @@ class PortPoolManager {
         const closedTid = pending.params.targetId;
         session.targetIds.delete(closedTid);
         session.targetUrls.delete(closedTid);
-        session.attachedTargets.delete(closedTid);
         this.targetToPort.delete(closedTid);
-        // 清理 sessionId → client 映射（找到该 targetId 对应的 session 并删除）
-        for (const [sid, ws] of session.sessionToClient.entries()) {
-          // 通过 targetId 反查 sessionId（targetCreated 事件建立的映射）
-          // 这里简单清理所有已关闭 target 的 session
-        }
+        // sessionId → client 映射在 targetCreated/attachedToTarget 时建立，
+        // 但端口池层不维护 sessionId ↔ targetId 反查表，故此处不清理 sessionToClient
+        // （session 级隔离下，client 断开时整体清理即可）
       }
 
       // 恢复原始 id，发给发起请求的 client
@@ -382,11 +453,36 @@ class PortPoolManager {
 
     // 2. 事件消息（无 id）：按 targetId 或 sessionId 路由
     if (msg.method && msg.params) {
-      // 诊断：打印所有未匹配到的事件
+      // 提取 targetId（attachedToTarget 的在 params.targetInfo.targetId）
       let targetId = null;
       if (msg.params.targetId) targetId = msg.params.targetId;
       else if (msg.params.targetInfo && msg.params.targetInfo.targetId) targetId = msg.params.targetInfo.targetId;
 
+      // 关键：attachedToTarget 事件带 sessionId 时，必须注册 sessionToPort，
+      // 否则后续该 session 的 Page.*/Runtime.* 事件无法路由（Playwright evaluate 会卡死）。
+      // 这一步独立于 targetId 是否已知——auto-attach 场景下 targetId 可能尚未在 targetToPort 注册。
+      // 归属端口：优先用 targetId 查 targetToPort；查不到时，找唯一一个 pendingCreate 的端口，
+      // 再查不到则归到端口 0（POOL_SIZE=0 时只有端口 0；多端口时靠 createTarget 响应补注册 targetId→port）
+      if (msg.method === 'Target.attachedToTarget' && msg.params.sessionId) {
+        let portIdx = this.targetToPort.get(targetId);
+        if (portIdx === undefined) {
+          // 找 pendingCreate 的端口（createTarget 响应还没到，但事件先到了）
+          for (let pi = 0; pi < this.portSessions.length; pi++) {
+            if (this.portSessions[pi] && this.portSessions[pi].pendingCreate) { portIdx = pi; break; }
+          }
+        }
+        if (portIdx === undefined) portIdx = 0;  // 兜底：归到主端口
+        const sess = this.portSessions[portIdx];
+        if (sess) {
+          if (targetId) {
+            sess.targetIds.add(targetId);
+            this.targetToPort.set(targetId, portIdx);
+          }
+          this.sessionToPort.set(msg.params.sessionId, portIdx);
+          sess.sessionToClient.delete(msg.params.sessionId);  // auto-attach：广播
+        }
+      }
+
       if (targetId) {
         const portIndex = this.targetToPort.get(targetId);
         if (portIndex !== undefined) {
@@ -406,13 +502,37 @@ class PortPoolManager {
               sess.targetUrls.set(targetId, 'about:blank');
               this.targetToPort.set(targetId, pi);
               if (msg.method === 'Target.attachedToTarget') sess.pendingCreate = false;
+              // attachedToTarget 事件带 sessionId：必须注册 sessionToPort/sessionToClient，
+              // 否则后续 Page.*/Runtime.* 等 session 事件无法路由（Playwright newPage 会卡死）
+              if (msg.method === 'Target.attachedToTarget' && msg.params && msg.params.sessionId) {
+                this.sessionToPort.set(msg.params.sessionId, pi);
+                // auto-attach 场景无特定发起 client，广播给该端口所有 client
+                sess.sessionToClient.delete(msg.params.sessionId);
+              }
               this._broadcastToPort(pi, msg);
               return true;
             }
           }
-          // pendingCreate 没匹配到——记录但不广播（避免 sessionId 串）
-          // targetId 会在 createTarget 响应时注册
-          return true;
+          // pendingCreate 没匹配到——仍需处理 setAutoAttach 自动触发的 attachedToTarget
+          // （Playwright/Puppeteer 的 newPage 走的就是这条路径，不走 createTarget lock）
+          // 用 targetToPort 找到归属端口；若 targetId 也未知，广播给所有端口（保守）
+          if (msg.method === 'Target.attachedToTarget' && msg.params && msg.params.sessionId) {
+            const knownPort = this.targetToPort.get(targetId);
+            const portIdx = knownPort !== undefined ? knownPort : 0;
+            const sess = this.portSessions[portIdx];
+            if (sess) {
+              sess.targetIds.add(targetId);
+              this.targetToPort.set(targetId, portIdx);
+              this.sessionToPort.set(msg.params.sessionId, portIdx);
+              sess.sessionToClient.delete(msg.params.sessionId);  // auto-attach：广播
+              this._broadcastToPort(portIdx, msg);
+            }
+            return true;
+          }
+          // targetCreated 无 pendingCreate 且非 attachedToTarget：记录但不广播
+          if (msg.method === 'Target.targetCreated') {
+            return true;
+          }
         }
       }
 
@@ -422,10 +542,13 @@ class PortPoolManager {
         if (portIndex !== undefined) {
           const sess = this.portSessions[portIndex];
           if (sess) {
-            // 精确路由：只发给持有这个 sessionId 的 client（不广播）
+            // 精确路由：有特定 owner 就单播，否则广播给该端口所有 client
+            // （auto-attach 场景无 owner，Playwright/Puppeteer 需要 Page.* 事件）
             const ownerWs = sess.sessionToClient.get(msg.sessionId);
             if (ownerWs && ownerWs.readyState === WebSocket.OPEN) {
               ownerWs.send(JSON.stringify(msg));
+            } else {
+              this._broadcastToPort(portIndex, msg);
             }
             return true;
           }

package/server/proxy-server.js

@@ -23,8 +23,11 @@ const TAKEOVER_PORT = CONFIG.TAKEOVER_PORT;
 let portPool = null;
 const { logCDP, logEvent, clearLog, logStatus, logConnectionEvent, flushAllLogs, logDisconnect } = require('./modules/logger');
 
+let validateApiKey = null;
+let saasAuth = null;  // 完整 SaaS auth 模块（createApiKey/listApiKeys/revokeApiKey）
 try {
-    const { validateApiKey } = require('./saas/auth');
+    saasAuth = require('./saas/auth');
+    validateApiKey = saasAuth.validateApiKey;
     var HAS_SAAS = true;
 } catch (e) {
     var HAS_SAAS = false;
@@ -317,9 +320,280 @@ function resolvePluginFromUrl(url) {
     return pluginConnections.values().next().value || null;
 }
 
+// ===== 管理控制台 API =====
+// 鉴权：ADMIN_TOKEN 环境变量（Bearer token 或 query ?token=）
+// 未设 ADMIN_TOKEN 时只允许 localhost（开发友好）
+function checkAdminAuth(req, url) {
+    const token = process.env.ADMIN_TOKEN;
+    if (!token) {
+        // 未设 token：只允许 localhost
+        const ip = req.socket.remoteAddress;
+        return ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+    }
+    // 设了 token：校验 Bearer 或 query
+    const authHeader = req.headers.authorization || '';
+    const bearer = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null;
+    const queryToken = url.searchParams.get('token');
+    return bearer === token || queryToken === token;
+}
+
+function adminJson(res, code, data) {
+    res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(data));
+}
+
+async function readBody(req) {
+    return new Promise(resolve => {
+        let d = ''; req.on('data', c => d += c);
+        req.on('end', () => { try { resolve(JSON.parse(d)); } catch { resolve({}); } });
+    });
+}
+
+async function handleAdminApi(req, res, url) {
+    const path = url.pathname.replace('/admin/api/', '');
+    const method = req.method;
+
+    if (!checkAdminAuth(req, url)) {
+        return adminJson(res, 401, { error: 'Unauthorized. Set ADMIN_TOKEN env or access from localhost.' });
+    }
+
+    try {
+        // 浏览器列表
+        if (path === 'browsers' && method === 'GET') {
+            const browsers = [];
+            for (const pluginWs of pluginConnections) {
+                if (pluginWs.readyState !== WebSocket.OPEN) continue;
+                const ns = getNamespace(pluginWs);
+                browsers.push({
+                    pluginId: pluginWs.pluginId,
+                    pluginName: pluginWs.pluginName || 'My Browser',
+                    userId: pluginWs.userId || null,
+                    apiKeyId: pluginWs.apiKeyId || null,
+                    browserName: ns.cachedBrowserVersion?.Browser || 'Unknown',
+                    userAgent: ns.cachedBrowserVersion?.['User-Agent'] || '',
+                    targets: ns.cachedTargets?.length || 0,
+                    connected: true,
+                    connectedAt: pluginWs.connectedAt,
+                    extVersion: pluginWs.extVersion || 'unknown'
+                });
+            }
+            return adminJson(res, 200, browsers);
+        }
+
+        // key 管理（需要 SaaS）
+        if (path === 'keys' && method === 'GET') {
+            if (!saasAuth) return adminJson(res, 503, { error: 'SaaS not available' });
+            return adminJson(res, 200, saasAuth.listApiKeys('builtin-admin'));
+        }
+        if (path === 'keys' && method === 'POST') {
+            if (!saasAuth) return adminJson(res, 503, { error: 'SaaS not available' });
+            const body = await readBody(req);
+            const name = body.name || ('browser-' + Date.now().toString(36));
+            const result = saasAuth.createApiKey('builtin-admin', name);
+            const port = PORT;
+            return adminJson(res, 200, {
+                ...result,
+                pluginUrl: `ws://localhost:${port}/plugin?key=${result.key}`,
+                clientUrl: `ws://localhost:${port}/client?key=${result.key}`
+            });
+        }
+        if (path.startsWith('keys/') && method === 'DELETE') {
+            if (!saasAuth) return adminJson(res, 503, { error: 'SaaS not available' });
+            const keyId = path.split('/')[1];
+            const result = saasAuth.revokeApiKey(keyId, 'builtin-admin');
+            return adminJson(res, result.changes > 0 ? 200 : 404, { ok: result.changes > 0, changes: result.changes });
+        }
+
+        // CDP 快捷操作（通过 pluginId 直接连已在线浏览器）
+        if (path.startsWith('cdp/') && method === 'POST') {
+            const body = await readBody(req);
+            if (!body.pluginId) return adminJson(res, 400, { error: 'Missing pluginId' });
+            const result = await execCdpViaPlugin(body.pluginId, body);
+            return adminJson(res, result.error ? 500 : 200, result);
+        }
+
+        return adminJson(res, 404, { error: 'Not found: ' + path });
+    } catch (e) {
+        return adminJson(res, 500, { error: e.message });
+    }
+}
+
+// 通过 pluginId 走端口池 /client 路径执行 CDP 命令（复用完整分组/session 路由逻辑）
+async function execCdpViaPlugin(pluginId, params) {
+    const action = params.action || 'evaluate';
+    // 找到 pluginId 对应的 plugin 连接
+    let pluginWs = null;
+    for (const ws of pluginConnections) {
+        if (ws.readyState === WebSocket.OPEN && ws.pluginId === pluginId) { pluginWs = ws; break; }
+    }
+    if (!pluginWs) return { error: 'Browser not found or offline' };
+
+    // closebrowser 特殊处理：不走 /client（会被 Browser.close 断开），
+    // 直接用 pluginWs 发 client-disconnected + closeTarget
+    if (action === 'closebrowser') {
+        // 从 apiKey 找到对应的 key session 的端口，拿到正确的 clientId
+        let clientId = `pool_${PORT}`;  // fallback
+        if (pluginWs.apiKey && portPool && portPool._keyToPortIndex) {
+            const portIdx = portPool._keyToPortIndex.get(pluginWs.apiKey);
+            if (portIdx !== undefined && portPool.portSessions[portIdx]) {
+                clientId = `pool_${portPool.portSessions[portIdx].port}`;
+            }
+        }
+        // 发 client-disconnected 让扩展关分组 + 关 tab
+        try {
+            pluginWs.send(JSON.stringify({ type: 'client-disconnected', clientId }));
+        } catch (e) {}
+        // 清理 key session（让下次连接重新分配）
+        if (pluginWs.apiKey && portPool) {
+            portPool.keySessions.delete(pluginWs.apiKey);
+            if (portPool._keyToPortIndex) portPool._keyToPortIndex.delete(pluginWs.apiKey);
+        }
+        return { closed: true };
+    }
+
+    const apiKey = pluginWs.apiKey;
+    if (!apiKey) return { error: 'Browser has no API key (not connected via /plugin?key=)' };
+
+    // 内部连 /client?key=xxx，走端口池完整路径（建组 + session 路由 + 分组）
+    const port = PORT;
+    return new Promise((resolve) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${port}/client?key=${apiKey}`);
+        const pending = new Map(); let id = 1; let sessionId = null;
+        const timeout = setTimeout(() => { try { ws.close(); } catch {}; resolve({ error: 'Timeout' }); }, 15000);
+
+        function cdp(method, p = {}, sid) {
+            return new Promise((res, rej) => {
+                const i = id++; pending.set(i, { resolve: res, reject: rej });
+                const o = { id: i, method, params: p };
+                if (sid) o.sessionId = sid; else if (sessionId) o.sessionId = sessionId;
+                ws.send(JSON.stringify(o));
+                setTimeout(() => { if (pending.has(i)) { pending.delete(i); rej(new Error('CDP timeout: ' + method)); } }, 12000);
+            });
+        }
+
+        function finish(result) { clearTimeout(timeout); try { ws.close(); } catch {}; resolve(result); }
+
+        ws.on('message', async (data) => {
+            const m = JSON.parse(data.toString());
+            if (m.id && pending.has(m.id)) {
+                const { resolve: r, reject: rj } = pending.get(m.id); pending.delete(m.id);
+                m.error ? rj(new Error(JSON.stringify(m.error))) : r(m.result);
+                return;
+            }
+            // attachedToTarget 事件 → 记 sessionId
+            if (m.method === 'Target.attachedToTarget' && m.params?.sessionId && !sessionId) {
+                sessionId = m.params.sessionId;
+                try {
+                    if (action === 'evaluate') {
+                        await cdp('Runtime.enable', {}, sessionId);
+                        const ev = await cdp('Runtime.evaluate', { expression: params.expression || 'document.title', returnByValue: true }, sessionId);
+                        finish({ result: ev.result.value });
+                    } else if (action === 'screenshot') {
+                        await cdp('Page.enable', {}, sessionId);
+                        const shot = await cdp('Page.captureScreenshot', { format: 'png' }, sessionId);
+                        finish({ screenshot: shot.data });
+                    }
+                } catch (e) { finish({ error: e.message }); }
+            }
+        });
+
+        ws.on('open', async () => {
+            try {
+                // listtabs：走 /client 路径，getTargets 被端口池按 key 自动过滤
+                if (action === 'listtabs') {
+                    await cdp('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+                    const tg = await cdp('Target.getTargets');
+                    const tabs = (tg?.targetInfos || [])
+                        .filter(t => t.type === 'page')
+                        .map(t => ({ targetId: t.targetId, url: t.url, title: t.title || '', attached: t.attached }));
+                    finish({ tabs });
+                }
+                // closetab：关闭指定 targetId
+                else if (action === 'closetab') {
+                    await cdp('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+                    await cdp('Target.closeTarget', { targetId: params.targetId });
+                    finish({ closed: true, targetId: params.targetId });
+                }
+                // switchtab：切换到指定 targetId（bringToFront）
+                else if (action === 'switchtab') {
+                    await cdp('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+                    const at = await cdp('Target.attachToTarget', { targetId: params.targetId, flatten: true });
+                    if (at.sessionId) {
+                        await cdp('Page.enable', {}, at.sessionId);
+                        await cdp('Page.bringToFront', {}, at.sessionId);
+                    }
+                    finish({ switched: true, targetId: params.targetId });
+                }
+                else if (action === 'newtab') {
+                    await cdp('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+                    const created = await cdp('Target.createTarget', { url: params.url || 'about:blank' });
+                    finish({ targetId: created.targetId });
+                } else {
+                    // evaluate/screenshot：直接 getTargets + attach（不等 setAutoAttach 事件，避免超时）
+                    await cdp('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+                    const tg = await cdp('Target.getTargets');
+                    let page = (tg.targetInfos || []).find(t => t.type === 'page');
+                    if (!page) {
+                        const created = await cdp('Target.createTarget', { url: 'about:blank' });
+                        page = { targetId: created.targetId };
+                    }
+                    // attach 后等 attachedToTarget 事件触发 evaluate/screenshot
+                    // 如果事件没来，1 秒后用手动方式（attach 响应里的 sessionId）
+                    const at = await cdp('Target.attachToTarget', { targetId: page.targetId, flatten: true });
+                    // 如果事件路径没处理，手动执行
+                    setTimeout(async () => {
+                        if (sessionId || !at.sessionId) return;
+                        sessionId = at.sessionId;
+                        try {
+                            if (action === 'evaluate') {
+                                await cdp('Runtime.enable', {}, sessionId);
+                                const ev = await cdp('Runtime.evaluate', { expression: params.expression || 'document.title', returnByValue: true }, sessionId);
+                                finish({ result: ev.result.value });
+                            } else if (action === 'screenshot') {
+                                await cdp('Page.enable', {}, sessionId);
+                                const shot = await cdp('Page.captureScreenshot', { format: 'png' }, sessionId);
+                                finish({ screenshot: shot.data });
+                            }
+                        } catch (e) { finish({ error: e.message }); }
+                    }, 1000);
+                }
+            } catch (e) { finish({ error: e.message }); }
+        });
+
+        ws.on('error', e => { clearTimeout(timeout); resolve({ error: e.message }); });
+    });
+}
+
 async function handleHttpRequest(req, res) {
     const url = new URL(req.url, `http://localhost:${PORT}`);
-    
+
+    // 主端口（9221）的 /json/version、/json/list 委托端口池 session[0]，
+    // 语义与 9231-9239 一致：只返回本端口（pool_9221）创建的 target。
+    // takeover（9220，req._takeoverMode=true）不走这条——它要看用户全部 tab。
+    if (!req._takeoverMode && portPool && portPool.portSessions[0] &&
+        (url.pathname === '/json/version' || url.pathname === '/json/version/' ||
+         url.pathname === '/json' || url.pathname === '/json/' ||
+         url.pathname === '/json/list' || url.pathname === '/json/list/' ||
+         url.pathname === '/json/new')) {
+        portPool._handleHttp(req, res, portPool.portSessions[0]);
+        return;
+    }
+
+    // 管理控制台：/admin 返回页面，/admin/api/* 返回 JSON
+    if (url.pathname === '/admin' || url.pathname === '/admin/') {
+        try {
+            const html = fs.readFileSync(path.join(__dirname, 'admin-console.html'), 'utf8');
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(html);
+        } catch (e) {
+            res.writeHead(500); res.end('Admin console not found: ' + e.message);
+        }
+        return;
+    }
+    if (url.pathname.startsWith('/admin/api/')) {
+        return handleAdminApi(req, res, url);
+    }
+
     if (url.pathname === '/json/browsers' || url.pathname === '/json/browsers/') {
         const browsers = [];
         for (const pluginWs of pluginConnections) {
@@ -465,6 +739,19 @@ wss.on('connection', (ws, req) => {
         }
     }
 
+    // 主端口（9221）的 create 连接走端口池第 0 个 session（与 9231-9239 行为一致）
+    // 注意：takeover（9220，req._takeoverMode=true）不走端口池，保留原 handleClientConnection 逻辑
+    if (!req._takeoverMode && portPool && portPool.portSessions[0]) {
+        const isMainPortClient = path === '/client' ||
+                                 path.startsWith('/client/') ||
+                                 path.startsWith('/devtools/browser/') ||
+                                 path.startsWith('/devtools/page/');
+        if (isMainPortClient) {
+            portPool._handleClientConnect(ws, req, portPool.portSessions[0]);
+            return;
+        }
+    }
+
     const clientInfo = {
         ip: req.socket.remoteAddress,
         port: req.socket.remotePort
@@ -473,6 +760,7 @@ wss.on('connection', (ws, req) => {
     if (path === '/plugin') {
         handlePluginConnection(ws, clientInfo, req);
     } else if (path === '/client' || path.startsWith('/client/') || path.startsWith('/client-') || path.startsWith('/devtools/browser/')) {
+        // 仅 takeover（9220）会走到这里；create 已被上面的端口池分支拦截
         const customClientId = path.startsWith('/client-') ? path.replace('/client-', '') : null;
         let targetPluginId = null;
         if (pathParts[0] === 'client' && pathParts[1]) {
@@ -483,6 +771,7 @@ wss.on('connection', (ws, req) => {
         const mode = req._takeoverMode ? 'takeover' : 'create';
         handleClientConnection(ws, clientInfo, customClientId, targetPluginId, mode);
     } else if (path.startsWith('/devtools/page/')) {
+        // 仅 takeover 会走到这里
         const targetId = path.replace('/devtools/page/', '');
         const mode = req._takeoverMode ? 'takeover' : 'create';
         handlePageConnection(ws, clientInfo, targetId, mode);
@@ -715,11 +1004,20 @@ function handlePluginConnection(ws, clientInfo, request) {
             }
         }
 
+        if (HAS_SAAS && process.env.REQUIRE_AUTH === 'true' && !apiKey) {
+            // 强制鉴权模式：plugin 必须带 key
+            logConnectionEvent('PLUGIN_AUTH_FAIL', 'No API key (REQUIRE_AUTH=true)');
+            ws.close(4001, 'API key required');
+            return;
+        }
+
         if (HAS_SAAS && apiKey) {
             const keyInfo = validateApiKey(apiKey);
             if (keyInfo) {
                 ws.userId = keyInfo.userId;
                 ws.apiKeyId = keyInfo.keyId;
+                ws.apiKey = apiKey;  // 记录 key 字符串，供 client 连接时反查 plugin
+                ws.apiKeyName = keyInfo.keyName;  // key 名称，用作 Chrome 分组名
                 logConnectionEvent('PLUGIN_AUTHED', `userId=${keyInfo.userId} keyName=${keyInfo.keyName}`);
             } else {
                 logConnectionEvent('PLUGIN_AUTH_FAIL', 'Invalid API key');
@@ -835,12 +1133,18 @@ function handlePluginConnection(ws, clientInfo, request) {
             const extVersion = parsed.version || 'unknown';
             ws.extVersion = extVersion;
             const match = extVersion === PKG_VERSION;
-            const level = match ? 'info' : 'warn';
             const label = match ? '✅' : '⚠️ VERSION MISMATCH';
             const msg = `[VERSION CHECK] ${label} server=${PKG_VERSION} extension=${extVersion}`;
             console.log(msg);
             logCDP('VERSION', msg);
             if (!match) {
+                // STRICT_VERSION=true（生产环境）：版本不一致直接拒绝，避免老扩展与新 proxy 不兼容
+                if (process.env.STRICT_VERSION === 'true') {
+                    console.log(`  ↳ STRICT_VERSION=true，拒绝连接`);
+                    logConnectionEvent('PLUGIN_VERSION_REJECTED', `server=${PKG_VERSION} extension=${extVersion}`);
+                    ws.close(4002, `Version mismatch: server=${PKG_VERSION} extension=${extVersion}`);
+                    return;
+                }
                 console.log(`  ↳ Run "cdp-tunnel update" or reload the extension to sync versions`);
             }
             getNamespace(ws).cachedBrowserVersion = null;
@@ -2101,10 +2405,25 @@ server.listen(PORT, '0.0.0.0');
 
 // v3.0 端口池启动（唯一模式）
 portPool = new PortPoolManager({
-    getPluginConnection: () => {
+    getPluginConnection: (apiKey) => {
+        // 鉴权模式：按 key 找对应的 plugin（一 key 一浏览器）
+        if (apiKey) {
+            for (const ws of pluginConnections) {
+                if (ws.readyState === WebSocket.OPEN && ws.apiKey === apiKey) return ws;
+            }
+            return null;
+        }
+        // 无鉴权模式（本地开发）：返回第一个 plugin
         for (const ws of pluginConnections) return ws;
         return null;
     },
+    validateClientKey: (apiKey) => {
+        // 无 SaaS 或未开启强制鉴权时放行（本地开发模式）
+        if (!HAS_SAAS || process.env.REQUIRE_AUTH !== 'true') return true;
+        // 开启强制鉴权：必须有有效 key
+        if (!apiKey) return false;
+        return !!validateApiKey(apiKey);
+    },
     handlePluginUpgrade: (req, socket, head) => {
         wss.handleUpgrade(req, socket, head, (ws) => {
             wss.emit('connection', ws, req);

package/server/saas/auth.js

@@ -85,7 +85,7 @@ function validateApiKey(key) {
     const apiKey = db.prepare('SELECT * FROM api_keys WHERE key = ? AND active = 1').get(key);
     if (!apiKey) return null;
     // 更新最后使用时间
-    db.prepare('UPDATE api_keys SET last_used_at = datetime("now") WHERE id = ?').run(apiKey.id);
+    db.prepare("UPDATE api_keys SET last_used_at = datetime('now') WHERE id = ?").run(apiKey.id);
     return { userId: apiKey.user_id, keyId: apiKey.id, keyName: apiKey.name };
 }