kris/WechatOnCloud
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
67aab58a00
WechatOnCloud/doc/优化方案/01-多应用桥接框架设计.md
Kris 67aab58a00 docs: 新增PRD规范与WechatOnCloud改造、多应用桥接框架文档 
新增三份文档：
1. 产品需求文档(PRD)编写规范
2. WechatOnCloud容器化微信改造需求方案
3. 多应用桥接框架整体设计方案
2026-07-18 16:04:25 +08:00

940 lines
41 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 多应用桥接框架设计
> 目标：将 bridge 从"微信专属 API 服务"演进为"容器内多桌面应用的统一桥接框架"。一个容器内可同时运行多个应用（微信 / 小红书 / Telegram / Chromium / 自定义），每个应用作为独立实例被 bridge 管理，对外暴露结构化接口。
---
> **阅读提示**：本文档是**目标架构设计**，同时用 `[现状]` 标注当前代码的实际状态。当前 bridge 仍是一个约 2400 行的单文件服务（[bridge/server.py](file:///D:/WechatOnCloud-main/bridge/server.py)），全局单例、微信强耦合；docker 与 panel 层已支持"一容器一应用"的多应用类型，但尚未支持"单容器多应用"。因此本文先聚焦 bridge 层改造，使其在"多容器单应用"模式下即可工作，单容器多应用作为后续扩展。
---
## 1. 背景与转变
### 1.1 现状
bridge 当前是**单应用、单进程、强耦合微信**的 API 服务：
- [bridge/server.py](../bridge/server.py) 约 2400 行单文件，全局单例 `_state = AppState()` 持有唯一的 `XdotoolDriver`、`DbReader`、`SendQueue`、`QrCapture`。
- 所有路由均为 `/api/*` 无前缀（如 `/api/send/text`、`/api/messages/since`），直接操作全局 `_state`，没有 `app_id` 概念。
- 响应模型字段名微信中心化：`wechat_running`、`wechat_window_found`、错误码 `WECHAT_NOT_RUNNING` / `WECHAT_NOT_LOGGED_IN`。
- DB 解密、联系人/消息读取、二维码登录全部写死微信表结构与 SQLCipher 参数。
- 一容器只跑一个应用（由 [docker/app-defs.sh](../docker/app-defs.sh) 的 `WOC_APP_TYPE` 决定）；想新增小红书/Telegram 自动化，当前只能再起一个容器。
### 1.2 转变
用户需求：**一个容器内同时跑多个应用，每个应用对外暴露接口**。
这要求 bridge 从"微信适配器"升格为"应用桥接框架"：
| 维度 | 现状 | 目标 |
|------|------|------|
| 容器内应用数 | 1（由 `WOC_APP_TYPE` 决定） | N（动态注册） |
| bridge 进程 | 跟随单一应用 | 一个 bridge 管理多个应用实例 |
| 路由 | 微信专属路由无前缀 | 通用路由无前缀 + 每个应用实例独立命名空间 |
| 状态 | 全局单例 `_state` | 按 app_id 隔离的 AppInstance 容器 |
| 资源调度 | 不需要 | 必须串行化 X11 / 剪贴板 / 焦点操作 |
### 1.3 已具备的基础（非本阶段改造重点）
- docker 层已通过 `WOC_APP_TYPE` 支持多种应用类型：`wechat` / `telegram` / `chromium` / `custom`（[docker/app-defs.sh](../docker/app-defs.sh)）。
- panel 的 `Instance.appType` 已能标识实例承载的应用类型，并透传给容器环境变量（[panel/server/src/store.ts](../panel/server/src/store.ts)）。
- bridge 基于 FastAPI + Pydantic，已有统一的 `BridgeError` 异常模型与全局异常处理器，为路由拆分和错误码扩展提供了基础。
> **本文档范围**：仅聚焦 bridge 层改造；panel UI、docker 单容器多应用启动机制不在本阶段文档范围内。
---
## 2. 核心理念
### 2.1 三层抽象
```
应用类型 (AppKind) — 静态描述：微信 / 小红书 / Telegram / Chromium / Custom
↓ 实例化
应用实例 (AppInstance) — 运行期实体：唯一 app_id、独立状态、独立窗口
↓ 适配
应用驱动 (AppDriver) — 该实例的能力实现：发消息 / 发笔记 / 读 DB / 截图
```
- **AppKind** 是注册表项，定义"这类应用能做什么、怎么启动、需要什么依赖"
- **AppInstance** 是运行期实体，一个容器内可以同时存在多个同类实例（如两个微信账号、两个小红书账号）
- **AppDriver** 是实例的能力实现层，框架通过它操作具体应用
### 2.2 框架职责边界
**框架负责（应用无关）**：
- HTTP 服务、路由分发、鉴权、限流
- 请求/响应日志、异常处理、错误码体系
- X11 串行化调度（避免多应用并发争用同一个 X server）
- 截图、剪贴板、窗口管理（通用 X11 能力）
- 应用生命周期管理（启动 / 停止 / 重启 / 健康检查）
- 诊断框架（通用检查项 + 应用自报检查项）
- 配置管理、命令行参数、环境变量
**应用驱动负责（应用相关）**：
- 进程启动命令与参数
- 窗口识别（按 title / class / PID）
- 登录态检测与登录流程
- 应用专属能力实现（发消息、发笔记、读 DB、搜索等）
- 应用专属路由注册
- 应用专属诊断项
> **[现状]** 当前所有职责都混在 [bridge/server.py](../bridge/server.py) 中，没有框架/驱动分层；`XdotoolDriver` 直接实现微信专用方法，`SendQueue` 是全局单例限流器，UIScheduler 尚未引入。
### 2.3 设计原则
1. **组合优于继承**：driver 持有通用工具实例（`self.xd`），不继承工具类
2. **一应用一命名空间**：每个实例独立 `app_id`，路由与状态都按 `app_id` 隔离
3. **声明式能力**：driver 声明能力集合，框架据此挂载路由与协商
4. **串行化 X11**：所有窗口操作经统一 UIScheduler 排队执行
5. **应用无关的 DB 抽象延迟**：SQLCipher 解密暂留微信 driver 内，待第二个 SQLCipher 应用出现再抽公共层
6. **向后兼容过渡**：旧路径与新路径并存，alias 机制保证现有调用方不破坏
---
## 3. 总体架构
```
┌─────────────────────────────────────────────────────────────────┐
│ Docker 容器 │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ bridge 框架进程 (FastAPI, :8088) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 通用路由层 │ │ UIScheduler │ │ AppManager │ │ │
│ │ │ /api/status │ │ (X11 串行) │ │ (生命周期) │ │ │
│ │ │ /api/apps │ │ │ │ │ │ │
│ │ │ /api/screens │ └──────────────┘ └──────┬───────┘ │ │
│ │ │ /api/diag/* │ │ │ │
│ │ └──────────────┘ │ │ │
│ │ ┌─────────────┼─────────┐ │ │
│ │ │ │ │ │ │
│ │ ┌───────────────────┴───┐ ┌──────┴───────┐ │ │
│ │ │ AppInstance[wx_a1] │ │ AppInstance │ │ │
│ │ │ └ WechatDriver │ │ [xhs_b2] │ │ │
│ │ │ routes: /api/apps/ │ │ └ XhsDriver │ │ │
│ │ │ wx_a1/* │ │ routes: │ │ │
│ │ │ capabilities: │ │ /api/apps/ │ │ │
│ │ │ text_send, │ │ xhs_b2/* │ │ │
│ │ │ db_read, │ │ capabilities│ │ │
│ │ │ login_qr │ │ publish, │ │ │
│ │ └───────────────────────┘ │ search │ │ │
│ │ └──────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ X server (Xvfb :1) ◀── 所有应用共用，UIScheduler 串行化调度 │
│ ├─ 微信窗口 (wxid_abc) │
│ ├─ chromium 窗口 (xiaohongshu) │
│ KasmVNC (:3000/3001) ◀── web 桌面串流 │
│ │
│ 数据卷 /config/ │
│ ├─ wechat/<wxid>/ 微信数据 │
│ ├─ xiaohongshu/ 小红书 cookie + 数据 │
│ ├─ telegram/ Telegram 数据 │
│ └─ apps.json 应用实例注册表（持久化） │
└─────────────────────────────────────────────────────────────────┘
▲
│ HTTP Bearer Token
┌──────┴──────┐
│ panel 面板 │ ◀── 统一入口，调度多容器、多应用
└─────────────┘
```
> **[现状]** 上图是目标态。当前每个 Docker 容器内只运行**一个**应用实例，bridge 进程也按单实例设计；`AppManager`、`UIScheduler`、`apps.json` 均未实现。本阶段优先让 bridge 在"多容器单应用"模式下具备框架能力（每个容器一个 bridge、一个 driver、一个 AppInstance），为未来的"单容器多应用"保留扩展点。
---
## 4. 核心概念
### 4.1 AppKind（应用类型）
静态注册项，描述"这类应用是什么"。一个 AppKind 在 bridge 启动时注册到 `AppKindRegistry`。
| 属性 | 说明 | 示例 |
|------|------|------|
| `kind_id` | 唯一标识 | `"wechat"` / `"xiaohongshu"` / `"telegram"` / `"chromium"` / `"custom"` |
| `name` | 显示名 | `"微信"` / `"小红书"` |
| `driver_class` | AppDriver 实现类 | `WechatDriver` / `XiaohongshuDriver` |
| `default_capabilities` | 默认能力集合 | `{"text_send","db_read","login_qr"}` |
| `binary_path` | 可执行文件路径（用于检测是否已安装） | `/config/wechat/opt/wechat/wechat` |
| `launch_args_template` | 启动参数模板（支持变量替换） | `"--user-data-dir={data_dir}"` |
| `single_instance` | 是否限制单实例（如系统托盘类应用） | `true` / `false` |
> **[现状]** `AppKindRegistry` 尚未实现。当前应用类型由容器环境变量 `WOC_APP_TYPE` 决定，bridge 代码中无对应抽象；但目标类的字段（`kind_id`、`driver_class`、`binary_path` 等）可直接映射到现有 docker/app-defs.sh 的定义。
### 4.2 AppInstance（应用实例）
运行期实体，代表一个正在运行（或已注册待启动）的应用。每个实例有唯一 `app_id`。
| 属性 | 说明 | 示例 |
|------|------|------|
| `app_id` | 全局唯一实例标识 | `"wx_a1"` / `"xhs_b2"`（kind 前缀 + 短随机） |
| `kind_id` | 所属应用类型 | `"wechat"` |
| `display_name` | 用户可读名 | `"工作微信"` / `"小红书主号"` |
| `data_dir` | 该实例独立数据目录 | `/config/apps/wx_a1` |
| `window_id` | X11 窗口 ID（运行期动态） | `0x380000a` |
| `pid` | 进程 PID | `1234` |
| `login_state` | 当前登录态 | `"logged_in"` / `"need_login"` / `"not_running"` |
| `capabilities` | 实际可用能力（动态计算） | `{"text_send"}`（DB 未解锁时 db_read 不在集合内） |
| `status` | 实例状态 | `"registered"` / `"starting"` / `"running"` / `"stopped"` / `"crashed"` |
**实例寻址**：所有应用专属路由以 `/api/apps/{app_id}/` 为前缀，框架据此路由到对应实例的 driver。
> **[现状]** `AppInstance` 数据类尚未实现。当前 bridge 的运行期状态是全局单例 `_state`，没有 `app_id`。本阶段每个 bridge 进程仍只管理一个实例，可把该实例的 `app_id` 固定为 `"default"` 或从 `WOC_APP_TYPE` 派生，使新路由层能提前落地。
### 4.3 AppDriver（应用驱动）
每种 AppKind 对应一个 AppDriver 实现类，负责该类应用的所有操作。driver 实例与 AppInstance 一一绑定。
```python
class AppDriver(ABC):
kind_id: ClassVar[str]
default_capabilities: ClassVar[set[str]]
def __init__(self, instance: AppInstance, ctx: BridgeContext) -> None:
self.instance = instance
self.ctx = ctx # 框架通用能力（xd / scheduler / screenshot）
self.xd = ctx.xd_factory(instance) # 该实例专属的 XdotoolBase
# 生命周期
async def install(self) -> None: ... # 首次安装（下载/解压）
async def start(self) -> None: ... # 启动进程
async def stop(self) -> None: ... # 停止进程
async def restart(self) -> None: ...
async def is_running(self) -> bool: ...
async def health_check(self) -> dict: ...
# 窗口与登录
async def find_window(self) -> int | None: ...
async def activate_window(self) -> None: ...
async def detect_login_state(self) -> str: ...
async def wait_for_login(self, timeout: int) -> None: ...
async def logout(self) -> None: ...
# 能力查询
def capabilities(self) -> set[str]: ... # 返回当前实际可用能力（动态）
# 路由注册
def register_routes(self, router: APIRouter) -> None: ...
# 诊断
def diagnostic_items(self) -> list[dict]: ...
async def diagnostic_run(self, check_id: str) -> dict: ...
async def diagnostic_autofix(self, check_id: str) -> dict: ...
```
> **[现状]** `AppDriver` 抽象基类尚未实现。当前微信相关逻辑直接写在 [bridge/server.py](../bridge/server.py) 和 [bridge/xdotool_driver.py](../bridge/xdotool_driver.py) 中，二者均强耦合微信。拆分时建议：
> 1. 把 `xdotool_driver.py` 中通用 X11 操作（`_run`、`_key`、`_paste_via_xclip`、窗口几何）抽成 `XdotoolBase`；
> 2. 把微信专属方法（`find_wechat_window`、`send_text`、`_open_session_by_name`）迁到 `drivers/wechat/driver.py` 的 `WechatDriver`；
> 3. 微信 DB 读写、密钥提取、二维码登录迁到 `drivers/wechat/` 子模块。
### 4.4 BridgeContext（框架上下文）
driver 通过它访问框架通用能力。框架保证线程安全与串行化。
| 字段 | 类型 | 说明 |
|------|------|------|
| `config` | `BridgeConfig` | 全局配置 |
| `xd_factory` | `Callable[[AppInstance], XdotoolBase]` | 为每个实例创建 X11 工具（绑定到该实例窗口） |
| `ui_scheduler` | `UIScheduler` | X11 操作串行化调度器 |
| `screenshot` | `Screenshot` | 通用截图能力 |
| `send_queue` | `SendQueue` | UI 操作串行化队列（多应用共享） |
| `logger` | `logging.Logger` | 框架 logger |
---
## 5. 模块设计
### 5.1 目录结构
```
bridge/
core/ 框架核心（应用无关）
__init__.py
context.py BridgeContext
config.py BridgeConfig（命令行 + env）
server.py FastAPI app 工厂 + lifespan + 全局中间件
logging.py logger 配置 + 请求日志中间件
errors.py BridgeError + ErrorResponse + 错误码表
models.py 通用响应模型（StatusResponse / AppInstanceInfo 等）
xdotool_base.py X11 通用操作基类
screenshot.py 通用截图
send_queue.py UI 串行化队列
ui_scheduler.py X11 操作调度器（多应用串行）
diagnostic.py 通用诊断框架
app_manager.py AppManager（实例生命周期管理）
app_kind.py AppKind + AppKindRegistry（类型注册表）
app_instance.py AppInstance 数据类
lifecycle.py InitState 后台任务框架
drivers/ 应用适配器
__init__.py
base.py AppDriver 抽象基类
wechat/
__init__.py
driver.py WechatDriver(AppDriver)
db_reader.py 微信 DB 读取
decryptor.py SQLCipher 解密
key_cache.py 密钥缓存
key_extractor.py 内存扫描提 key
models.py 微信专属请求/响应模型
routes.py 微信专属路由
diagnostic.py 微信诊断项
xiaohongshu/
__init__.py
driver.py XiaohongshuDriver(AppDriver)
routes.py 小红书专属路由
models.py
telegram/
__init__.py
driver.py TelegramDriver(AppDriver)
routes.py
chromium/
__init__.py
driver.py ChromiumDriver(AppDriver) 通用浏览器
custom/
__init__.py
driver.py CustomDriver(AppDriver)
tools/ 调试脚本
s6/ s6 服务定义
main.py 入口：解析参数 → 注册 kinds → 启动 app
```
> **[现状]** 上述 `core/`、`drivers/`、`main.py` 均为目标结构。当前 bridge 目录扁平：所有代码在 [bridge/server.py](../bridge/server.py)、[bridge/xdotool_driver.py](../bridge/xdotool_driver.py)、[bridge/send_queue.py](../bridge/send_queue.py) 等根级文件中。S1 阶段可按以下顺序迁移，避免一次性大爆炸：
> 1. 先把 `server.py` 中通用配置/错误/模型迁到 `core/`；
> 2. 创建 `drivers/base.py` 与 `drivers/wechat/`；
> 3. 保持 `main.py` 仍只注册一个 `WechatDriver`，行为与旧版完全一致。
### 5.2 AppManager（应用管理器）
框架核心组件，管理容器内所有 AppInstance 的生命周期。
**职责**：
- 维护实例注册表（内存 + 持久化到 `/config/apps.json`）
- 提供实例 CRUD：`register` / `unregister` / `list` / `get`
- 控制实例生命周期：`start` / `stop` / `restart`
- 健康检查：周期性轮询所有 running 实例的 `is_running`
- 自动恢复：crashed 实例按策略重启（最多 N 次/小时）
**实例注册表结构**（`/config/apps.json`）：
```json
{
"version": 1,
"instances": [
{
"app_id": "wx_a1",
"kind_id": "wechat",
"display_name": "工作微信",
"data_dir": "/config/apps/wx_a1",
"auto_start": true,
"created_at": 1735900800
},
{
"app_id": "xhs_b2",
"kind_id": "xiaohongshu",
"display_name": "小红书主号",
"data_dir": "/config/apps/xhs_b2",
"auto_start": false,
"created_at": 1735900900
}
]
}
```
> **[现状]** `AppManager` 与 `/config/apps.json` 均未实现。当前实例生命周期（容器启停、应用安装）由 panel 通过 Docker API 管理，bridge 只感知当前容器内已启动的单个应用。本阶段改造不推翻 panel 的生命周期管理，bridge 内只保留单实例的运行期抽象，为后续多实例注册表预留接口。
### 5.3 UIScheduler（X11 操作调度器）
**问题**：多应用共用一个 X server，并发操作会导致：
- 窗口焦点争用（A 激活窗口时 B 的操作打到 A）
- 剪贴板污染（A 写剪贴板，B 还没读就被覆盖）
- 键盘事件错位（A 的 Ctrl+V 发到 B 的窗口）
**解决**：所有 X11 操作（activate / key / paste / click / type）必须经 UIScheduler 排队执行。
```python
class UIScheduler:
"""X11 操作串行化调度器。
所有 driver 的 X11 操作通过 submit() 提交，调度器按 FIFO 顺序
串行执行。同一时间只有一个操作在 X server 上进行。
"""
async def submit(self, coro_factory: CoroFactory, *, app_id: str) -> Any:
"""提交一个 X11 操作。
Args:
coro_factory: 返回 coroutine 的工厂（便于重试与超时控制）
app_id: 发起方实例 ID（用于日志与死锁检测）
Returns:
操作结果
Notes:
- 操作间最小间隔 100ms（避免 X server 压力）
- 单操作超时 30s（避免死锁）
- 操作日志带 app_id 前缀，便于排障
"""
```
**driver 使用方式**：
```python
class WechatDriver(AppDriver):
async def send_text(self, to: str, content: str) -> str:
async def _op():
await self.xd.activate_window(self.instance.window_id)
await self.xd._open_session_by_name(to)
await self.xd._paste_via_xclip(content)
await self.xd._key("Return")
return f"local_{int(time.time())}_{random.randint(0,0xFFFFFF):06x}"
return await self.ctx.ui_scheduler.submit(_op, app_id=self.instance.app_id)
```
**不进 UIScheduler 的操作**：
- 读窗口列表（`xdotool search`，只读）
- 读进程状态（`pgrep`，只读）
- 读 DB（不涉及 X11）
- 截图（`scrot` 本身是只读快照，不争用焦点）
### 5.4 SendQueue 与 UIScheduler 的关系
| 组件 | 作用 | 粒度 |
|------|------|------|
| `SendQueue` | 发送类操作的限流（防止频率过高触发风控） | 单实例：每个 driver 自己一个队列 |
| `UIScheduler` | X11 操作的串行化（防止多应用争用 X server） | 全局：所有 driver 共享 |
两者正交：一个操作可能先经 SendQueue 限流，再经 UIScheduler 串行执行。
> **[现状]** 当前只有一个全局 [SendQueue](../bridge/send_queue.py)，用于单应用发送限流；`UIScheduler` 尚未实现，X11 操作在 HTTP 层并发调用时存在焦点/剪贴板冲突风险。S1 阶段可保持 `SendQueue` 不变，S2 引入多实例后再把 `SendQueue` 下放到每个 `AppInstance`，同时新增全局 `UIScheduler`。
---
## 6. 接口规范
### 6.1 路由分层
```
/api/* 通用路由（无 app_id，框架级）
/api/status 框架状态（聚合所有应用摘要）
/api/apps 应用实例列表 / 注册新实例
/api/apps/{app_id} 单实例状态 / 控制
/api/apps/{app_id}/start 启动实例
/api/apps/{app_id}/stop 停止实例
/api/apps/{app_id}/restart 重启实例
/api/kinds 支持的应用类型列表
/api/screenshot 全屏截图（所有应用窗口）
/api/diagnostic/items 通用诊断项 + 所有实例诊断项聚合
/api/diagnostic/run/{id} 执行诊断
/api/diagnostic/autofix/{id}
/api/apps/{app_id}/* 应用专属路由（由 driver.register_routes 挂载）
/api/apps/{app_id}/messages 微信消息拉取
/api/apps/{app_id}/contacts 微信联系人
/api/apps/{app_id}/send/text 微信发文本
/api/apps/{app_id}/login/qr 微信扫码登录
/api/apps/{app_id}/db/decrypt 微信 DB 解密
/api/apps/{app_id}/xhs/publish 小红书发笔记
/api/apps/{app_id}/xhs/search 小红书搜索
```
> **[现状]** 当前所有路由都是 `/api/*` 无前缀（如 `/api/send/text`、`/api/messages/since`、`/api/db/decrypt`），且全部写死微信逻辑。本阶段目标：
> 1. 新增 `/api/apps/{app_id}/*` 路由层；
> 2. 将旧路由作为 alias 内部转发到 `/api/apps/default/*`；
> 3. `/api/status` 同时返回旧字段（取 default app）与新 `apps` 数组，保证面板零改动。
### 6.2 通用路由详述
#### GET /api/status
返回框架整体状态 + 所有实例摘要。
```json
{
"bridge_version": "2.0.0",
"uptime_seconds": 3600,
"display": ":1",
"app_count": 2,
"apps": [
{
"app_id": "wx_a1",
"kind_id": "wechat",
"display_name": "工作微信",
"status": "running",
"login_state": "logged_in",
"capabilities": ["text_send", "db_read", "login_qr"]
},
{
"app_id": "xhs_b2",
"kind_id": "xiaohongshu",
"display_name": "小红书主号",
"status": "running",
"login_state": "need_login",
"capabilities": ["publish", "search"]
}
]
}
```
#### GET /api/apps
列出所有实例。
#### POST /api/apps
注册新实例。
```json
// 请求
{
"kind_id": "xiaohongshu",
"display_name": "小红书小号",
"auto_start": true
}
// 响应
{
"app_id": "xhs_c3",
"kind_id": "xiaohongshu",
"display_name": "小红书小号",
"data_dir": "/config/apps/xhs_c3",
"status": "registered"
}
```
#### GET /api/apps/{app_id}
单实例详细状态。
```json
{
"app_id": "wx_a1",
"kind_id": "wechat",
"display_name": "工作微信",
"status": "running",
"pid": 1234,
"window_id": "0x380000a",
"login_state": "logged_in",
"capabilities": ["text_send", "db_read", "login_qr", "media"],
"uptime_seconds": 1800,
"db_accessible": true,
"current_wxid": "wxid_abc",
"current_nickname": "张三"
}
```
#### POST /api/apps/{app_id}/start|stop|restart
控制实例生命周期。
#### GET /api/kinds
列出支持的 AppKind。
```json
{
"kinds": [
{
"kind_id": "wechat",
"name": "微信",
"default_capabilities": ["text_send", "db_read", "login_qr", "media"],
"single_instance": false,
"installed": true
},
{
"kind_id": "xiaohongshu",
"name": "小红书",
"default_capabilities": ["publish", "search"],
"single_instance": false,
"installed": true
}
]
}
```
### 6.3 应用专属路由规范
由各 driver 通过 `register_routes(router)` 挂载，router 自动绑定 `/api/apps/{app_id}` 前缀。
**driver 实现示例**：
```python
# drivers/wechat/routes.py
def register_routes(router: APIRouter) -> None:
@router.get("/messages/since")
async def get_messages(app_id: str, cursor: int = 0, limit: int = 50):
driver = app_manager.get_driver(app_id)
return await driver.get_messages_since(cursor, limit)
@router.post("/send/text")
async def send_text(app_id: str, req: SendTextRequest):
driver = app_manager.get_driver(app_id)
return await driver.send_text(req.to, req.content)
```
### 6.4 错误码扩展
新增框架级错误码：
| 错误码 | HTTP | 说明 |
|--------|------|------|
| `APP_NOT_FOUND` | 404 | app_id 不存在 |
| `APP_NOT_RUNNING` | 503 | 实例未运行 |
| `APP_NOT_LOGGED_IN` | 401 | 实例未登录 |
| `APP_KIND_UNKNOWN` | 400 | 未知应用类型 |
| `APP_KIND_NOT_INSTALLED` | 503 | 应用类型未安装 |
| `APP_ALREADY_EXISTS` | 409 | 实例已存在（single_instance 冲突） |
| `UI_BUSY` | 503 | UIScheduler 队列拥塞 |
| `APP_CAPABILITY_NOT_SUPPORTED` | 501 | 该实例不支持请求的能力 |
> **[现状]** 当前 [bridge/models.py](../bridge/models.py) 中只有微信中心化错误码，如 `WECHAT_NOT_RUNNING`、`WECHAT_NOT_LOGGED_IN` 等。拆分阶段应：
> 1. 保留旧错误码作为微信 driver 的返回值；
> 2. 新增框架级错误码上表；
> 3. alias 路由命中时仍可使用旧错误码，避免面板/外部系统改动。
### 6.5 向后兼容层
现有无前缀路由（`/api/messages`、`/api/send/text` 等）保留为 alias，内部转发到 `/api/apps/{default_app_id}/...`。
**默认实例选择规则**：
1. 若容器内只有一个实例，自动作为 default
2. 若多实例，读取 `/config/.woc-default-app`（由面板或首次注册时写入）
3. 都没有则返回 404
**alias 路由行为**：
- 命中 alias 时日志打 `DEPRECATED` warning，提示调用方迁移
- alias 在 major 版本升级时下线（v3.0.0 移除）
### 6.6 与既有系统的兼容性约束
改造必须尊重以下已验证的硬约束，否则现有微信实例会损坏：
1. **鉴权**：`/api/bridge/:id/*` 外部调用依赖 `WOC_BRIDGE_API_TOKEN` 作为 Bearer token；修改 `.env` 后必须重建 panel 容器（而非重启）才能生效。
2. **DB 解密**：微信 DB 仅兼容 Linux WeChat 4.x，使用 SQLCipher 4 参数（AES-256-CBC、PBKDF2-HMAC-SHA512、256000 rounds、mac_salt = salt XOR 0x3A）。解密能力保留在 `drivers/wechat/` 内，不提前抽象。
3. **ptrace**：自动提取 key 需要容器具备 `SYS_PTRACE` capability 或 `--privileged`，且宿主 `ptrace_scope=0`。
4. **DB 路径**：自动检测写死 `/config/xwechat_files/<wxid>/db_storage/message/message_0.db`；改为 driver 内部常量，不作为框架公共假设。
5. **发送定位**：微信 `send_text/send_file` 使用 `display_name`（备注/昵称）而非 wxid 搜索会话，该行为由 `WechatDriver` 封装，不进入框架公共层。
6. **容器启动**：当前 [docker/autostart](../docker/autostart) 只启动一个应用；bridge 框架不假设自己能启动多个应用，生命周期控制仍由 panel/docker 负责。
---
## 7. 资源调度与并发
### 7.1 X11 资源争用对策
| 资源 | 争用场景 | 对策 |
|------|---------|------|
| 窗口焦点 | A 激活窗口时 B 失焦 | 所有 activate/key/click 经 UIScheduler 串行 |
| 剪贴板 | A 写入后 B 未读就被 C 覆盖 | paste 操作是"写剪贴板+立即 Ctrl+V"原子组，经 UIScheduler 串行 |
| 键盘事件 | A 的 Ctrl+V 发到 B 窗口 | activate 后立即操作，UIScheduler 保证原子 |
| 鼠标坐标 | A 的 click 坐标被 B 的 mousemove 改变 | mousemove + click 必须在同一个 UIScheduler 任务内 |
### 7.2 并发模型
```
HTTP 请求 (asyncio)
↓
driver 方法 (async)
↓
UIScheduler.submit(coro) ◀── 全局串行点（X11 操作）
↓
XdotoolBase._run (asyncio subprocess)
```
- HTTP 层并发：FastAPI 默认并发处理请求
- driver 层并发：每个实例的方法可并发调用
- UIScheduler 层串行：所有 X11 写操作排队执行
- DB 读取层并发：不涉及 X11，独立并发（受限于 SQLite 读写锁）
### 7.3 限流策略
| 层级 | 限流 | 配置 |
|------|------|------|
| HTTP 全局 | 单 IP 每秒 N 请求 | `WOC_BRIDGE_MAX_CALLS_PER_SEC` |
| 单实例发送 | 发送类操作最小间隔 | `WOC_BRIDGE_SEND_DELAY_MS`（每实例独立） |
| UIScheduler | 操作间最小间隔 | 固定 100ms（防止 X server 压力） |
| UIScheduler 队列长度 | 最多排队 N 个操作 | 50，超限返回 `UI_BUSY` |
---
## 8. 应用生命周期
### 8.1 实例状态机
```
register
┌─────────────────────────┐
│ ▼
┌────────┐ start ┌─────────┐ running ┌────────┐
│registered├────────►│starting├────────────►│running │
└────────┘ └────┬───┘ └───┬────┘
▲ │ fail │ stop
│ ▼ ▼
│ ┌────────┐ ┌────────┐
│ │crashed │ │stopped │
│ └───┬────┘ └───┬────┘
│ │ restart │ start
│ ▼ │
└──────────────────────────────────────────┘
```
### 8.2 启动流程
1. `POST /api/apps` 注册实例 → 状态 `registered`
2. `POST /api/apps/{app_id}/start` → 状态 `starting`
3. driver.install()（首次启动，下载/解压）
4. driver.start()（启动应用进程）
5. 轮询 driver.find_window() 直到窗口出现（超时 60s）
6. 状态 `running`
7. 启动失败 → 状态 `crashed`，记录错误
### 8.3 自动启动
容器启动时，AppManager 读取 `/config/apps.json`，对所有 `auto_start=true` 的实例按顺序执行启动流程。
**顺序约束**：实例间启动间隔 5 秒（避免同时启动多个 GUI 应用导致内存峰值）。
### 8.4 健康检查
AppManager 后台任务（每 30s）：
1. 遍历所有 `running` 状态实例
2. 调用 `driver.is_running()`
3. 失败则状态转 `crashed`
4. 记录崩溃次数与时间
5. 若配置了自动恢复且未超限（默认 3 次/小时），触发 restart
### 8.5 数据卷布局
```
/config/
apps.json 实例注册表
.woc-default-app 默认实例 app_id（兼容层用）
apps/
wx_a1/
data/ 应用数据根（driver 自由组织）
wechat/
opt/wechat/wechat 微信二进制
xwechat_files/ 微信运行时数据
logs/ 该实例日志
state/ 该实例状态文件
xhs_b2/
data/
chromium/ 小红书专用 chromium user-data-dir
Default/
Cookies 小红书登录 cookie
logs/
state/
```
---
## 9. 应用间通信
### 9.1 显式通信（推荐）
应用之间通过外部调用方（如面板或用户脚本）显式编排：
```
# 伪代码：从小红书采集内容，发到微信
xhs_note = await bridge.get(f"/api/apps/xhs_b2/xhs/search?keyword=foo")
await bridge.post(f"/api/apps/wx_a1/send/text", json={"to":"文件助手","content":xhs_note})
```
**优点**：流程显式、可观测、可调试。
**不提供应用间直接调用**：driver 之间不互相感知，避免隐式依赖。
### 9.2 事件总线（未来扩展）
可选的发布订阅机制：
```python
# driver 发布事件
await self.ctx.event_bus.publish("message_received", {"app_id": "wx_a1", "msg": {...}})
# 外部订阅
GET /api/events/stream (SSE)
```
P0 不实现，留待有明确需求时再做。
---
## 10. 部署模型
### 10.1 单容器多应用
```
容器 woc-app-multi
├─ bridge (:8088) 管理 2 个实例
├─ Xvfb (:1)
├─ KasmVNC (:3000)
├─ 微信进程 (wx_a1)
└─ chromium 进程 (xhs_b2)
```
适用于：单用户、资源受限（NAS）、应用间需要协同（同一桌面）。
### 10.2 多容器单应用（现有模式保留）
```
容器 woc-wx-<id1> 微信实例 1
容器 woc-wx-<id2> 微信实例 2
容器 woc-xhs-<id3> 小红书实例
```
适用于：多用户隔离、横向扩展、单应用崩溃不影响其他。
### 10.3 混合模式
面板支持两种模式并存：
- 轻量场景用单容器多应用（省资源）
- 隔离场景用多容器单应用（强隔离）
面板层提供创建实例时的"部署位置"选项：新建独立容器 or 加入已有容器的 bridge。
---
## 11. 演进路径
### S0：当前现状
- [bridge/server.py](../bridge/server.py) 约 2400 行单文件，全局单例 `_state`。
- 所有 `/api/*` 路由直接写死微信逻辑，无 `app_id`、无 driver 抽象。
- [docker/autostart](../docker/autostart) 一容器一应用；panel 通过 Docker API 管理生命周期。
### S1：抽 core/ 与 driver 抽象（不改行为，本阶段重点）
**目标**：把 server.py 拆成 `core/` + `drivers/wechat/`，建立 `AppDriver` 抽象，但保持单应用模式。
**改动**：
- 新建 `core/` 目录，迁移 `config` / `context` / `errors` / `logging` / `models` / `send_queue` / `screenshot`。
- 抽 `XdotoolBase`（通用 X11 操作）到 `core/xdotool_base.py`。
- 定义 `drivers/base.py` 的 `AppDriver` 抽象基类。
- 微信逻辑迁移到 `drivers/wechat/`，`WechatDriver(AppDriver)` 用组合方式持有 `XdotoolBase`。
- 微信路由迁移到 `drivers/wechat/routes.py`。
- `main.py` 读 `WOC_APP_TYPE`，只注册一个 driver，创建一个 `AppInstance`（`app_id="default"`）。
**验证**：所有现有 API 行为不变，面板无感知；`pytest` 或现有集成测试全部通过。
### S2：新路由层 + 向后兼容层
**目标**：引入 `/api/apps/{app_id}/*` 路由，旧路由作为 alias 转发。
**改动**：
- 新增 `/api/apps/{app_id}/status`、`/api/apps/{app_id}/send/text` 等路由。
- 旧路径 `/api/messages`、`/api/send/text` 等转为 alias，转发到 `/api/apps/default/...`。
- `/api/status` 同时返回旧字段（取 default app）与新 `apps` 数组。
- 旧字段日志打 `DEPRECATED` warning。
**验证**：面板与外部调用方无需改动即可工作；新路径可通过 `/api/apps/default/*` 访问。
### S3：UIScheduler 与 SendQueue 正交化
**目标**：解决多实例共享 X server 时的焦点/剪贴板冲突。
**改动**：
- 新增 `core/ui_scheduler.py`，所有 X11 写操作经其串行执行。
- 每个 `AppInstance` 持有独立 `SendQueue`；`UIScheduler` 全局唯一。
- 单应用模式下行为不变，多实例模式下才体现串行价值。
**验证**：高并发调用 `/api/apps/default/send/text` 不再出现剪贴板污染。
### S4：AppManager 与单容器多实例（未来扩展）
**目标**：支持容器内注册多个 `AppInstance`。
**改动**：
- 实现 `core/app_manager.py`、`core/app_instance.py`、`core/app_kind.py`。
- 新增 `/api/apps` CRUD 路由。
- `/config/apps.json` 持久化。
- 需同步改造 [docker/autostart](../docker/autostart) 以支持启动多个应用。
**验证**：可在同一容器内通过 API 注册并启动微信 + 小红书两个实例。
### S5：新增 Xiaohongshu/Telegram Driver（框架可扩展性验证）
**目标**：落地非微信应用自动化。
**改动**：
- 实现 `drivers/xiaohongshu/driver.py` + `routes.py`（P0：publish/text、search）。
- 或实现 `drivers/telegram/driver.py`（优先浏览器/桌面版，若走原生协议则另议）。
**验证**：通过 `/api/apps/{app_id}/xhs/publish` 成功发笔记。
### S6：面板适配与单容器多应用部署（不在本文档范围）
**目标**：面板支持多应用管理 UI 与"单容器多应用"部署选项。
**改动**（panel 层）：
- 面板新增"应用实例"管理页。
- 桌面入口支持选择"进入哪个应用窗口"。
- 实例创建支持"新建独立容器"或"加入已有容器"。
### S7：下线兼容层
**目标**：移除 alias，完成迁移。
**前提**：面板与所有已知适配器已切换到新路径。
**改动**：
- 删除旧路径 alias。
- `/api/status` 移除旧字段。
- major 版本升级到 v3.0.0。
---
## 12. 不做的事
### 12.1 完全不做
1. **不引入应用间隐式依赖**：driver 之间不互相调用，编排由外部完成。
2. **不做多容器 bridge 集群**：一个 bridge 进程只管一个容器内的应用，跨容器调度由面板负责。
3. **不做应用沙箱**：应用间共享 X server 与文件系统（受 Linux 权限控制），不做额外隔离。
4. **不做 RBAC**：`app_id` 级别的权限控制留给面板层，bridge 层只做 Bearer Token 全局鉴权。
5. **不改 KasmVNC 串流层**：桌面串流保持现状（全屏共享），不按应用切分串流。
6. **不做 OCR**：不引入 tesseract，页面识别靠 URL + 坐标启发式。
### 12.2 本阶段先不做
1. **不抽象 SQLCipher 解密**：解密能力暂留 `drivers/wechat/`，待第二个 SQLCipher 应用出现再抽公共层。
2. **不实现单容器多应用启动**：[docker/autostart](../docker/autostart) 当前只启动一个应用，改造它需要 panel/docker 同步调整，不在本阶段 bridge 文档范围。
3. **不新增非微信 driver**：先完成框架抽象与微信 driver 迁移，再落地 Xiaohongshu/Telegram driver。
4. **不替换全局 `SendQueue`**：S1 保持现有全局队列，S3 再下放到每个 `AppInstance`。
5. **不引入新依赖**：仍只使用 fastapi / uvicorn / pydantic / pillow / cryptography。
---
## 13. 关键决策记录
| 决策点 | 选择 | 理由 |
|--------|------|------|
| 文档定位 | 目标架构 + `[现状]` 注释 | 既描述最终形态，又不掩盖当前代码未落地的事实 |
| 本阶段重点 | 先让 bridge 在"多容器单应用"模式下可工作 | docker autostart 当前只支持一容器一应用；先完成 bridge 框架抽象，再扩展单容器多应用 |
| 文档范围 | 只聚焦 bridge 层 | panel UI、docker 多应用启动机制另行设计 |
| 抽象颗粒度 | 一应用一 driver（粗粒度） | 业务流程差异大，能力复用价值低 |
| 容器内应用数 | 目标为多实例并存，当前先单实例 | 满足"一容器多应用"长期需求，但本阶段保留单实例运行 |
| 路由前缀 | `/api/apps/{app_id}/*` + alias 过渡 | 实例独立寻址 + 向后兼容 |
| XdotoolBase 风格 | 组合（driver 持有 `self.xd`） | 避免多继承混乱 |
| SQLCipher 解密位置 | 留 drivers/wechat/ | YAGNI，等第二个应用再抽 |
| X11 并发控制 | 全局 UIScheduler 串行 | 多应用争用同一 X server 必须串行；当前尚未实现 |
| 应用间通信 | 显式编排（无直接调用） | 流程可观测、可调试 |
| 部署模型 | 单容器多应用 + 多容器单应用并存 | 兼顾资源效率与隔离性；当前仅多容器单应用可用 |
Reference in New Issue View Git Blame Copy Permalink