butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 全面更新——README/API/DEVELOPMENT 摘除 STF 章节（设备池/型号/看屏/新端点文档，技术红线改为共享 transport 表述）

Browse Source
This commit is contained in:
butubb
2026-08-19 14:07:53 +08:00
parent 83ba489f57
commit 5543bad0e6
3 changed files with 132 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+42 -48
View File
@@ -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` | `[email protected]` | 维护页重启 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） |
doc/API.md
+73 -48
View File
@@ -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`（默认 `[email protected]`）、`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` 指定设备；浏览器 `<img src>` 直接渲染，客户端断开自动停止。数据源 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 <serial>`。
**响应**：
@@ -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"}`
doc/DEVELOPMENT.md
+17 -15
View File
@@ -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 里用 `<script src>` 引用
- **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
- **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb/STF 风暴，不要移除
- **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb 连接风暴，不要移除
---