架构说明

系统架构

n8n / 操作员
      │ REST
FastAPI ─── SQLAlchemy ─── SQLite（持久化任务、结果、设备）
      │                      │
      └── 调度循环 ─── 到期 READY 任务 ─── 7 个 worker 槽位
                                               │ 每台设备互斥锁 + 数据库任务认领
                              Publisher 统一接口
                       ┌──────────┴──────────┐
                 MockPublisher       OfficialApiPublisher / AndroidRpaPublisher
                                               │
                 中央 Agent API ← HTTPS 轮询 ← Windows/Mac/Linux 控制电脑上的 Agent
                                                       │
                                                  本机 ADB + Appium
                                                       ▼
                                                      手机

手机连接方式

本机模式由服务器直接运行 ADB 和 Appium。手机接在另一台电脑时，由手机旁边的控制 Agent 通过 USB 使用本机 ADB/Appium，并主动通过 HTTPS 轮询中央 API。每个控制节点使用独立 Bearer Token 和任务租约，避免过期 worker 修改任务；素材限制在 MEDIA_ROOT 内下载，截图和状态会回传服务器。中央调度器不会操作分配给控制节点的手机。

Agent 下载单文件默认最多 5 GiB、单任务总量最多 8 GiB、每任务最多 20 个素材；可分别通过 MAX_AGENT_ASSET_BYTES、MAX_AGENT_JOB_ASSET_BYTES、MAX_AGENT_ASSETS_PER_JOB 调整。下载先写入 .part 文件，完整校验后原子改名。Agent 每小时清理超过 AGENT_MEDIA_RETENTION_HOURS（默认 168 小时）的安全终态任务素材缓存；不清理 NEEDS_HUMAN 诊断、截图、日志、数据库或服务器源素材。

当 worker 主机能通过路由访问手机私网 IP 时，也支持 Android 无线调试。不要把 ADB 或 Appium 端口暴露到公网。除 localhost 开发模式外，Agent 必须使用 HTTPS 服务地址。按当前产品设置，Dashboard、文档、截图和普通任务 API 均不要求操作员登录；可通过 HTTPS 域名直接访问。跨站写请求会被拒绝，/agent/* 仍使用独立节点 Bearer Token，/health 保持公开供存活检查。回调采用持久化至少一次投递：精确匹配允许的主机名、固定解析到的公网 IP、不跟随重定向；接收方应使用幂等键去重。

app/main.py 负责 API 生命周期和调度线程。数据库记录是任务事实来源，内存 worker 池不是持久队列。服务异常重启后，中间 UI 状态会转为 NEEDS_HUMAN，因为界面动作可能已经完成但结果未写入数据库。到期任务从 PENDING 变为 READY；worker 通过条件更新认领任务。进程内设备锁和数据库租约可防止同一进程重复控制设备。单机最多有 7 个执行槽位，可同时控制 7 台手机。

适配器接口位于 app/publishers/base.py。Mock 只运行预检、表单准备和模拟的人工确认；截图会注明是模拟，SUCCESS 不代表平台真实发布。Android 适配器在平台专属流程完成验证前会安全停止。确认后，worker 会启动新会话并重新构建草稿，再尝试发布。YAML 选择器与业务代码分开加载。官方 API 适配器目前只是接口占位，后续只能基于平台允许使用的官方 API 实现。

SQLite 适用于单机 MVP。条件认领支持同机多个 worker，但进程内设备锁无法保护跨主机设备。迁移 PostgreSQL 后、允许多服务器执行前，还需要数据库级设备锁/租约和 schema 迁移工具。普通操作接口目前无登录验证，因此任何能访问后台的人都能读写任务并人工确认发布；此模式只适合受信任使用环境。HTTPS 可保护传输，但不能替代访问控制或生产审计。

状态流转概要

PENDING → READY → RUNNING → UPLOADING → FILLING_CONTENT → WAITING_CONFIRM → READY（操作员确认）→ RUNNING → PUBLISHING → SUCCESS | NEEDS_HUMAN

普通异常最多按 max_retries 次数进入 RETRY，耗尽后进入 FAILED。认证或风控标志进入 NEEDS_HUMAN。操作员可以通过 /retry 重试 FAILED 或 NEEDS_HUMAN 任务。API 返回规范状态名；RUNNING 是进入各细分阶段之前的通用认领状态。