docs: 全面更新——README/API/DEVELOPMENT 摘除 STF 章节（设备池/型号/看屏/新端点文档，技术红线改为共享 transport 表述）
This commit is contained in:
+73
-48
@@ -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"}`
|
||||
|
||||
Reference in New Issue
Block a user