diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 83a3c2b..e061233 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -37,15 +37,15 @@ └──────────────┘ │ 状态/心跳 │ u2 操作 │ │ ▼ │ JSON API │ ┌─────────────────┐ - ▼ ┌──────────────┐ │ STF Device / adb │ -┌──────────────┐ │ 看门狗监控 │ └─────────────────┘ -│ web_server │ └──────────────┘ -│ (Flask API) │ + ▼ ┌──────────────┐ │ 设备 adb │ +┌──────────────┐ │ 看门狗监控 │ │ (IP:5555 直连 │ +│ web_server │ └──────────────┘ │ / USB 远程) │ +│ (Flask API) │ └─────────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ -│ data/users.db│ SQLite 持久化（用户/分组/任务/自定义动作/APK记录） +│ data/users.db│ SQLite 持久化（用户/分组/任务/设备池/自定义动作/APK记录） └──────────────┘ ``` @@ -64,34 +64,25 @@ ## 3. 核心模块详解 -### 3.1 STFClient（`core/stf_client.py`） +### 3.1 DevicePool（`core/device_pool.py`） -OpenSTF REST API 封装，负责设备池管理。 +设备池（已摘除 OpenSTF）：SQLite `devices` 表 = 设备清单，本机 adb = 在线状态。 **关键设计**： -- 所有请求带 `timeout=(5, 15)`，避免 STF 网关 504 时卡死 -- `remote_connect` 带重试（3 次），STF provider 慢启动时需要 -- 错误分类：`DeviceOfflineError`（不重试）/ `STFNetworkError` / `DeviceConflictError`（自动重试） -- 占用冲突自动清理重试（偶发 "already in use" 脏状态） - -**核心方法**： - -| 方法 | 说明 | -|------|------| -| `list_all_devices()` | 返回 STF 上所有设备（含状态） | -| `list_free_devices()` | 返回可占用的空闲设备 | -| `list_my_devices()` | 返回当前账户已占用的设备 | -| `occupy(serial)` | 占用设备（冲突自动重试） | -| `release(serial)` | 释放设备（含远程断开） | -| `remote_connect(serial)` | 建立远程 ADB 隧道，返回 remoteConnectUrl | -| `remote_disconnect(serial)` | 断开远程 ADB 隧道 | +- `list_configured()` — 清单（管理页维护，enabled=False 不参与调度） +- `list_online()` — 本机 adb 在线设备；池内有 USB 设备（serial 无冒号）时合并 220 + 远程 adb server（`USB_ADB_HOST:PORT`，host 网络模式 5037）状态 +- `list_ready()` — 清单 ∩ 在线（任务调度用） +- CRUD — `add_device`（upsert）/ `remove_device` / `set_enabled` +- 单实例互斥由 `TaskManager._running[serial]` 内存锁保证（无跨实例占用概念） +- 全模块不 connect/kill-server/disconnect（遵守共享 adb transport 红线） ### 3.2 STFDevice + BaseWorker（`core/device_worker.py`） **STFDevice** — 单设备生命周期管理： -- `acquire()`：占用 → remoteConnect → adb connect -- `release()`：adb disconnect → remoteDisconnect → STF release -- 直连模式：serial 为 `IP:5555` 时直接 adb connect，不走 STF 桥接 +- `acquire()`：IP:5555 直连 adb connect；USB（serial 无冒号）校验 220 远程 adb server 可见性 +- `release()`：无操作（不 disconnect，红线） +- 互斥由 TaskManager `_running` 保证，设备池负责在线判断 **BaseWorker** — 通用 Worker 基类（继承 threading.Thread）： diff --git a/doc/DEPLOY.md b/doc/DEPLOY.md index 5c85d95..00d3abf 100644 --- a/doc/DEPLOY.md +++ b/doc/DEPLOY.md @@ -17,15 +17,14 @@ python --version # 应输出 3.10+ pip --version ``` -### 1.2 OpenSTF 服务 +### 1.2 设备池（已摘除 OpenSTF 依赖） -本项目依赖 OpenSTF 管理设备池。如已有 STF 服务，跳过本节。 +设备池由平台自身管理（SQLite `devices` 表 + 本机 adb 在线状态），**不再依赖 OpenSTF**。 +新增设备在管理后台「工具 → 设备池管理」添加（serial 形如 `100.100.10.x:5555`）。 -STF 部署参考官方文档：https://github.com/DeviceFarmer/stf - -**需要获取的信息**： -- STF 服务地址（如 `http://192.168.20.220:7100`） -- STF API Token（在 STF 个人设置 → API Keys 里生成） +USB 设备（serial 无冒号）插在部署机（220）时，经 220 的 adb server 驱动： +- 220 的 adb 容器需为 **host 网络模式**（5037 已监听所有网卡，含 Tailscale） +- 平台配置 `USB_ADB_HOST`（默认 `100.100.10.1`）/ `USB_ADB_PORT`（默认 5037） ### 1.3 adb 工具 @@ -41,8 +40,9 @@ STF 部署参考官方文档：https://github.com/DeviceFarmer/stf 设备需满足： - 开启 **USB 调试**（设置 → 开发者选项） -- 或通过 **adb 网络连接**（设置 → 开发者选项 → 无线调试，获取 IP:5555） -- 已接入 STF 设备池（STF 显示 present=True, ready=True） +- 转网络调试：USB 连上后 `adb -s tcpip 5555`（管理后台「adb 终端」有一键快捷命令） +- 设备加入 Tailscale（同一账号，获得 100.100.10.x IP） +- 在「工具 → 设备池管理」添加 `IP:5555`（自动尝试连接，任务运行时 u2 自动推送 atx-agent） --- @@ -87,15 +87,9 @@ pip install -r requirements.txt ```ini # .env 示例 -STF_TOKEN=你的STF_API_Token WEB_SECRET_KEY=随机字符串（会话密钥，python -c "import secrets;print(secrets.token_hex(32))" 生成） TAILSCALE_API_KEY=你的Tailscale_API_key -``` - -`config.py` 只改非密钥项，如 `STF_URL`： - -```python -STF_URL = "http://你的STF地址:端口" +# USB_ADB_HOST=100.100.10.1 # 220 的 Tailscale IP（USB 设备远程 adb server，默认值已可用） ``` 其他配置按需调整： @@ -105,21 +99,14 @@ STF_URL = "http://你的STF地址:端口" | `WEB_HOST` | `0.0.0.0` | 仅本机访问改为 `127.0.0.1` | | `WEB_PORT` | `18050` | 端口冲突时修改 | | `ADB_PATH` | 自动识别 | 用自定义 adb 时修改 | -| `STF_SSH_TARGET` | `stf@192.168.20.220` | 维护页"一键重启 STF 容器"与工具页"STF 设备管理"的 SSH 目标 | -| `STF_SSH_PASSWORD` | （空） | SSH 密码认证（.env 配置后走 paramiko 密码登录，跨平台）；留空则退回系统 ssh 免密密钥（BatchMode） | -| `STF_DOCKER_CONTAINER` | `stf` | 220 上 STF Docker 容器名（`docker ps` 查看） | -| `STF_ADB_CONTAINER` | `adb` | 220 上 adb Docker 容器名（STF 设备管理执行 `docker exec adb adb ...`） | -| `STF_SCRIPT_PATH` | `/mnt/data/openstf/connect_devices.sh` | STF 设备池脚本路径（工具页增删设备会读写其 DEVICES 列表） | +| `USB_ADB_HOST` | `100.100.10.1` | USB 设备所在部署机（220）的 Tailscale IP | +| `USB_ADB_PORT` | `5037` | 220 adb 容器监听端口（host 网络模式） | | `TAILSCALE_TAILNET` | 按邮箱前缀 | tailnet 名称/ID（个人账号一般为登录邮箱前缀） | > **未配置 `WEB_SECRET_KEY`**：启动时随机生成（每次重启登录态失效，生产务必配置固定值）。 > **工具页 Tailscale 管理前置**：`.env` 写入 `TAILSCALE_API_KEY` 后重启服务； > 未配置时管理分区显示明确提示，不影响其他功能。 - -> **维护页 STF 重启 / 工具页 STF 设备管理前置**：需能 SSH 到部署机——两种方式任选： -> 1. `.env` 配置 `STF_SSH_PASSWORD` 走密码认证（paramiko，无需额外工具，推荐） -> 2. 免密密钥：本机公钥加入目标机 `authorized_keys` -> 且 `STF_DOCKER_CONTAINER`/`STF_ADB_CONTAINER` 与真实容器名一致；未配置好时按钮会返回明确错误。 +> （历史遗留的 `STF_URL`/`STF_TOKEN`/`STF_SSH_*` 等配置已废弃，代码不再读取。） ### 2.4 启动服务 diff --git a/doc/STF_REMOVAL.md b/doc/STF_REMOVAL.md index dfbc2d2..d5afbc8 100644 --- a/doc/STF_REMOVAL.md +++ b/doc/STF_REMOVAL.md @@ -120,18 +120,23 @@ STF 当前仅提供：occupy/release 互斥、present+ready 健康信号、设 走 token 或仅内网/Tailscale 暴露） - 备选方案（若 ws-scrcpy 试用不达标）：自建 minicap JPEG 流 + u2 触控注入（2-3 天） -## 阶段 3：界面清理 + STF 停用（阶段 2 稳定后） +## 阶段 3：界面清理 + STF 停用（已完成代码部分，2026-08-18） -- `templates/admin/monitor.html`：删「一键重启 STF 容器」区块 (460-468)、设备表 STF 占用列 (328)； - 「STF 设备管理」子分栏改名为「设备池管理」（增删改走 SQLite，SSH 部分退役） -- 维护终端：删「卸载/检查 STF agent」按钮（agent 已无用）；如需补「重启 u2 atx-agent」 - （u2 断开重连会自动重推 atx-agent，一般无需手动） -- 文案清理：tools.js / apps.js / editor.js 中"STF 池"→"设备池"，`api/adb/devices` 的 - source 字段 `stf` → `pool` -- 删除 `core/stf_client.py`、`STFClient` 全部引用；`config.py` 中 STF_URL/STF_TOKEN 标注废弃 -- 220 侧：**停 STF 容器**（`docker stop stf`，不删除）；connect_devices.sh cron 退役， - 补连职责由平台侧定时器（对池内设备 adb connect 检查）接管 -- 更新 `doc/ARCHITECTURE.md` / `doc/DEPLOY.md` 相关章节 +✅ 已完成的代码部分（commit a5ce57b，-956 行）： +- 删「一键重启 STF 容器」区块、设备表 STF 占用列、强制释放占用按钮 +- 删「STF 设备管理」子分栏（设备池管理面板接管）+ 卸载/检查 STF agent 按钮 +- 删除 `core/stf_client.py`、`core/stf_device_mgmt.py` 及全部引用（含 web_server + 全部 STF API、启动残留清理、设备池首导 seed） +- 错误类（STFError/DeviceOfflineError）迁入 `core/device_worker.py`； + `create_worker`/`BaseWorker` 去掉 stf 参数；`stf_occupied` 字段全链路移除 +- 文案清理（tools/apps/editor/monitor）+ `config.py` STF/SSH 配置标注废弃 +- 文档更新（ARCHITECTURE/DEPLOY） + +⏳ 待人工确认的最后一步（220 侧）： +- **停 STF 容器**（`docker stop stf`，不删除，可 `docker start stf` 回滚） +- 保留 adb 容器（host 网络 5037，USB 设备远程驱动依赖它）； + connect_devices.sh cron 可留可退役（对网络设备补连已无必要，无害） +- 停容器前请确认：任务调度/看屏/设备池管理已稳定运行 ≥1 天 ## 阶段 4（可选，未来多实例/多机时）