PinchTab 运行时架构与故障排查手册

PinchTab 运行时架构与故障排查手册

一、架构概览

┌─────────────────────────────────────────────────────────────┐
│                      PinchTab 架构                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  MCP Client (Hermes)                                       │
│       │                                                      │
│       │  JSON-RPC over stdio                                 │
│       ▼                                                      │
│  ┌──────────────────────────────────────┐                    │
│  │  pinchtab mcp (PID 5906)            │                    │
│  │  MCP Bridge - 管理实例生命周期       │                    │
│  └──────────────┬───────────────────────┘                    │
│                 │ HTTP / WebSocket                             │
│                 ▼                                              │
│  ┌──────────────────────────────────────┐                    │
│  │  pinchtab server (PID 6033)         │                    │
│  │  端口 9867 - 中央控制面              │                    │
│  │  管理实例、路由请求、鉴权             │                    │
│  └──────────────┬───────────────────────┘                    │
│                 │                                              │
│                 ▼                                              │
│  ┌──────────────────────────────────────┐                    │
│  │  pinchtab bridge (PID 6042)         │                    │
│  │  端口 9868 - 实例代理                │                    │
│  │  转发 CDP 命令到 Chrome               │                    │
│  └──────────────┬───────────────────────┘                    │
│                 │ CDP (Chrome DevTools Protocol)             │
│                 ▼                                              │
│  ┌──────────────────────────────────────┐                    │
│  │  Chrome (PID 6055)                  │                    │
│  │  远程调试端口 9869                    │                    │
│  │  headless 模式                       │                    │
│  │  临时 profile: /tmp/pinchtab-xxx     │                    │
│  └──────────────────────────────────────┘                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

二、关键文件与路径

/opt/data/home/.pinchtab/config.json

  • 路径: /opt/data/home/.pinchtab/config.json
  • 用途: Server 实际使用的配置
  • 重要性: ⭐⭐⭐ 最高优先级

/opt/data/home/.pinchtab/server.pid

  • 路径: /opt/data/home/.pinchtab/server.pid
  • 用途: Server PID 和 token 文件
  • 重要性: ⭐⭐⭐ 运行时读取

/opt/data/home/.pinchtab/server.log

  • 路径: /opt/data/home/.pinchtab/server.log
  • 用途: Server 日志
  • 重要性: ⭐⭐ 调试用

/opt/data/.pinchtab/config.json

  • 路径: /opt/data/.pinchtab/config.json
  • 用途: MCP 工具读取的配置
  • 重要性: ⭐⭐⭐ 必须同步

/opt/data/.pinchtab/instances/

  • 路径: /opt/data/.pinchtab/instances/
  • 用途: 实例状态目录
  • 重要性: ⭐⭐ 清理 error 实例

/opt/data/.pinchtab/profiles/default/

  • 路径: /opt/data/.pinchtab/profiles/default/
  • 用途: 用户数据目录
  • 重要性: ⭐⭐ 浏览器 profile

/opt/data/.agent-browser/browsers/chrome-148.0.7778.167/chrome

  • 路径: /opt/data/.agent-browser/browsers/chrome-148.0.7778.167/chrome
  • 用途: Chrome 二进制路径
  • 重要性: ⭐⭐⭐ 必须配置

~/.hermes/config.yaml

  • 路径: ~/.hermes/config.yaml
  • 用途: Hermes 的 MCP 配置
  • 重要性: ⭐⭐ MCP 连接配置

三、Token 鉴权链路

1. Server 启动时生成 token (或从 config 读取)
   ↓
2. token 写入 /opt/data/home/.pinchtab/server.pid
   ↓
3. token 也写入 /opt/data/.pinchtab/config.json (需手动同步)
   ↓
4. MCP 工具从 /opt/data/.pinchtab/config.json 读取 token
   ↓
5. 所有 HTTP 请求携带 Authorization: Bearer <token>
   ↓
6. Server 验证 token → 转发到 bridge → 转发到 Chrome
⚠️ 关键坑点：两个 config.json 必须同步！

四、端口分配

9867

  • 端口: 9867
  • 服务: Server
  • 用途: 中央控制面 (health, navigate, tabs)

9868

  • 端口: 9868
  • 服务: Bridge
  • 用途: 实例代理 (转发 CDP 命令)

9869

  • 端口: 9869
  • 服务: Chrome
  • 用途: 远程调试端口 (CDP)

9888

  • 端口: 9888
  • 服务: Profile Server
  • 用途: 用户数据同步 (通常不跑)

五、故障排查清单

问题 1: 401 missing_token / bad_token

症状: 所有 API 返回 401