阶段3: 文档更新（ARCHITECTURE/DEPLOY 摘除 STF 章节，STF_REMOVAL 标记代码完成+220 停容器待确认）
This commit is contained in:
+17
-26
@@ -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）：
|
||||
|
||||
|
||||
+13
-26
@@ -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 <serial> 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` | `[email protected]` | 维护页"一键重启 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 启动服务
|
||||
|
||||
|
||||
+16
-11
@@ -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（可选，未来多实例/多机时）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user