GoWind CMS 拆解社交分发引擎——10 平台适配器、状态闸门与自愈定时任务本文回答一个问题“把这篇文章一键发到 10 个平台、明早 9 点准时发、失败自动重试、发布后还能回拉互动数据”——这句话拆成工程问题一共有几层GoWind CMS 的社交分发功能连接 10 个平台Bluesky / Mastodon / DEV.to / Telegram / WordPress / 微信公众号 / Nostr / 微博 / LinkedIn / 博客园支持内容一键分发、定时发布、改期重排、失败重试、互动统计回拉并把这些能力以 MCP 工具的形式暴露给 AI 代理。这篇文章拆它的五层平台适配器、凭据生命周期、发布状态机、定时自愈、统计回拉——每一层都有可以直接迁移的工程决策。一、适配器架构三个方法、一个接口、一种错误哲学所有平台适配器实现同一个接口pkg/social/provider.gotypeProviderinterface{ValidateCredentials(ctx context.Context,creds Credentials)errorPublish(ctx context.Context,account Account,content Content)(*PublishResult,error)FetchStats(ctx context.Context,account Account,externalIDstring)(*Stats,error)}typeCredentialsmap[string]string接口面刻意收窄到三方法配套一个语义化哨兵错误集合var(ErrInvalidCredentialserrors.New(...)ErrRateLimitederrors.New(...)ErrContentTooLongerrors.New(...)ErrNotFounderrors.New(...)ErrStatsUnsupportederrors.New(...)// 统计回拉链路据此静默跳过而非报错)ErrStatsUnsupported的注释点明了这套错误哲学适配器用类型化错误表达能力差异上层据此分流——Telegram 没有互动统计 API回拉 worker 遇到这个哨兵就推进节流时间戳、静默跳过而不是每周期报一次错。错误即协议。适配器通过注册表解耦各平台子包在init()里Register(PLATFORM_BLUESKY, p)自注册core 侧按 proto 枚举名取用——新增平台 新增一个子包主链路零改动。安全模型有一条清晰的边界注释原文「凭据只在 core service 层解密后以 Credentials 传入适配器不接触存储与 pkg/ai 的’密钥运行时注入’同款安全模型」。适配器是纯函数式的平台客户端密钥从哪里来、怎么加密它一概不知。二、MetaWeblog一个适配器吃掉一类协议10 个平台不是 10 份等量代码。博客园、Typecho 及一切声明支持 MetaWeblog API 的博客系统共用一个通用 XML-RPC 适配器pkg/social/metaweblog包头注释就是它的设计宣言覆盖对象博客园、Typecho 及一切声明支持 MetaWeblog API 的博客系统——RPC 端点由用户凭据给出本适配器不绑定具体站点。整个适配器只用三个 XML-RPC 方法blogger.getUsersBlogs、metaWeblog.newPostblog_id留空时自动调getUsersBlogs取第一个博客。两个工程细节ctx 透传缝底层 XML-RPC 库不接受 contextctxTransport自定义 Transport 把调用级 ctx 塞进去——超时与取消不因库的老接口而失效错误归类classifyXMLError按中英文认证关键词“密码”/“auth”/“403”……把各家实现不一的 faultString 归类为ErrInvalidCredentials——把混乱归一在适配器层上层只认哨兵错误。其他平台的对接要点各有味道Bluesky 用 App Password 现签现用 JWT不持久化会话300 rune 长度预检Nostr 是账户即密钥——NIP-01 私钥直接对 kind1 事件做 Schnorr 签名广播任一 relay 接受即成功微信公众号走草稿箱→freepublish 两段式thumb_media_id必填、受 IP 白名单约束未认证号 freepublish 报权限时保留草稿降级。收件箱回拉则是可选能力接口InboxFetcherAsInboxFetcher类型断言——能力是可选接口而非全家桶未实现的平台周期任务静默跳过。三、凭据生命周期从保存即验证到增量合并不丢密钥凭据的安全链路五步每步都有明确的威胁对位保存即验证CreateSocialAccount先调provider.ValidateCredentials通过才加密落库——坏凭据在入口就挡住不等发布时才炸AES-256-GCM 落库enc:前缀 随机 nonce密钥由ENCRYPTION_KEY经 SHA-256 派生core/admin 双服务同值。这里有一个真实的修复故事CHANGELOG 1.1.0 原话「AI 模型提供商 API Key 此前明文落库全局存储加密器pkg/crypto从未初始化现已在服务启动接线未配置时降级明文并告警」——加密代码写了、初始化漏了是这类安全设施最典型的失效方式wiring.go里那段InitGlobalEncryptor 未配置告警就是为它补的读取恒空List/Get/Create/Update 四个出口统一item.Credentials nil只回CredentialHint如app_password ***xxxx末 4 位脱敏——管理页永远拿不到密文增量合并编辑账号时前端动态表单只回传用户填写的键core 取旧密文解密、if v ! { merged[k] v }合并、重新验证加密——部分更新不会把没填的密钥清掉代改密文边角场景——用户只想改 Bluesky 的 handle 不想重输密码handle 恰好是凭据的一部分密文里core 代为解密改写这一键再加密。「凭据密文无法在 BFF 侧改写必须由 core 完成」——谁持有密钥谁负责密文变换边界不含糊。四、发布是状态机不是一次 HTTP 调用一键发布的直译是provider.Publish(content)——这个实现把它建成了状态机DRAFT → SCHEDULED → PUBLISHING → PUBLISHED / FAILED(可重试)。两个关键决策状态流转收敛在仓储层social_distribution_repo.go结构体注释「状态流转由本仓储的专用方法收敛service/worker 不直接散写 status避免竞态下状态机被绕过」——通用的Update根本不开放 status 字段写入改状态只有走专用方法一条路。进入 PUBLISHING 走条件更新抢占——全文的高光代码// TryLockPublishing:n0 表示抢到发布权;n0 表示并发点击/重复发布n,err:r.entClient.Client().SocialDistribution.Update().Where(socialdistribution.IDEQ(id),socialdistribution.StatusIn(DRAFT,SCHEDULED,FAILED),// 只有这些状态可进发布).SetStatus(PUBLISHING).Save(ctx)returnn0,nil用户双击发布按钮、worker 与手动触发并发、MCP 工具与页面同时下发——所有路径都汇到这条条件 UPDATE 上恰一方进入 PUBLISHING。这与运维平台的PENDING-only 条件回填是同一种原语的镜像用法那边防重复终态化这边防重复起始化。失败重试的语义也收在仓储MarkFailed返回累计publish_attempts原子 1worker 据此判定 1MaxRetry4 次穷尽才算最终失败——计数在库不在内存跨进程重启依然准确。看板拖拽流转MoveStatus同样走StatusIn(froms...)条件更新拖晚了并发变化返回 false 让前端刷新。五、定时发布的两层防线定时发布用 asynq DELAY 实现publish_time在未来 → 按时刻入队ProcessAt为空或已过 → 零延迟立即执行MaxRetry(3)。这一层有三个细节调度器未注入时返回错误——与重索引类 best-effort 任务刻意区分注释“否则 SCHEDULED 记录会被无声搁置”。同样是入队有的任务失败可以静默降级有的必须硬失败判据是失败是否造成用户可见的承诺落空改期自动重新排队 旧任务自弃改期落库后重新入队新时刻的 DELAY 任务而旧的已排期任务到点时发现排期已推迟超过 2 分钟窗口socialStaleTaskSkipWindow则自行丢弃——新旧任务不需要互相互杀靠数据库里的当前状态裁决永久性/暂时性失败分叉worker 里ErrContentTooLong这类重试必然还错的返回nil不烧重试额度网络类错误返回err交给 asynq 退避重试。错误分类决定重试策略哨兵错误体系在这里兑现价值。第二层防线是兜底扫描pkg/task/publish_sweep.goDELAY 任务在 Redis 数据丢失、服务崩溃窗口内可能静默丢失两个每分钟一轮的 sweep 任务扫描已到期但仍是 SCHEDULED的记录重新入队。这个文件的头注释里藏着一个精彩的踩坑故事值得整段引用任务类型命名注意asynq ServeMux 在精确匹配失败后按【前缀】兜底路由strings.HasPrefix类型名不得是其他已注册类型的前缀——曾用名 “post.publish.sweep” 会命中 “post.publish” 的 handlerpayload 解码失败被吞。现改为互不为前缀的 “post.scheduled.sweep” / “social.distribution.sweep”。“payload 解码失败被吞”——这个 bug 的恶劣在于三层叠加前缀路由命中错误的 handler、解码失败、错误被吞。三个独立的小缺陷叠出一个定时任务偶尔静默不执行的幽灵故障。sweep 的幂等性也写明了“重复入队无害worker 会跳过已发布/改期记录”——又回到状态闸门重试的底气始终是那个条件更新。通知语义对齐落库即达成功即时站内信通知操作者失败只在重试穷尽后通知一次——不打扰但绝不让失败静默。六、统计回拉与平台 API 共处的克制发布出去只是前半程互动数据赞/评/转要回拉。这条链路的三个常量就是全部的克制哲学socialStatsSyncWindow30天// 只回拉近 30 天发布的内容socialStatsSyncThrottle2小时// 单条记录最小回拉间隔socialStatsSyncBatchLimit50// 单批上限,防长事务/平台限流候选查询按PUBLISHED external_id 非空 30 天内 (从未回拉 或 节流已过)筛选Limit 50。遇ErrStatsUnsupported走TouchStatsSyncedAt仅推进节流时间戳——用节流替代报错不支持统计的平台不会产生周期性告警噪音。回拉成功追加快照到social_stats_history只增不改的表批次尾部顺手按 90 天保留裁剪限批 1000 防长事务——趋势图的数据积累与容量治理在同一个写路径里完成不需要独立的清理任务。七、MCP 服务器把分发能力暴露给 AI 代理分发的第五层出口是 MCPModel Context Protocol服务器mcp_server.go290 行基于mark3labs/mcp-go StreamableHTTP 传输把 CMS 能力包装成四个工具——list_recent_posts/get_social_summary/list_social_distributions/publish_distribution。鉴权模型有两处讲究MCP_TOKEN只走环境变量缺失时拒绝启动 MCP 服务器不存在无鉴权的降级模式tools/list的元数据名称与描述对未鉴权调用方可见但每个工具调用必须带 Token——工具目录是发现协议的一部分能力执行才是要保护的面。最有分量的是publish_distribution这个写工具的实现路径它内部走PublishSocialDistribution→TryLockPublishing——与页面按钮完全同一条安全路径。AI 代理触发的发布与人类触发的发布共享状态闸门、重试语义与审计不存在AI 专用旁路。给 AI 开放写能力时正确的姿势不是为它新写一套而是确认它只能走到人类已有的那条路上。八、结语拆完五层这个引擎的架构观可以收敛成三句话平台异构性收口在适配器层——哨兵错误即协议能力差异InboxFetcher、ErrStatsUnsupported用可选接口和类型化错误表达上层永远只见统一语义发布是状态机——状态流转收敛在仓储、进入 PUBLISHING 走条件更新、重试计数在库不在内存所有并发问题在状态闸门前终止定时承诺用两层防线兑现——asynq DELAY 管正常路径每分钟 sweep 管灾难路径幂等 worker 让重复入队无害而前缀路由的事故故事提醒我们任务系统的路由语义要像对待 SQL 注入一样认真读文档。仓库分发引擎在backend/pkg/social与backend/app/core/service/internal/service/social_service.goGitHubgithub.com/tx7do/go-wind-cmsGiteegitee.com/tx7do/go-wind-cms