docs: 项目文档、设计图、工具、协议模块、部署说明

2026-08-20 20:38:21 +08:00
commit bf25d8beac
46 changed files with 2965 additions and 0 deletions
@@ -0,0 +1,27 @@
+flowchart TB
+    subgraph WEB["① 控制端 Web 多租户SaaS"]
+        U["运营 / 审核 / 管理员"]
+        W["任务编排 · 素材库 · 账号台账 · 审计"]
+        U --- W
+    end
+    subgraph CORE["② 调度中心 服务器"]
+        Q["任务队列 Redis(asynq) · 状态机 · 排期器"]
+        API["通道A 官方API执行器 OAuth"]
+        AGW["通道B Agent网关 WSS注册/心跳/路由"]
+    end
+    subgraph AGENT["③ 执行端 Agent 客户侧安装"]
+        WS["WSS长连接 主动出网回连"]
+        VAULT["凭据保险库 cookie本地加密"]
+        ROUTER["代理路由器 一账号一IP"]
+        PA["浏览器执行器 go-rod CDP 独立档案"]
+        QR["扫码登录面板"]
+    end
+    WEB -->|"任务下发"| Q
+    Q -->|"通道A 官方API"| API
+    Q -->|"通道B 自动化"| AGW
+    AGW --> WS --> ROUTER --> PA
+    VAULT --- PA
+    QR --- VAULT
+    API --> INT["国际 X/IG/YouTube/TikTok"]
+    PA --> DOM["国内 抖音/快手/小红书/视频号/B站"]
+    PA --> INT
@@ -0,0 +1,14 @@
+flowchart TB
+    subgraph CP["控制面 我方服务器 无平台流量"]
+        WEB["控制台/API"] --- Q["队列/排期/状态机"]
+        Q --- GW["Agent网关 WSS"]
+    end
+    subgraph DP["数据面 客户Agent 全部平台流量"]
+        WS["WSS客户端"] --- EX["任务执行器"]
+        EX --- V["凭据保险库"]
+        EX --- PR["代理路由"]
+    end
+    CP -->|"任务元数据 WSS <1KB"| DP
+    DP -->|"结果/挑战 WSS"| CP
+    DP -->|"上传/发布 平台流量"| P["目标平台"]
+    CP -.->|"绝不触达"| P
@@ -0,0 +1,11 @@
+flowchart LR
+    subgraph M["Mac 开发机 内网测试环境"]
+        WEB["网页端 dev"] --> S["服务器 API + WSS网关"]
+    end
+    subgraph W["Windows 客户机"]
+        APP["客户端App Agent<br/>WinUI壳+Go执行核心"]
+    end
+    W -->|"WSS ws://局域网IP:端口"| S
+    S --> DB[("MySQL + Redis")]
+    S --> FS[("素材 服务器本地盘")]
+    APP -->|"直链下载素材 带签名token"| FS
@@ -0,0 +1,8 @@
+flowchart LR
+    ACC["账号台账"] --> REG{"账号归属地?"}
+    REG -->|国内平台| POOL1["国内住宅IP池<br/>芝麻/快代理/922S5等"]
+    REG -->|国外平台| POOL2["海外住宅IP池<br/>BrightData/IPRoyal等"]
+    POOL1 --> BIND["一账号绑定一IP<br/>长期固定不轮换"]
+    POOL2 --> BIND
+    BIND --> CTX["浏览器Context级注入<br/>非全局TUN 防串账号"]
+    CTX --> EXEC["执行发布"]
@@ -0,0 +1,17 @@
+stateDiagram-v2
+    [*] --> 队列中
+    队列中 --> 执行中: Agent认领
+    执行中 --> 已发布: 平台回执成功
+    执行中 --> 网络重试: 网络/超时错误
+    网络重试 --> 执行中: 退避1m/5m/15m/1h
+    网络重试 --> 失败终态: 超上限N次
+    执行中 --> 挑战中: 需扫码/验证码
+    挑战中 --> 执行中: 用户完成挑战
+    挑战中 --> 挂起: 挑战超时
+    挂起 --> 执行中: 用户稍后处理
+    执行中 --> 账号冷却: 风控拦截
+    账号冷却 --> 执行中: 冷却结束+人工确认
+    账号冷却 --> 失败终态: 人工放弃
+    失败终态 --> 队列中: 人工一键重发
+    已发布 --> [*]
+    失败终态 --> [*]
@@ -0,0 +1,38 @@
+sequenceDiagram
+    participant OP as 运营
+    participant S as 服务器
+    participant A as Agent
+    participant PL as 平台
+    participant IT as 账号负责人
+    Note over A,S: 单条WSS长连接复用(实测RTT 0.07ms)
+    OP->>S: 提交任务(素材/平台/排期)
+    S->>S: 校验→审核→入队→排期触发
+    S->>A: task.push(taskId,加密载荷)
+    A-->>S: ack(taskId) 幂等确认
+    A->>A: 选账号→注入代理→协议级登录态校验(不启浏览器)
+    alt 登录态正常
+        A->>PL: 冷启动浏览器→上传素材→提交发布
+        PL-->>A: 发布回执+截图
+        A->>S: task.result(success)
+        S-->>OP: 实时状态+链接
+    else 平台触发二次验证
+        PL-->>A: 挑战(扫码/短信/APP确认/滑块)
+        A->>S: challenge.push(类型,凭证)
+        S-->>IT: 控制台+企微提醒
+        IT->>S: 扫码或输入验证码
+        S->>A: challenge.resolve(结果)
+        A->>PL: 继续发布流程
+    else 网络类失败
+        A->>A: 指数退避 1m/5m/15m/1h
+        A->>PL: 自动重试上传
+    else 登录态失效
+        A->>S: challenge.push(qr)
+        S-->>IT: 推送扫码提醒
+        IT->>S: 扫码成功
+        S->>A: challenge.resolve
+        A->>PL: 恢复执行
+    else 风控拦截
+        A->>S: task.result(fail,原因)
+        S->>S: 账号冷却+人工队列
+        S-->>OP: 告警通知
+    end
@@ -0,0 +1,13 @@
+flowchart TB
+    TR["平台触发二次验证"] --> DET{"Agent检测挑战类型"}
+    DET -->|二维码登录| QR["取码→推控制台+企微<br/>码过期自动刷新"]
+    DET -->|APP确认| CF["推送手机确认提醒<br/>Agent轮询登录态"]
+    DET -->|短信/邮箱| SMS["控制台弹输入框<br/>用户输入→回传回填"]
+    DET -->|滑块/点选| CAP["默认截图推人工<br/>低风控平台本地尝试"]
+    QR --> OK{"完成?"}
+    CF --> OK
+    SMS --> OK
+    CAP --> OK
+    OK -->|是| CONT["Agent继续发布流程"]
+    OK -->|否/超时| PEND["任务挂起→人工队列<br/>一键重发/放弃"]
+    PEND --> CONT
@@ -0,0 +1,22 @@
+sequenceDiagram
+    participant U as 用户(手机)
+    participant C as 控制台/企微
+    participant S as 服务器
+    participant A as Agent
+    participant P as 平台
+    Note over A,P: 首选API直取(无浏览器, B站已验证)
+    A->>P: HTTP取码 0.1-0.5s 得token+图片URL
+    A->>S: challenge.push(token) 实测<50ms
+    S->>C: WS推码 并行推企微/托盘
+    C->>C: 本地重渲染二维码(非截图)
+    par 用户扫码 3-10s
+        U->>U: 手机扫码确认
+    and Agent短轮询检测
+        loop 300-500ms
+            A->>P: 轮询扫码状态(或网络钩子)
+        end
+    end
+    A->>P: API换取cookie 0.2-0.5s
+    A->>A: 存入凭据保险库
+    A->>S: challenge.resolve(已登录)
+    S-->>C: 状态变绿
@@ -0,0 +1,17 @@
+sequenceDiagram
+    participant U as 用户
+    participant W as 网页端
+    participant S as 服务器
+    participant A as App(Agent)
+    U->>W: 登录(密码+TOTP 2FA可选)
+    W->>S: POST /api/auth/login
+    S-->>W: JWT(15min) + refresh cookie
+    U->>W: 工作区→设备→添加设备
+    W->>S: POST /api/agents/pairing
+    S-->>W: 配对码(6位,5分钟有效)
+    U->>A: 输入配对码
+    A->>A: 生成Ed25519密钥对+deviceId
+    A->>S: WSS auth(deviceId,配对码,公钥,签名)
+    S->>S: 验证→注册公钥→签发agentToken(可吊销)
+    S-->>A: 绑定成功
+    A->>A: 私钥入本地保险库(DPAPI/SQLCipher)
@@ -0,0 +1,9 @@
+flowchart TB
+    OP["运营(网页端)"] -->|"① multipart直传(一期服务器本地盘)"| FS["素材存储 一期本地盘/二期OSS"]
+    OP -->|"② 元数据 API(sha256)"| S["服务器"]
+    S -->|"③ WSS task.push + 短时效下载URL"| A["Agent"]
+    A -->|"④ 直链下载(带签名token)"| FS
+    A -->|"⑤ 上传发布"| P["目标平台"]
+    P -->|"⑥ 回执+截图"| A
+    A -->|"⑦ WSS task.result(URL+状态)"| S
+    S -->|"⑧ WSS 实时状态推送"| OP
@@ -0,0 +1,25 @@
+gantt
+    title EveryPublish 交付排期（1人+AI · 3阶段2检查点）
+    dateFormat YYYY-MM-DD
+    axisFormat %m-%d
+    section 阶段一 网页端（D1-D7）
+    D1 工程化与骨架 :A1, 2026-08-20, 1d
+    D2 认证与工作区API :A2, after A1, 1d
+    D3 业务API(账号/素材/任务) :A3, after A2, 1d
+    D4 WSS网关+假执行器 :A4, after A3, 1d
+    D5 页面1(登录/仪表盘/成员/设置) :A5, after A4, 1d
+    D6 页面2(素材/账号/任务/日历) :A6, after A5, 1d
+    D7 页面3(审核/挑战/审计/admin) :A7, after A6, 1d
+    检查点1 网页端手动测试(暂停) :milestone, M1, after A7, 1d
+    section 阶段二 Windows客户端（D8-D11）
+    D8 agent-core(Go) :B1, after M1, 1d
+    D9 WinUI3壳+托盘+watchdog :B2, after B1, 1d
+    D10 B站真实发布(无浏览器) :B3, after B2, 1d
+    D11 抖音/快手/小红书(CDP) :B4, after B3, 1d
+    检查点2 交付用户测试(暂停) :milestone, M2, after B4, 1d
+    section 阶段三 联调与交付（D12-D15）
+    D12 联调+异常注入 :C1, after M2, 1d
+    D13 打包+内部试用 :C2, after C1, 1d
+    D14-15 缓冲(平台逆向) :C3, after C2, 2d
+    section 二期（预留）
+    视频号+官方API通道 :F1, after C3, 21d
@@ -0,0 +1 @@
+{"args":["--no-sandbox","--disable-gpu"]}