12 KiB
12 KiB
EveryPublish 逻辑图全集（最小闭环版）
2026-08-20 · 汇总自 docs/multi-platform-publish-plan.md 与 docs/system-design.md，MVP 范围已标注。
图索引
| # | 图 | 回答的问题 | 来源 | PNG |
|---|---|---|---|---|
| 1 | 总体架构（双通道） | 系统由哪些部分组成、如何协作 | plan §3 | PNG |
| 2 | 控制面/数据面分离 | 为什么我方服务器不会被封 | plan §3.1 | PNG |
| 3 | MVP 部署拓扑（内网联调） | 一期怎么跑起来（Mac+Windows） | 新增 | PNG |
| 4 | IP 路由逻辑 | 账号与 IP 如何绑定 | plan §8 | PNG |
| 5 | 重试与降级状态机 | 失败/挑战/风控如何流转 | plan §21.2 | PNG |
| 6 | 全链路时序（含异常分支） | 用户→端→平台→用户完整路径 | plan §21.1 | PNG |
| 7 | 二次验证挑战兜底流程 | 扫码/验证码/APP确认怎么处理 | plan §21.3 | PNG |
| 8 | 登录链路优化时序 | 登录为何能从 10s 级压到 2s 级 | plan §22 | PNG |
| 9 | Agent 配对时序 | 客户端如何安全接入 | system-design §8.2 | PNG |
| 10 | 素材传输链路 | 文件怎么上传/下发/回传 | system-design §12 | PNG |
| 11 | 开发排期甘特 | 何时完成最小闭环 | 新增 | PNG |
图1 总体架构（双通道）
MVP 范围：一期只做通道B（Agent 自动化）+ 国内四平台（抖音/快手/小红书/B站）；通道A（官方API）与视频号为二期。
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 发出。
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 隔离。
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 级注入。
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 重试与降级状态机
失败按原因分流：网络→指数退避重试；登录态→挑战（人工扫码）；风控→账号冷却+人工队列。
stateDiagram-v2
[*] --> 队列中
队列中 --> 执行中: Agent认领
执行中 --> 已发布: 平台回执成功
执行中 --> 网络重试: 网络/超时错误
网络重试 --> 执行中: 退避1m/5m/15m/1h
网络重试 --> 失败终态: 超上限N次
执行中 --> 挑战中: 需扫码/验证码
挑战中 --> 执行中: 用户完成挑战
挑战中 --> 挂起: 挑战超时
挂起 --> 执行中: 用户稍后处理
执行中 --> 账号冷却: 风控拦截
账号冷却 --> 执行中: 冷却结束+人工确认
账号冷却 --> 失败终态: 人工放弃
失败终态 --> 队列中: 人工一键重发
已发布 --> [*]
失败终态 --> [*]
图6 全链路时序（含异常分支）
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 硬解为辅；超时挂起→人工队列→一键重发。
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 不传截图、短轮询检测、扫码与检测并行。
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 配对时序
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 抽象保证零改动）。
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，以新文档为准。
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 天。