From 5543bad0e6e08b9c3e0c520cdc70ceac334e8c80 Mon Sep 17 00:00:00 2001 From: butubb <1422726308@qq.com> Date: Wed, 19 Aug 2026 14:07:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E2=80=94=E2=80=94README/API/DEVELOPMENT=20=E6=91=98=E9=99=A4?= =?UTF-8?q?=20STF=20=E7=AB=A0=E8=8A=82=EF=BC=88=E8=AE=BE=E5=A4=87=E6=B1=A0?= =?UTF-8?q?/=E5=9E=8B=E5=8F=B7/=E7=9C=8B=E5=B1=8F/=E6=96=B0=E7=AB=AF?= =?UTF-8?q?=E7=82=B9=E6=96=87=E6=A1=A3=EF=BC=8C=E6=8A=80=E6=9C=AF=E7=BA=A2?= =?UTF-8?q?=E7=BA=BF=E6=94=B9=E4=B8=BA=E5=85=B1=E4=BA=AB=20transport=20?= =?UTF-8?q?=E8=A1=A8=E8=BF=B0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 90 ++++++++++++++++----------------- doc/API.md | 121 +++++++++++++++++++++++++++------------------ doc/DEVELOPMENT.md | 32 ++++++------ 3 files changed, 132 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index 32cf875..b5244d6 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # 设备自动化后台（platform-tools） -基于 **STF（Smartphone Test Farm）+ uiautomator2 + Flask** 的 Android 多设备自动化任务执行平台。 +基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化任务执行平台（已摘除 OpenSTF 依赖）。 -提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、APK 批量安装、UI 元素抓取等功能。内置抖音养号任务和通用步骤任务，可扩展任意 App 的自动化操作。 +提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、设备池管理（新增/停用/删除/型号采集）、APK 批量安装、网页远程看屏（MJPEG 实时流 + 触控）、UI 元素抓取等功能。内置抖音养号任务和通用步骤任务，可扩展任意 App 的自动化操作。 --- @@ -26,9 +26,9 @@ ### 环境要求 - **Python 3.10+**（推荐 3.12） -- **OpenSTF 服务**：已部署并运行，设备已接入 STF - **Windows / Linux / macOS**均可（adb 二进制需放对应平台版本到 `bin/adb/`） -- 设备需开启 **USB 调试**或通过 **adb 网络连接**（IP:5555）接入 +- 设备需开启 **USB 调试**（USB 连上后 `adb tcpip 5555` 转网络调试），并加入 Tailscale 获得 `100.100.10.x` IP +- 新增设备在后台「工具 → 设备池管理」添加 `IP:5555`（自动连接，任务运行时 u2 自动推送 atx-agent） ### 三步启动 @@ -36,8 +36,8 @@ # 1. 安装依赖 pip install -r requirements.txt -# 2. 修改配置（STF 地址、token、adb 路径等） -# 编辑 config.py 中的 STF_URL 和 STF_TOKEN +# 2. 修改配置（可选）：USB 设备在 220 上时配置 USB_ADB_HOST/PORT（默认 100.100.10.1:5037 已可用） +# 密钥类配置放 .env（WEB_SECRET_KEY / TAILSCALE_API_KEY） # 3. 启动 Web 后台 python web_server.py @@ -59,11 +59,12 @@ python web_server.py ### 首次使用流程 1. **登录后台** → 用 `admin/admin123` 登录，建议立即修改密码 -2. **查看设备** → 首页"监控"Tab 自动展示 STF 设备池状态 -3. **创建分组**（可选）→ "分组"Tab 按批次/项目给设备分组 -4. **创建任务** → "任务"Tab 新建任务，选择任务类型、目标设备、参数、调度 -5. **执行任务** → 任务列表点"立即执行"，或在"监控"Tab 勾选设备批量操作 -6. **查看日志** → "日志"Tab 实时查看运行日志 +2. **添加设备** → "工具 → 设备池管理"添加设备（serial 形如 `100.100.10.20:5555`，自动连接并采集型号） +3. **查看设备** → 首页"监控"Tab 展示设备池状态（在线/型号/任务） +4. **创建分组**（可选）→ "分组"Tab 按批次/项目给设备分组 +5. **创建任务** → "任务"Tab 新建任务，选择任务类型、目标设备、参数、调度 +6. **执行任务** → 任务列表点"立即执行"，或在"监控"Tab 勾选设备批量操作（亮屏/息屏/停止） +7. **查看日志** → "日志"Tab 实时查看运行日志 --- @@ -77,16 +78,15 @@ platform-tools/ │ ├── core/ # 核心基础设施层 │ ├── logger.py # 统一日志（分文件、10MB 滚动） -│ ├── stf_client.py # STF REST API 封装（占用/释放/远程连接） +│ ├── device_pool.py # 设备池（SQLite 清单 + adb 在线状态 + 型号采集） │ ├── adb_helper.py # adb 命令封装（全局锁，绝不 kill-server） -│ ├── device_worker.py # BaseWorker 基类 + STFDevice + 心跳看门狗 +│ ├── device_worker.py # BaseWorker 基类 + 设备生命周期 + 心跳看门狗 │ ├── task_manager.py # TaskManager 调度器 + 前台App扫描器 │ ├── u2_helper.py # uiautomator2 通用辅助函数 │ ├── uiauto_helper.py # uiautodev 元素抓取客户端 │ ├── apk_manager.py # APK 上传/解析/批量安装 │ ├── ocr.py # 屏幕 OCR（RapidOCR，条件判断 OCR 选择器） -│ ├── ssh_client.py # SSH 统一执行（paramiko 纯密码 / 免密密钥） -│ ├── stf_device_mgmt.py # STF 设备池管理（读写 220 脚本 + adb connect/disconnect） +│ ├── ssh_client.py # SSH 统一执行（paramiko 纯密码 / 免密密钥，预留运维用） │ ├── tailscale_client.py # Tailscale API v2 客户端 │ ├── models.py # SQLAlchemy 数据模型 + 数据库初始化 │ └── actions/ # 全局 Action 框架 @@ -99,7 +99,7 @@ platform-tools/ │ └── task.py # 步骤执行引擎（open_app/click/swipe/if_el...） │ ├── templates/admin/ # 前端页面 -│ ├── monitor.html # 单页应用（监控/任务/分组/日志/用户/维护/工具） +│ ├── monitor.html # 单页应用（监控/任务/分组/日志/用户/工具） │ └── login.html # 登录页 │ ├── static/admin/ # 前端 JS 模块（monitor.html 按依赖顺序加载） @@ -108,10 +108,12 @@ platform-tools/ │ ├── monitor.js # 监控页（设备表/截图/异常汇总） │ ├── editor.js # 步骤编辑器（拖拽/条件判断/元素抓取） │ ├── tasks.js # 任务 Tab + 自定义动作 -│ ├── tools.js # 工具 Tab（剪贴板/应用版本/STF设备/adb终端/Tailscale） +│ ├── tools.js # 工具 Tab（剪贴板/设备池管理/adb终端/Tailscale/远程看屏） │ ├── apps.js # 工具 Tab-应用管理（APK/设备已装应用） │ ├── admin.js # 管理 Tab（分组/日志/用户）+ 初始化 -│ └── custom.css # 自定义样式 +├── static/fonts/ # 自托管字体（Bricolage Grotesque + IBM Plex Mono） +│ +├── data/ │ ├── data/ # 运行时数据 │ ├── users.db # SQLite（用户/分组/任务/自定义动作/APK记录） @@ -140,26 +142,24 @@ platform-tools/ ### 设备生命周期 ``` -STF occupy（占用设备） +设备池选定设备（TaskManager._running 内存锁保证互斥） ↓ -STF remoteConnect（建立远程 ADB 隧道） - ↓ -adb connect（连接远程设备） +IP:5555 → adb connect 直连；USB（serial 无冒号）→ 本机 adb 或 220 远程 adb server ↓ u2.connect（连接 uiautomator2，自动推送 atx-agent） ↓ Worker.run_task（执行业务逻辑） ↓ -adb disconnect + STF release（释放设备） +释放（不 disconnect，遵守共享 adb transport 红线） ``` -> 直连模式：当设备 serial 为 `IP:5555` 格式时，直接 adb connect，不走 STF 桥接，更稳定。 +> 单实例部署下互斥由调度器内存锁保证；多实例场景可扩展 SQLite 行锁（见 doc/STF_REMOVAL.md 阶段 4）。 ### Worker — 单设备执行线程 每台设备对应一个 `Worker` 线程，继承 `BaseWorker`（`core/device_worker.py`）。基类已封装： -- STF 设备占用/释放（try/finally 保证释放） +- 设备获取（IP:5555 直连 / USB 远程 adb server，try/finally 保证释放） - adb 连接 + u2.connect（带 30 秒超时保护） - 状态上报（实时推送到前端监控大屏） - 异常捕获（设备离线不重试，其他异常按策略重试） @@ -225,21 +225,17 @@ self.set_progress(done=5, total=80, unit="视频", | 配置项 | 默认值 | 说明 | |-------|--------|------| -| `STF_URL` | `http://192.168.20.220:7100` | OpenSTF 服务地址 | -| `STF_TOKEN` | （.env 配置） | STF API Token，在 STF 个人设置里生成（密钥类配置统一放 `.env`） | | `ADB_PATH` | 自动识别 | adb 二进制路径，自动区分 Windows/Linux | | `WEB_HOST` | `0.0.0.0` | Web 监听地址（0.0.0.0 支持局域网访问） | | `WEB_PORT` | `18050` | Web 端口（避开 Windows 动态端口范围） | | `DATA_DIR` | `data/` | 持久化数据目录 | | `APK_DIR` | `data/apks/` | APK 文件存储目录 | -| `STF_SSH_TARGET` | `stf@192.168.20.220` | 维护页重启 STF / STF 设备管理的 SSH 目标（需免密） | -| `STF_DOCKER_CONTAINER` | `stf` | 220 上 STF Docker 容器名 | -| `STF_ADB_CONTAINER` | `adb` | 220 上 adb Docker 容器名（STF 设备管理执行 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 server） | +| `USB_ADB_PORT` | `5037` | 220 adb 容器监听端口（host 网络模式） | | `TAILSCALE_API_KEY` | （.env 配置） | Tailscale 管理 API key（Settings → API Access Tokens） | | `TAILSCALE_TAILNET` | 按邮箱前缀 | tailnet 名/ID | -**必须修改的配置**：`.env` 里的 `STF_TOKEN`（密钥类统一放 `.env`，不入 git）；`STF_URL` 在 `config.py`。 +**必须修改的配置**：`.env` 里的 `WEB_SECRET_KEY`（会话密钥，不入 git）；其余均为可选（默认值开箱即用）。 --- @@ -247,17 +243,16 @@ self.set_progress(done=5, total=80, unit="视频", ### 页面结构 -单页应用（`templates/admin/monitor.html`），7 个 Tab；任务/工具 Tab 内部再有页内子分栏： +单页应用（`templates/admin/monitor.html`），6 个 Tab；任务/工具 Tab 内部再有页内子分栏： | Tab | 功能 | 可见性 | |-----|------|--------| -| 监控 | 设备状态大屏：在线/离线、运行任务、当前动作、进度条、前台 App、截图、停止 | 所有登录用户（设备操作按钮需"设备控制"权限） | +| 监控 | 设备状态大屏：在线/离线、型号、运行任务、当前动作、进度条、前台 App、截图、勾选批量操作（亮屏/息屏/停止） | 所有登录用户（设备操作按钮需"设备控制"权限） | | 任务 | 子分栏：任务计划（CRUD/启用停用/立即执行/下次运行时间/**离线设备自动跳过**）、自定义动作（打包复用） | 所有登录用户可看，写操作需"任务管理"权限 | | 分组 | 设备分组管理：创建/编辑/删除分组 | 所有登录用户可看，写操作需"任务管理"权限 | | 日志 | 实时日志查看：按模块切换（core/task/web/action） | 需"日志查看"权限 | | 用户 | 用户管理：创建/删除/修改密码/分配权限 | 仅管理员 | -| 维护 | STF 服务：一键重启容器 | 仅管理员 | -| 工具 | 子分栏：剪贴板注入、adb 远程终端（快捷命令/自动 `-s`/卸载 STF agent）、Tailscale 管理（改名/授权/密钥不过期/设置IP/auth key）、应用管理（APK 上传安装）、应用版本管理（按包名查所有设备版本）、设备已装应用、STF 设备管理（读写 220 脚本维护设备池） | 仅管理员 | +| 工具 | 子分栏：剪贴板注入、adb 远程终端（快捷命令/自动 `-s`）、**设备池管理**（新增/停用/删除/一键重连/型号采集）、**远程看屏**（MJPEG 实时流 + 点击/滑动/按键/文字）、Tailscale 管理（改名/授权/密钥不过期/设置IP/auth key）、应用管理（APK 上传安装）、应用版本管理（按包名查所有设备版本）、设备已装应用 | 仅管理员 | 任务/工具 Tab 的子分栏会记住上次选中的位置；无权限的 tab 和按钮自动隐藏。 @@ -284,10 +279,9 @@ self.set_progress(done=5, total=80, unit="视频", | 设备状态 | 处理方式 | |---------|---------| -| worker 运行中 | 复用已有 ADB 连接查询 | -| 自己占用 | 通过 STF remoteConnect 隧道查询（不 occupy/release） | -| 完全空闲 | 返回"空闲"（不主动 adb connect，避免 STF 误判离线） | -| 他人占用 | 标记"(他人占用)" | +| worker 运行中（IP:5555） | 复用已有 ADB 连接查询 | +| worker 运行中（USB） | 经 220 远程 adb server 查询 | +| 完全空闲 | 返回"空闲"（不主动 connect，避免扰动共享 adb transport） | ### 截图功能 @@ -357,7 +351,7 @@ self.set_progress(done=5, total=80, unit="视频", | 文件 | 模块前缀 | 内容 | |------|---------|------| -| `logs/core.log` | `core.*` | STF/adb/worker/task_manager 核心程序 | +| `logs/core.log` | `core.*` | adb/worker/task_manager/设备池 核心程序 | | `logs/task.log` | `task.*` | 任务执行（worker 业务逻辑） | | `logs/web.log` | `web.*` | Web 请求/管理 | | `logs/action.log` | `action.*` | 操作执行（点赞/评论等） | @@ -396,14 +390,13 @@ netsh interface ipv4 show excludedportrange protocol=tcp 修改 `config.py` 中的 `WEB_PORT` 到一个不在排除范围内的端口。 -### STF 设备显示离线但实际在线 +### 设备显示离线 -STF 状态有缓存，`present=True` 不代表设备真在线。用"扫描前台App"按钮复测，或直接尝试执行任务。 +先确认本机 `adb devices` 能看到设备（工具 → 设备池管理 → 一键重连）；看不到则检查 Tailscale 是否在线、设备是否加入了正确的 tailnet（平台与设备必须在同一 tailnet）。 -### 设备一直被占用无法释放 +### 新增设备后任务不调度它 -监控页点"**强制释放占用**"按钮释放当前账户占用的所有设备； -无人值守场景可在 `.env` 设置 `AUTO_RELEASE_STALE_OCCUPY=true`（单实例）启动自动清理。 +新设备需在「工具 → 设备池管理」添加（serial 为 `IP:5555`），仅连上 adb 不会进入设备池。添加后自动连接并采集型号，下一轮任务即可调度。 ### u2.connect 卡死 @@ -442,7 +435,8 @@ finally: | [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) | **开发手册**：开发流程、git 工作流、技术红线、环境、本地开发 | | [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务开发指南（新增 App 任务的完整模板和规范） | | [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层设计、数据流、关键设计决策） | -| [doc/DEPLOY.md](doc/DEPLOY.md) | 部署指南（环境准备、STF 配置、生产部署） | +| [doc/DEPLOY.md](doc/DEPLOY.md) | 部署指南（环境准备、设备池配置、生产部署） | +| [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md) | STF 摘除迁移记录（阶段 0-3 已完成，含多实例锁方案） | | [doc/API.md](doc/API.md) | API 接口文档（全部 HTTP 接口说明） | > **注意**：所有 git 操作（含 push 到 dev）都需负责人确认后才能执行，详见开发手册。修改 `core/`、`tasks/`、`templates/` 后需重启服务/强刷浏览器才生效。 @@ -459,4 +453,4 @@ finally: | uiautomator2 | Android UI 自动化 | | uiautodev | UI 元素抓取（步骤编辑器"抓取元素"） | | pyaxmlparser | APK 元信息解析 | -| OpenSTF | 设备农场管理（占用/释放/远程 ADB） | +| 自建设备池 | 设备清单/在线状态/型号（SQLite + adb） | diff --git a/doc/API.md b/doc/API.md index 4af5980..dbb29b6 100644 --- a/doc/API.md +++ b/doc/API.md @@ -343,7 +343,7 @@ （权限：设备控制） -释放当前账户占用的所有 STF 设备（清理用）。 +（已随 STF 摘除移除，此接口不再存在；设备互斥由调度器内存锁保证） **响应**： ```json @@ -557,7 +557,7 @@ ### GET /api/apks/install/devices -可安装设备列表：STF 在线设备池 + 本机 adb 设备（**含 USB 有线连接**，serial 无冒号标记 `usb`）。 +可安装设备列表：设备池在线设备（标记 `pool`）+ 本机 adb 设备（**含 USB 有线连接**，serial 无冒号标记 `usb`）。 安装弹窗用此列表，USB 设备安装时跳过 adb connect 直接安装。 **响应**： @@ -598,26 +598,81 @@ ## 13. 维护 / 工具（仅管理员） 以下接口都**仅管理员可用**（普通用户即使有业务权限也访问不了，返回 403）。 -维护页现仅含 STF 服务管理；adb 终端、Tailscale 管理、应用管理、STF 设备管理等 -已集中到"工具"页（页内子分栏），API 不变。 +设备池管理、远程看屏、adb 终端等集中在"工具"页（页内子分栏）。 -### POST /api/stf/restart +### GET /api/devices/pool -一键重启 STF Docker 容器。通过 SSH 到部署机执行 `docker restart`，随后轮询 STF API 确认恢复。 - -- 目标与容器名：`STF_SSH_TARGET`（默认 `stf@192.168.20.220`）、`STF_DOCKER_CONTAINER`（默认 `stf`）环境变量配置 -- 前置条件：本机可免密 SSH 到部署机 -- **有任务在运行时返回 409 拒绝执行**（STF 重启会重置设备占用状态） -- 失败返回 502（SSH 不可达/容器名错误）；执行超时返回 408 +设备池清单（SQLite devices 表），含实时在线状态。**权限**：`devices`。 **响应**： ```json -{"ok": true, "msg": "STF 容器已重启", "detail": "stf: Up 3 seconds", "api_alive": true} +{"ok": true, "devices": [ + {"serial": "100.100.10.20:5555", "name": "", "model": "22120RN86C", + "enabled": true, "online": true, "note": "", "created_at": "2026-08-17 11:10"} +]} ``` +### POST /api/devices/pool/add + +添加/更新设备（upsert）。**权限**：`devices`。 +**请求**（JSON）：`{"serial": "100.100.10.20:5555", "name": "备注", "note": ""}` +IP:5555 设备添加后立即尝试 adb connect，并后台采集型号（getprop ro.product.model）。 + +### POST /api/devices/pool/toggle + +启用/停用设备（停用后不参与任务调度）。**权限**：`devices`。 +**请求**（JSON）：`{"serial": "...", "enabled": false}` + +### POST /api/devices/pool/remove + +从设备池删除（不再参与调度，不影响设备本身）。**权限**：`devices`。 +**请求**（JSON）：`{"serial": "..."}` + +### POST /api/devices/pool/reconnect + +一键重连：并发 adb connect 池内全部 IP:5555 设备（后台执行），完成后自动批量刷新型号。**权限**：`devices`。 + +### POST /api/devices/pool/refresh_models + +批量采集池内在线设备的型号（后台执行）。**权限**：`devices`。 + +### GET /api/screen/stream + +远程看屏：MJPEG 实时画面流（`multipart/x-mixed-replace`）。**权限**：`devices`。 + +`?serial=xxx` 指定设备；浏览器 `` 直接渲染，客户端断开自动停止。数据源 u2（atx-agent minicap，约 3-6 帧/秒）。 + +### POST /api/screen/tap + +点击设备屏幕。**权限**：`devices`。 +**请求**（JSON）：`{"serial": "...", "x": 360, "y": 800}`（设备原生分辨率坐标） + +### POST /api/screen/swipe + +滑动。**请求**（JSON）：`{"serial": "...", "x1": 360, "y1": 1200, "x2": 360, "y2": 600, "duration": 0.2}` + +### POST /api/screen/key + +按键。**请求**（JSON）：`{"serial": "...", "key": "back"}`。 +支持：back/home/recent/menu/power/volume_up/volume_down/enter/delete/search/camera + +### POST /api/screen/text + +输入文字（需焦点在输入框）。**请求**（JSON）：`{"serial": "...", "text": "你好"}` + +### POST /api/device/screen_all + +批量亮屏/息屏（并发）。**权限**：`devices`。 + +**请求**（JSON）： +```json +{"mode": "on", "serials": ["100.100.10.11:5555"]} +``` +`serials` 可选：指定设备（离线自动过滤）；不带则作用于全部在线设备。息屏会中断运行中的任务，前端有确认提示。 + ### GET /api/adb/devices -维护终端设备列表：本地 adb 已连接（含 offline）+ STF 在线设备池（标记 `stf`）。 +维护终端设备列表：本地 adb 已连接（含 offline）+ 设备池已配置设备（标记 `pool`）。 供终端设备选择器使用——选中后前端自动附加 `-s `。 **响应**： @@ -639,7 +694,7 @@ adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时 ``` （开头的 `adb` 前缀可省略） -**安全红线**：包含 `kill-server` / `disconnect` 的命令直接拒绝（400）——会断开 STF provider 共享的 adb transport，导致全部设备被 STF 误判离线。 +**安全红线**：包含 `kill-server` / `disconnect` 的命令直接拒绝（400）——会断开共享的 adb transport，导致全部设备连接重建。 **响应**： ```json @@ -653,7 +708,7 @@ adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时 ### POST /api/steps/test 在指定设备上单步试执行（步骤编辑器"测试此步骤"按钮），验证选择器是否命中。 -只读连接（adb connect + u2），不占用/释放 STF，与运行中任务互不干扰。 +只读连接（adb connect + u2），与运行中任务互不干扰。 **请求**（JSON）： ```json @@ -721,7 +776,7 @@ adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时 {"ipv4": "100.100.10.16"} ``` -⚠ 改 IP 会断开设备当前 tailscale 会话；平台设备池 serial 随之变化，需同步更新 STF 设备池/分组/任务目标。 +⚠ 改 IP 会断开设备当前 tailscale 会话；平台设备池 serial 随之变化，需同步更新设备池/分组/任务目标。 ### DELETE /api/tailscale/devices/:device_id @@ -746,7 +801,7 @@ adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时 ## 16. 工具（仅管理员） -工具页（剪贴板注入 / 应用版本管理 / STF 设备管理）接口，均仅管理员可用。 +工具页（剪贴板注入 / 应用版本管理 / 设备池管理）接口，均仅管理员可用。 ### POST /api/tools/clipboard/set @@ -756,7 +811,7 @@ adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时 ```json {"serials": ["100.100.10.11:5555", "0123456789ABCDEF"], "text": "要注入的文字"} ``` -设备来源与维护终端一致（本地 adb 含 USB + STF 池）。 +设备来源与维护终端一致（本地 adb 含 USB + 设备池）。 实现：u2 `jsonrpc.setClipboard`（实测 `cmd clipboard` 在 MIUI 上不存在），支持中文/引号/换行； IP 设备先 adb connect（已连接跳过，绝不 disconnect），USB 设备首次自动推送 atx-agent。 @@ -781,33 +836,3 @@ IP 设备先 adb connect（已连接跳过，绝不 disconnect），USB 设备 "results": {"100.100.10.11:5555": {"installed": true, "version_name": "28.5.0", "version_code": "280500"}}} ``` 未安装返回 `installed: false`；查询失败的设备带 `error` 字段。 - -### GET /api/stf/devmgmt/status - -STF 设备管理状态：connect_devices.sh 脚本配置的 IP 列表 + 220 上 adb 实际连接状态。 - -**响应**： -```json -{"ok": true, - "configured": ["100.100.10.10", "100.100.10.11"], - "connected": [{"serial": "100.100.10.10:5555", "state": "device"}]} -``` - -### POST /api/stf/devmgmt/add - -添加设备：写入 220 上 `connect_devices.sh` 的 DEVICES 列表 + 立即 `docker exec adb adb connect`。 -设备不可达时 connect 会 15 秒超时兜底（220 侧 `timeout`），但仍保留在脚本中，cron 每 5 分钟自动重试。 - -**请求**（JSON）：`{"ip": "100.100.10.20"}`（可带 `:5555`，自动归一化） - -**响应**： -```json -{"ok": true, "msgs": ["已写入脚本 /mnt/data/openstf/connect_devices.sh", "连接超时（设备当前不可达），已保留在脚本中，cron 会每 5 分钟自动重试"]} -``` - -### POST /api/stf/devmgmt/remove - -移除设备：从脚本 DEVICES 删除 + `adb disconnect`（设备从 STF 池下线，任务不再分配）。 -注意：断开的是 220（STF provider 侧）的 adb 连接，与本机任务直连的 adb 相互独立。 - -**请求**（JSON）：`{"ip": "100.100.10.20"}` diff --git a/doc/DEVELOPMENT.md b/doc/DEVELOPMENT.md index 32de8b1..c977548 100644 --- a/doc/DEVELOPMENT.md +++ b/doc/DEVELOPMENT.md @@ -13,7 +13,7 @@ | `dev` | **开发分支**，所有新功能/修复都在这里开发 | | `main` | **生产分支**（主分支），只放已确认的稳定版本 | -生产环境 = STF 主机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。 +生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。 ### 1.2 git 操作铁律（重要） @@ -42,47 +42,49 @@ | 环境 | 位置 | 说明 | |------|------|------| | 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` | -| 生产机 | STF 主机 220 的 `auto_control` | python-app 容器，`network_mode: host` | -| STF 服务 | `192.168.20.220:7100` | 设备农场（REST API） | -| 设备 | Tailscale `100.100.10.x:5555` | 5 台 Xiaomi，本机 `100.100.10.2` 在 tailnet 内 | +| 生产机 | 部署机 220 的 `auto_control` | python-app 容器，`network_mode: host` | +| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（2026-08-18 `docker stop stf`，代码已摘除依赖） | +| adb 容器 | 220 上 `adb`（host 网络 5037） | USB 设备远程 adb server；网络设备补连用 | +| 设备 | Tailscale `100.100.10.x:5555` | Xiaomi 舰队，本机 `100.100.10.2` 在 tailnet 内 | | uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） | ### 2.1 adb key（关键） -- 本机 `~/.android/adbkey` 已换成 **STF adb 容器的 key**（5 台设备都信任） +- 本机 `~/.android/adbkey` 沿用历史 key（原取自 STF adb 容器，全部设备都信任） - **不要随意更换 key**——设备会变 unauthorized 连不上 - 旧 key 备份在 `~/.android/adbkey.local.bak` - 生产环境的容器也需要用这把 key（部署时处理） ### 2.2 设备连接方式 -- 设备 serial 是 `IP:5555`（Tailscale 地址），**直连**优先 -- STF 桥接（remoteConnect）在此环境**不可用**（隧道 adb key 认证失败，显示 unauthorized） +- 设备 serial 是 `IP:5555`（Tailscale 地址），**直连**优先（只 connect、绝不 disconnect） +- USB 设备（serial 无冒号）：插本机走本地 adb；插 220 走远程 adb server（`USB_ADB_HOST:5037`） - 本机已在 tailnet 内，直连可靠且快（<1s） +- 设备加入/退出平台：工具 → 设备池管理（SQLite 清单，自动连接 + 型号采集） --- -## 3. 技术红线（开发限制）—— 违反会打断 STF，需人工恢复 +## 3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复 -这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备被 STF 误判离线、需人工处理： +这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备连接被全部重建（历史原因：STF provider 共享同一 adb transport，摘除 STF 后仍保留此约束）： 1. **绝不 `adb kill-server`** - - 会断开所有设备的 adb transport，STF 对全网设备误判离线并触发重连 + - 会断开所有设备的 adb transport，全部设备连接被重建，运行中任务中断 - 见 `core/adb_helper.py` 2. **绝不对 `IP:5555` 设备 `adb disconnect`** - - STF provider 共享该地址的 adb transport，disconnect 会断 STF + - 该地址的 adb transport 是共享的（历史与 STF provider 共用），disconnect 会断掉全部相关连接 - 直连模式下 `release()` 不 disconnect - 见 `core/device_worker.py` `STFDevice.release()` 3. **空闲设备扫描不主动 connect/disconnect** - - STF provider 内部通过 IP:5555 维持连接，外部 connect/disconnect 会让 STF 误判离线 + - IP:5555 的 transport 由多方共享（历史与 STF provider 共用），外部 connect/disconnect 会扰动共享连接 - `_ForegroundScanner._scan_free` 对空闲设备直接返回"空闲"，不碰 adb - 见 `core/task_manager.py` -4. **adb key 保持为 STF 容器的 key**（见 2.1） +4. **adb key 保持历史 key 不变**（见 2.1，设备信任该 key） -5. **直连优先，不引入 STF 桥接**（见 2.2） +5. **直连优先，不引入第三方桥接**（见 2.2） ### 3.1 其他开发限制 @@ -92,7 +94,7 @@ - **数据库是 SQLite**（`data/users.db`，WAL 模式）：运行时数据不提交 git - **前端 JS 在 `static/admin/monitor.js`**（已从 HTML 拆分），HTML 里用 `