docs: 文档同步（README/API/架构/部署）
This commit is contained in:
+141
-28
@@ -14,6 +14,21 @@
|
||||
|
||||
---
|
||||
|
||||
**权限模型**（v2 起）：
|
||||
- 所有接口需登录；**查看类 GET 接口**（状态/列表/截图）所有登录用户可用
|
||||
- **写操作按权限位授权**（管理员拥有全部权限）：
|
||||
| 权限位 | 中文 | 覆盖接口 |
|
||||
|--------|------|---------|
|
||||
| `tasks` | 任务管理 | 任务/自定义动作/分组的增删改、启停、立即执行 |
|
||||
| `devices` | 设备控制 | 停止设备、释放占用、清除异常、前台扫描、元素抓取 |
|
||||
| `apks` | 应用管理 | APK 上传、安装、删除 |
|
||||
| `logs` | 日志查看 | `GET /api/logs` |
|
||||
- **用户管理接口仅管理员可用**（普通用户即使被授予业务权限也无法访问）
|
||||
- 无权限访问返回 `403 {"ok": false, "error": "无权限执行此操作..."}`
|
||||
- 当前用户权限查询：`GET /api/me`
|
||||
|
||||
---
|
||||
|
||||
## 1. 认证
|
||||
|
||||
### POST /login
|
||||
@@ -83,7 +98,7 @@
|
||||
|
||||
**worker_status 取值**：`idle` / `connecting` / `running` / `done` / `error` / `failed` / `released`
|
||||
|
||||
### POST /api/scan_foreground
|
||||
（权限：设备控制）
|
||||
|
||||
手动触发前台 App 扫描（后台异步执行，不打扰设备）。
|
||||
|
||||
@@ -176,12 +191,14 @@
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"jobs": [{"id": "abc123", "name": "抖音养号", "task_type": "douyin_nurture", "...": "..."}],
|
||||
"jobs": [{"id": "abc123", "name": "抖音养号", "task_type": "douyin_nurture",
|
||||
"next_run": "2026-08-12 09:00", "...": "..."}],
|
||||
"task_types": [...]
|
||||
}
|
||||
```
|
||||
`next_run`：下次真正执行时间（已按运行窗口跳过窗口外触发点，格式 `YYYY-MM-DD HH:MM`）；手动任务/已停用为 `null`。
|
||||
|
||||
### POST /api/jobs
|
||||
（权限：任务管理）
|
||||
|
||||
创建任务计划。
|
||||
|
||||
@@ -192,7 +209,7 @@
|
||||
"task_type": "douyin_nurture",
|
||||
"target": {"mode": "all"},
|
||||
"params": {"watch_count": 50, "actions": {"like": {"params": {"rate": 0.5}}}},
|
||||
"schedule": {"mode": "once"},
|
||||
"schedule": {"mode": "cron", "cron": "0 */2 * * *"},
|
||||
"retry": {"max_attempts": 3, "delay": 60},
|
||||
"enabled": true
|
||||
}
|
||||
@@ -203,7 +220,15 @@
|
||||
{"ok": true, "msg": "任务已创建", "job": {"id": "abc123", "...": "..."}}
|
||||
```
|
||||
|
||||
### PUT /api/jobs/:job_id
|
||||
`schedule` 字段格式：
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `mode` | `once` 手动 / `cron` 定时启动 / `cron_stop` 定时启动+停止 |
|
||||
| `cron` | 标准 5 段 cron：`分 时 日 月 周`（周 `0`/`7`=周日）；如 `0 */2 * * *` 每 2 小时整点 |
|
||||
| `stop_cron` | （cron_stop 必填）到点停止本任务 worker |
|
||||
| `window` | 可选，运行窗口 `{"start": "21:00", "end": "09:00"}`（每天重复，支持跨午夜）。窗口外定时触发和手动执行（`POST /api/jobs/:id/run`）均不启动，手动执行返回错误提示 |
|
||||
|
||||
（权限：任务管理）
|
||||
|
||||
更新任务计划。只需传要更新的字段。
|
||||
|
||||
@@ -217,7 +242,7 @@
|
||||
{"ok": true, "msg": "任务已更新", "job": {"...": "..."}}
|
||||
```
|
||||
|
||||
### DELETE /api/jobs/:job_id
|
||||
（权限：任务管理）
|
||||
|
||||
删除任务计划。
|
||||
|
||||
@@ -226,7 +251,7 @@
|
||||
{"ok": true, "msg": "任务已删除"}
|
||||
```
|
||||
|
||||
### POST /api/jobs/:job_id/run
|
||||
（权限：任务管理）
|
||||
|
||||
立即执行任务（异步，不阻塞）。
|
||||
|
||||
@@ -235,7 +260,7 @@
|
||||
{"ok": true, "msg": "任务 抖音养号 已触发"}
|
||||
```
|
||||
|
||||
### POST /api/jobs/:job_id/toggle
|
||||
（权限：任务管理）
|
||||
|
||||
启用/停用任务。
|
||||
|
||||
@@ -267,7 +292,7 @@
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/groups
|
||||
（权限：任务管理）
|
||||
|
||||
创建分组。
|
||||
|
||||
@@ -276,7 +301,7 @@
|
||||
{"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}
|
||||
```
|
||||
|
||||
### PUT /api/groups/:name
|
||||
（权限：任务管理）
|
||||
|
||||
更新分组。
|
||||
|
||||
@@ -285,7 +310,7 @@
|
||||
{"serials": ["192.168.1.100:5555", "192.168.1.101:5555"], "description": "更新描述"}
|
||||
```
|
||||
|
||||
### DELETE /api/groups/:name
|
||||
（权限：任务管理）
|
||||
|
||||
删除分组。
|
||||
|
||||
@@ -293,7 +318,7 @@
|
||||
|
||||
## 7. 运行控制
|
||||
|
||||
### POST /api/stop_device
|
||||
（权限：设备控制）
|
||||
|
||||
停止单台设备的 worker（并阻止后续重试）。
|
||||
|
||||
@@ -307,7 +332,7 @@
|
||||
{"ok": true, "msg": "已发送停止信号给 192.168.1.100:5555"}
|
||||
```
|
||||
|
||||
### POST /api/stop_all
|
||||
（权限：设备控制）
|
||||
|
||||
停止所有运行中的 worker。
|
||||
|
||||
@@ -316,7 +341,7 @@
|
||||
{"ok": true, "stopped": ["192.168.1.100:5555", "192.168.1.101:5555"]}
|
||||
```
|
||||
|
||||
### POST /api/release
|
||||
（权限：设备控制）
|
||||
|
||||
释放当前账户占用的所有 STF 设备（清理用）。
|
||||
|
||||
@@ -329,7 +354,7 @@
|
||||
|
||||
## 8. 用户管理
|
||||
|
||||
### GET /api/users
|
||||
（仅管理员）
|
||||
|
||||
列出所有用户。
|
||||
|
||||
@@ -338,7 +363,7 @@
|
||||
{"ok": true, "users": [{"id": 1, "username": "admin", "is_admin": true}]}
|
||||
```
|
||||
|
||||
### POST /api/users
|
||||
（仅管理员）
|
||||
|
||||
创建用户。
|
||||
|
||||
@@ -347,7 +372,7 @@
|
||||
{"username": "user1", "password": "pass123", "is_admin": false}
|
||||
```
|
||||
|
||||
### PUT /api/users/:uid
|
||||
（仅管理员）
|
||||
|
||||
更新用户（修改密码/管理员权限）。
|
||||
|
||||
@@ -356,7 +381,7 @@
|
||||
{"password": "newpass", "is_admin": true}
|
||||
```
|
||||
|
||||
### DELETE /api/users/:uid
|
||||
（仅管理员）
|
||||
|
||||
删除用户（不能删除 admin 和当前登录用户）。
|
||||
|
||||
@@ -364,7 +389,7 @@
|
||||
|
||||
## 9. 日志
|
||||
|
||||
### GET /api/logs
|
||||
（权限：日志查看）
|
||||
|
||||
查看日志文件内容。
|
||||
|
||||
@@ -394,7 +419,7 @@
|
||||
|
||||
列出所有自定义动作（步骤打包）。
|
||||
|
||||
### POST /api/custom_actions
|
||||
（权限：任务管理）
|
||||
|
||||
创建自定义动作。
|
||||
|
||||
@@ -403,11 +428,11 @@
|
||||
{"name": "登录流程", "icon": "📦", "steps": [{"type": "click", "...": "..."}]}
|
||||
```
|
||||
|
||||
### PUT /api/custom_actions/:action_id
|
||||
（权限：任务管理）
|
||||
|
||||
更新自定义动作。
|
||||
|
||||
### DELETE /api/custom_actions/:action_id
|
||||
（权限：任务管理）
|
||||
|
||||
删除自定义动作。
|
||||
|
||||
@@ -424,7 +449,7 @@
|
||||
{"ok": true, "running": true}
|
||||
```
|
||||
|
||||
### GET /api/uiauto/devices
|
||||
（权限：设备控制）
|
||||
|
||||
获取 uiauto2 已连接的设备列表。
|
||||
|
||||
@@ -433,7 +458,7 @@
|
||||
{"ok": true, "devices": [{"serial": "192.168.1.100:5555", "model": "Pixel 6"}]}
|
||||
```
|
||||
|
||||
### GET /api/uiauto/screenshot
|
||||
（权限：设备控制）
|
||||
|
||||
通过 uiauto2 获取设备截图（JPEG）。
|
||||
|
||||
@@ -444,7 +469,7 @@
|
||||
|
||||
**响应**：成功返回 `image/jpeg`，失败返回 JSON 错误。
|
||||
|
||||
### GET /api/uiauto/elements
|
||||
（权限：设备控制）
|
||||
|
||||
获取设备 UI 元素树。
|
||||
|
||||
@@ -498,7 +523,7 @@
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/apks/upload
|
||||
（权限：应用管理）
|
||||
|
||||
上传 APK 文件（自动解析包名/版本/应用名）。
|
||||
|
||||
@@ -512,11 +537,11 @@
|
||||
{"ok": true, "apk": {"...": "..."}, "msg": "上传成功: 抖音"}
|
||||
```
|
||||
|
||||
### DELETE /api/apks/:apk_id
|
||||
（权限：应用管理）
|
||||
|
||||
删除 APK 文件和记录。
|
||||
|
||||
### POST /api/apks/install
|
||||
（权限：应用管理）
|
||||
|
||||
批量安装 APK 到指定设备。
|
||||
|
||||
@@ -530,6 +555,19 @@
|
||||
{"ok": true, "msg": "开始安装 抖音 到 2 台设备"}
|
||||
```
|
||||
|
||||
### GET /api/apks/install/devices
|
||||
|
||||
可安装设备列表：STF 在线设备池 + 本机 adb 设备（**含 USB 有线连接**，serial 无冒号标记 `usb`）。
|
||||
安装弹窗用此列表，USB 设备安装时跳过 adb connect 直接安装。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "devices": [
|
||||
{"serial": "100.100.10.11:5555", "model": "22120RN86C", "source": "stf"},
|
||||
{"serial": "ZY322ABCDEF", "model": "", "source": "usb"}
|
||||
]}
|
||||
```
|
||||
|
||||
### GET /api/apks/install/status
|
||||
|
||||
获取安装任务实时状态。
|
||||
@@ -554,3 +592,78 @@
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. 维护（仅管理员）
|
||||
|
||||
维护页两个接口都**仅管理员可用**（普通用户即使有业务权限也访问不了，返回 403）。
|
||||
|
||||
### POST /api/stf/restart
|
||||
|
||||
一键重启 STF Docker 容器。通过 SSH 到部署机执行 `docker restart`，随后轮询 STF API 确认恢复。
|
||||
|
||||
- 目标与容器名：`STF_SSH_TARGET`（默认 `[email protected]`）、`STF_DOCKER_CONTAINER`（默认 `stf`）环境变量配置
|
||||
- 前置条件：本机可免密 SSH 到部署机
|
||||
- **有任务在运行时返回 409 拒绝执行**（STF 重启会重置设备占用状态）
|
||||
- 失败返回 502（SSH 不可达/容器名错误）；执行超时返回 408
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "STF 容器已重启", "detail": "stf: Up 3 seconds", "api_alive": true}
|
||||
```
|
||||
|
||||
### GET /api/adb/devices
|
||||
|
||||
维护终端设备列表：本地 adb 已连接（含 offline）+ STF 在线设备池（标记 `stf`）。
|
||||
供终端设备选择器使用——选中后前端自动附加 `-s <serial>`。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "devices": [
|
||||
{"serial": "100.100.10.11:5555", "state": "device"},
|
||||
{"serial": "100.100.10.13:5555", "state": "offline"},
|
||||
{"serial": "100.100.10.12:5555", "state": "stf"}
|
||||
]}
|
||||
```
|
||||
|
||||
### POST /api/adb/cmd
|
||||
|
||||
adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时）。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"cmd": "adb -s 100.100.10.11:5555 shell ls /sdcard"}
|
||||
```
|
||||
（开头的 `adb` 前缀可省略）
|
||||
|
||||
**安全红线**：包含 `kill-server` / `disconnect` 的命令直接拒绝（400）——会断开 STF provider 共享的 adb transport，导致全部设备被 STF 误判离线。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "stdout": "...", "stderr": "", "code": 0}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 步骤测试（仅管理员可触发，需"设备控制"权限）
|
||||
|
||||
### POST /api/steps/test
|
||||
|
||||
在指定设备上单步试执行（步骤编辑器"测试此步骤"按钮），验证选择器是否命中。
|
||||
只读连接（adb connect + u2），不占用/释放 STF，与运行中任务互不干扰。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{
|
||||
"serial": "100.100.10.11:5555",
|
||||
"step": {"type": "click", "label": "测试", "params": {"selector_type": "xpath", "selector_value": "//*[@resource-id=\"x\"]"}}
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "步骤已执行（测试）", "result": "命中"}
|
||||
```
|
||||
`result`：`命中` / `未找到` / `已执行`（无选择器命中语义的步骤）。
|
||||
无"设备控制"权限返回 403。
|
||||
|
||||
Reference in New Issue
Block a user