docs: 项目文档、设计图、工具、协议模块、部署说明
This commit is contained in:
Qiufeng
@@ -0,0 +1,299 @@
|
||||
# EveryPublish 逻辑图全集（最小闭环版）
|
||||
|
||||
> 2026-08-20 · 汇总自 docs/multi-platform-publish-plan.md 与 docs/system-design.md，MVP 范围已标注。
|
||||
|
||||
## 图索引
|
||||
|
||||
| # | 图 | 回答的问题 | 来源 | PNG |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 总体架构（双通道） | 系统由哪些部分组成、如何协作 | plan §3 | [PNG](../diagrams/png/01-总体架构.png) |
|
||||
| 2 | 控制面/数据面分离 | 为什么我方服务器不会被封 | plan §3.1 | [PNG](../diagrams/png/02-控制面-数据面分离.png) |
|
||||
| 3 | MVP 部署拓扑（内网联调） | 一期怎么跑起来（Mac+Windows） | 新增 | [PNG](../diagrams/png/03-MVP-部署拓扑.png) |
|
||||
| 4 | IP 路由逻辑 | 账号与 IP 如何绑定 | plan §8 | [PNG](../diagrams/png/04-IP-路由逻辑.png) |
|
||||
| 5 | 重试与降级状态机 | 失败/挑战/风控如何流转 | plan §21.2 | [PNG](../diagrams/png/05-重试与降级状态机.png) |
|
||||
| 6 | 全链路时序（含异常分支） | 用户→端→平台→用户完整路径 | plan §21.1 | [PNG](../diagrams/png/06-全链路时序.png) |
|
||||
| 7 | 二次验证挑战兜底流程 | 扫码/验证码/APP确认怎么处理 | plan §21.3 | [PNG](../diagrams/png/07-二次验证挑战兜底流程.png) |
|
||||
| 8 | 登录链路优化时序 | 登录为何能从 10s 级压到 2s 级 | plan §22 | [PNG](../diagrams/png/08-登录链路优化时序.png) |
|
||||
| 9 | Agent 配对时序 | 客户端如何安全接入 | system-design §8.2 | [PNG](../diagrams/png/09-Agent-配对时序.png) |
|
||||
| 10 | 素材传输链路 | 文件怎么上传/下发/回传 | system-design §12 | [PNG](../diagrams/png/10-素材传输链路.png) |
|
||||
| 11 | 开发排期甘特 | 何时完成最小闭环 | 新增 | [PNG](../diagrams/png/11-开发排期甘特.png) |
|
||||
|
||||
## 图1 总体架构（双通道）
|
||||
|
||||
**MVP 范围**：一期只做通道B（Agent 自动化）+ 国内四平台（抖音/快手/小红书/B站）；通道A（官方API）与视频号为二期。
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
## 图2 控制面/数据面分离
|
||||
|
||||
我方服务器只流转任务元数据（<1KB），绝不触达平台；全部平台流量从客户 Agent 发出。
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
## 图3 MVP 部署拓扑（内网联调）
|
||||
|
||||
Mac 跑网页端+服务器，Windows 装客户端，同局域网联调。注意服务器绑定 0.0.0.0、客户端用局域网 IP、防火墙放行、关 AP 隔离。
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
## 图4 IP 路由逻辑
|
||||
|
||||
一账号一固定 IP，国内账号=国内住宅 IP，国外账号=国外住宅 IP，浏览器 Context 级注入。
|
||||
|
||||
```mermaid
|
||||
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["执行发布"]
|
||||
```
|
||||
|
||||
## 图5 重试与降级状态机
|
||||
|
||||
失败按原因分流：网络→指数退避重试；登录态→挑战（人工扫码）；风控→账号冷却+人工队列。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 队列中
|
||||
队列中 --> 执行中: Agent认领
|
||||
执行中 --> 已发布: 平台回执成功
|
||||
执行中 --> 网络重试: 网络/超时错误
|
||||
网络重试 --> 执行中: 退避1m/5m/15m/1h
|
||||
网络重试 --> 失败终态: 超上限N次
|
||||
执行中 --> 挑战中: 需扫码/验证码
|
||||
挑战中 --> 执行中: 用户完成挑战
|
||||
挑战中 --> 挂起: 挑战超时
|
||||
挂起 --> 执行中: 用户稍后处理
|
||||
执行中 --> 账号冷却: 风控拦截
|
||||
账号冷却 --> 执行中: 冷却结束+人工确认
|
||||
账号冷却 --> 失败终态: 人工放弃
|
||||
失败终态 --> 队列中: 人工一键重发
|
||||
已发布 --> [*]
|
||||
失败终态 --> [*]
|
||||
```
|
||||
|
||||
## 图6 全链路时序（含异常分支）
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
## 图7 二次验证挑战兜底流程
|
||||
|
||||
验证码类挑战人工兜底为主、Agent 硬解为辅；超时挂起→人工队列→一键重发。
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
## 图8 登录链路优化时序
|
||||
|
||||
API 取码免浏览器、只传 token 不传截图、短轮询检测、扫码与检测并行。
|
||||
|
||||
```mermaid
|
||||
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: 状态变绿
|
||||
```
|
||||
|
||||
## 图9 Agent 配对时序
|
||||
|
||||
```mermaid
|
||||
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)
|
||||
```
|
||||
|
||||
## 图10 素材传输链路（一期本地盘 / 二期OSS）
|
||||
|
||||
大文件绝不走 WSS；一期存服务器本地盘、直链带签名 token；二期切 OSS 预签名（StorageDriver 抽象保证零改动）。
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
## 图11 开发排期甘特（2 人，至最小闭环）
|
||||
|
||||
> 2026-08-20 更新：AI 加速版日级排期见 docs/dev-schedule.md，以新文档为准。
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title EveryPublish 最小闭环排期(2人)
|
||||
dateFormat YYYY-MM-DD
|
||||
axisFormat %m-%d
|
||||
section 奠基
|
||||
协议包+工程骨架 :M0, 2026-08-24, 7d
|
||||
section 网页端
|
||||
服务器最小闭环 :M1, 2026-08-31, 14d
|
||||
网页端全部功能 :M2, 2026-08-31, 28d
|
||||
section 客户端Windows
|
||||
Agent框架+WinUI壳 :M3, 2026-08-31, 21d
|
||||
真实平台接入4平台 :M4, 2026-09-21, 21d
|
||||
section 联调与收尾
|
||||
内网联调+异常加固 :M5, 2026-10-12, 14d
|
||||
打包+内部试用 :M6, 2026-10-26, 7d
|
||||
section 二期
|
||||
视频号+官方API通道 :M7, after M6, 21d
|
||||
```
|
||||
|
||||
## 最小闭环验收清单
|
||||
|
||||
| 里程碑 | 验收标准 | 周次 |
|
||||
|---|---|---|
|
||||
| M0 协议+骨架 | 协议包单测通过，两端共享类型 | W1 |
|
||||
| M1 服务器最小闭环 | 假执行器：任务→下发→执行→回传→显示全通 | W2-3 |
|
||||
| M2 网页端全部功能 | 账号/素材/任务/排期/审核/挑战/审计/通知全页面可用 | W2-6 |
|
||||
| M3 Windows 客户端框架 | 安装→配对→接假任务→回传结果 | W2-4 |
|
||||
| M4 真实平台接入 | 抖音/快手/小红书/B站真实发布成功+截图回执 | W5-7 |
|
||||
| M5 内网联调+加固 | 断线/重试/挑战/延迟<300ms 验收全过 | W8-9 |
|
||||
| M6 打包+试用 | Windows 安装包+自动更新+内部试用 | W10 |
|
||||
|
||||
**人力**：2 人（网页/服务端 1 + 客户端 1）10 周闭环；单人 16-18 周。闭环后持续成本：平台适配每周 0.5-1 天。
|
||||
Reference in New Issue
Block a user