Owncast 服务器联邦Federation第四阶段实现计划基于 ActivityPub Leave 活动的流结束状态同步【免费下载链接】owncastTake control over your live stream video by running it yourself. Streaming chat out of the box.项目地址: https://gitcode.com/GitHub_Trending/ow/owncast导读本文深度解析 Owncast 服务器联邦Server Federation第四阶段的核心实现计划通过 ActivityPubLeave 活动Activity在直播流结束时向联邦服务器实时广播离线状态使目录型服务器Directory无需轮询即可同步对方已下播的事实。文章既完整还原实现计划文档中的活动结构、集成点、测试策略与实施步骤又结合当前仓库源码逐一印证GoOffline触发链、outbox/inbox 基础设施、Owncast 自定义元数据的收发解析以及联邦服务器状态库的底层更新逻辑。读完本文你将掌握在 Owncast 上实现流结束状态广播的完整技术方案理解 Leave 活动与既有 OfferGoLive活动如何对称工作并能定位到每一处关键代码实现。说明该实现计划文档描述的功能在 services/activitypub/outbox/ping.go 与 services/activitypub/inbox/leave.go 中已有对应落地实现本文在复述计划的同时将以源码为据展开纵深讲解。一、方案背景为什么流结束需要主动广播在服务器联邦场景中一台 Owncast 服务器下称本地服务器开播时会通过 ActivityPubOffer 活动对应SendStreamPing向关注它的服务器广播直播开始及当前流元数据标题、描述、标签、缩略图等。但在该实现计划出现之前下播这个状态缺乏对称的主动通知远端服务器只能依赖超时探测staleness sweep或轮询来发现对方已经离线导致目录中的直播列表长时间残留已结束的条目。第四阶段的方案就是引入 ActivityPub 标准的Leave 活动发送侧本地流从在线转为离线时构造一条 Leave 活动携带服务器标识与流元数据投递到所有关注该服务器的目录型联邦服务器接收侧收到 Leave 活动后将对应联邦服务器的状态立即标记为 offline并更新缓存的元数据。该方案完全复用既有 ActivityPub 基础设施outbox 发送、inbox 接收、crypto 签名、persistence 队列管理无需引入任何新的外部依赖与既有的 GoLive 逻辑形成平行对称结构。二、ActivityPub Leave 活动结构详解2.1 计划文档定义的活动格式实现计划给出的 Leave 活动 JSON 骨架如下{ context: https://www.w3.org/ns/activitystreams, type: Leave, id: https://example.owncast.tv/activities/leave-123, actor: https://example.owncast.tv/federation/user/, object: https://example.owncast.tv, published: 2024-01-01T00:00:00Z, logo: https://example.owncast.tv/logo.png, name: Example Server, streamTitle: My Stream, streamDescription: Stream description, tags: [gaming, tech] }结构要点字段含义type活动类型固定为Leaveid活动唯一标识通常指向本地服务器资源actor发送方本地 Owncast 服务器的 actor IRI即federation/user/指向的联邦账户object活动的对象这里取本地服务器的根 URLhttps://example.owncast.tvpublished发布时间RFC3339 时间戳logo/name/streamTitle/streamDescription/tagsOwncast 自定义元数据字段2.2 自定义元数据字段的命名空间源码印证计划文档提到Metadata fields are set at the root level usingSetOwncastMetadataand parsed usingParseOwncastMetadata。这些字段的真实 JSON-LD 键在 config/constants.go 中统一定义为https://owncast.online/ns#命名空间下的属性APOwncastNamespaceStreamStatus https://owncast.online/ns#streamStatus APOwncastNamespaceStreamTitle https://owncast.online/ns#streamTitle APOwncastNamespaceServerName https://owncast.online/ns#serverName APOwncastNamespaceStreamDescription https://owncast.online/ns#streamDescription APOwncastNamespaceLogoURL https://owncast.online/ns#logoUrl APOwncastNamespaceThumbnailURL https://owncast.online/ns#thumbnailUrl APOwncastNamespaceStreamTags https://owncast.online/ns#streamTags流状态取值同样集中定义APStreamStatusLive live、APStreamStatusOffline offline。因此实际在线路上传输的 Leave 活动其自定义字段是以上述完整 IRI 为键展开的接收方正是通过ParseOwncastMetadata按这些键反向解析。需要注意真实的 Activity 并不会把元数据字段简写为logo、name这种短名计划文档中的示例是为了可读性而简化的示意。2.3 元数据写入与解析的源码实现写入侧services/activitypub/apmodels/owncast_metadata.go 的SetOwncastMetadata(unknownProps, repo, isStreamConnected)始终写入serverName与streamDescription来自服务器配置的GetServerName/GetServerSummary根据isStreamConnected写入streamStatus为live或offline仅当处于直播状态时附带thumbnailUrl{serverURL}/thumbnail.jpg因为离线时缩略图不存在streamTitle、logoUrl、streamTags按配置是否存在条件写入。解析侧的ParseOwncastMetadata(unknownProps)从活动未声明属性unknown properties中提取StreamStatus、StreamTitle、StreamDescription、ServerName、LogoURL、ThumbnailURL、Tags并通过ns#directory标记判断发送方是否为目录型服务器。这套对称的写/读机制保证 Leave 与 Offer 携带同一套元数据语义。三、发送侧GoOffline 与 Leave 活动出站3.1 触发点与流生命周期集成实现计划要求在 GoLive 所在位置附近创建并行的 GoOffline 函数并挂钩现有流离线事件。源码中的真实触发链位于 services/stream/stream.go开播时调用s.activitypub.SendStreamPing()对应计划中的 GoLive 语义发送 Offer 活动下播时调用s.activitypub.SendStreamGoingOffline()对应计划中的 GoOffline 语义发送 Leave 活动。两者都受GetFederationEnabled()开关控制——关闭联邦功能时不会发送任何流状态广播。3.2 共享的出站构建器计划要求Create Leave activity builder function并Use SetOwncastMetadata to add metadata。源码在 services/activitypub/outbox/ping.go 中用一个共享私有函数sendStreamStatusToFollowers(activity, isLive, logLabel)统一处理 Offer 与 Leave生成活动idshortid并指向本地资源 IRIactor 设为本地联邦账户 IRI将object设置为服务器根 URL{serverURL}语义即离开/加入直播目录调用apmodels.SetOwncastMetadata(activity.GetUnknownProperties(), configRepository, isLive)注入元数据构造 to/cc 寻址沿用getAddressingToFollowers公开服务器时 topublic、ccfollowers序列化后经SendToDirectoryFollowers(payload, stream-status)仅投递给目录型关注者避免向普通粉丝发送无意义的目录流量调用Add(activity, id, false)将活动写入 outbox 持久化记录。两个公开入口是对称的一行封装func (s *Service) SendStreamPing() error { // 开播Offer if !s.configRepository.GetFederationEnabled() { return nil } return s.sendStreamStatusToFollowers(streams.NewActivityStreamsOffer(), true, stream ping Offer activity) } func (s *Service) SendStreamGoingOffline() error { // 下播Leave if !s.configRepository.GetFederationEnabled() { return nil } return s.sendStreamStatusToFollowers(streams.NewActivityStreamsLeave(), false, stream-offline Leave activity) }3.3 投递与重试机制投递链路复用 services/activitypub/outbox/outbox.go 的sendToInboxes对每个收件箱校验https协议与主机合法性拒绝内部地址防 SSRF构造workerpool.Delivery{Inbox, Payload, ActorIRI, ActivityType, CoalesceKey}后调用EnqueueBatch交给持久化投递队列services/activitypub/workerpool/outbound.go。签名在每次投递前即时完成crypto 组件失败活动由投递队列负责重试符合计划中Retry failed activity deliveries的性能与容错要求。3.4 周期性保活可选增强开播后services/activitypub/outbox/ticker.go 会以5 分钟间隔StreamPingInterval 5 * time.Minute周期性地重发 Offer 流状态活动保证目录端列表新鲜度下播时StopStreamPingTicker停止该周期任务并由SendStreamGoingOffline发送最终离线通知。这正对应实现计划Activity sending should be async/non-blocking以及batch updates的工程考量。四、接收侧Leave 活动入站处理4.1 入站路由与校验计划要求在activitypub/inbox/worker.go或类似 inbox handler 中接收 Leave 活动。当前仓库的入站路由位于 services/activitypub/inbox/service.go其工作模式为经 HTTP 接收到的活动InboxRequest进入AddToQueue由大小为runtime.GOMAXPROCS(0)的 worker 池并发消费每个 worker 在handle(job.request)中对活动做签名校验与结构验证复用 ActivityPub crypto 组件再按活动类型分发到对应 handler每个 handler 外层有 panic 恢复保护保证单个异常活动不会拖垮整个 worker。4.2 Leave 专用处理逻辑源码级Leave 的专用 handler 是 services/activitypub/inbox/leave.go 的handleLeaveInboxRequest完整复现了计划中的四步取 actor从活动GetActivityStreamsActor()获取发送方并通过s.resolver.GetResolvedActorFromActorProperty解析出对方 actor IRI解析元数据apmodels.ParseOwncastMetadata(activity.GetUnknownProperties())提取服务器名、流标题、标签等置为离线metadata.StreamStatus offline更新状态库调用updateFederatedServerStatus(actorIRI, metadata)持久化离线状态。4.3 状态库更新与防御性检查updateFederatedServerStatusleave.go体现了与 Offer 处理完全对称的防御逻辑IRI 归一化serverURLFromActorIRI将完整 actor IRI如https://example.owncast.tv/federation/user/归约为基址scheme://host与联邦服务器表federated_servers的主键对齐与 services/activitypub/inbox/offer.go 同源白名单过滤shouldProcessOfferFromServer仅处理我们正在积极关注的服务器——忽略Pending、rejected、none状态的来源防止未建立 Follow 关系的服务器写入状态落库repo.UpdateServerStatus(serverURL, false, nil)将IsOnline置为false。离线状态不带流字段流已结束无标题/缩略图可存与 Offer 路径携带FederatedStreamUpdate的行为形成注释中明确说明的对称关系。底层UpdateServerStatus实现在 persistence/federatedserversrepository/sqlfederatedserversrepository.go对应仓库单测 federatedserversrepository_test.go 的TestUpdateServerStatusOffline专门覆盖离线更新路径并验证对不存在服务器的无副作用行为TestUpdateServerStatus_NonExistentServer。4.4 元数据模型更新所用到的流元数据结构为 models/federatedserver.go 的FederatedStreamUpdatetype FederatedStreamUpdate struct { Title *string json:title,omitempty Description *string json:description,omitempty Tags []string json:tags,omitempty ThumbnailURL *string json:thumbnailUrl,omitempty }对应数据库模型FederatedServer含IsOnline、StreamTitle、LastSeenOnline、LastStatusUpdate、FollowStatus等字段由FromDatabaseModel转换供 UI 与目录列表消费。五、安全性元数据消毒与元数据上限实现计划在Security一节要求Sanitize metadata fields。由于远端元数据是攻击者可控输入Offer 路径在 offer.go 中定义了明确的长度/数量上限Leave 路径虽不存储流字段但同样共享这套边界约束项目上限值常量流标题300 字符maxStreamTitleLen流描述2000 字符maxStreamDescriptionLen服务器名200 字符maxServerNameLen元数据 URL缩略图/logo2048 字符maxMetadataURLLen标签数量20 个maxTags单个标签长度100 字符maxTagLentruncateMetadata按 runeUTF-8 安全截断clampTags同时限制标签数量与单标签长度防止恶意远端服务器撑爆数据库或破坏 UI。此外入站活动在路由前已完成签名验证与 actor 授权校验符合计划中Verify activity signatures / Validate actor authorization的安全要求。六、测试策略与验收标准6.1 计划文档的测试分层单元测试Leave 活动构造结构正确性、Leave 活动处理状态更新逻辑、元数据解析ParseOwncastMetadata对自定义属性的提取集成测试test/automated/api/Leave 活动端点接收、状态更新传播、元数据持久化端到端测试部署两个 Owncast 实例并互相联邦在一台启动/停止直播验证另一台收到 Leave 活动且状态正确更新。6.2 仓库中的既有验证证据入站 Offer/Leave 的元数据解析在 services/activitypub/apmodels/owncast_metadata_test.go 有配套测试联邦服务器状态库的离线更新在 federatedserversrepository_test.go 有TestUpdateServerStatusOffline等用例覆盖outbox 流状态构建Offer/Leave 共享代码路径的序列化行为可通过 services/activitypub/outbox/outbox_test.go 验证。6.3 验收清单Success Criteria 落地映射计划验收项对应实现证据下播时发送 Leave 活动services/stream/stream.go调用SendStreamGoingOffline()Leave 活动正确接收处理services/activitypub/inbox/leave.go的handleLeaveInboxRequest联邦服务器状态更新为 offlineupdateFederatedServerStatus→UpdateServerStatus(serverURL, false, nil)元数据随活动更新SetOwncastMetadata/ParseOwncastMetadata无性能回退异步 worker 池 持久化投递队列 stream-status合并键错误处理队列重试、worker panic 恢复、详尽log.Debug/Error日志七、实施路线与依赖清单7.1 阶段划分计划文档口径Phase 1 出站2-3 天定位 GoLive 调用点 → 创建并行 GoOffline 函数 → 构建 Leave 活动 → 注入 Owncast 元数据 → 接入 outbox 队列 → 测试活动创建与排队Phase 2 入站2-3 天为 inbox worker 增加 Leave handler → 用ParseOwncastMetadata提取元数据 → 更新联邦服务器状态 → 持久化元数据变更 → 测试处理链路Phase 3 集成与测试2 天全链路集成测试、错误处理与边界情况、多联邦服务器性能测试、文档更新Phase 4 UI可选1 天UI 实时状态更新、元数据展示、离线服务器视觉标识。7.2 涉及/复用的既有组件组件作用services/activitypub/outbox/出站活动构建与投递services/activitypub/inbox/入站活动路由与处理services/activitypub/apmodels/Owncast 元数据写入/解析、actor 与活动构建services/activitypub/crypto/活动签名与验签persistence/federatedserversrepository/联邦服务器状态持久化models/federatedserver.go服务器与流元数据模型外部依赖无新增全部复用既有 ActivityPub 库与 Owncast 基础设施这与计划文档Uses existing ActivityPub libraries的结论一致。7.3 风险与缓解对照计划列出的风险源码中的缓解手段活动投递失败workerpool 持久化投递队列 重试CoalesceKey合并重复投递元数据体积失控truncateMetadata/clampTags强制截断见第五节上限表状态更新竞态pingTickerMu保护 ticker 生命周期状态库更新经由单一 repository 方法串行落库与不支持 Leave 的服务器兼容仅向目录型关注者发送接收方忽略未知属性对未关注来源静默丢弃八、后续演进方向实现计划展望了后续增强点结合当前仓库可以这样理解其落点支持更多活动类型Join、Update目前开播/下播对应 Offer/Leave 一对未来可用Update在直播中推送标题/标签变更复用sendStreamStatusToFollowers的通用构建路径批量状态更新SendToDirectoryFollowers已支持按coalesceKey合并投递可进一步按时间窗聚合多条状态变更WebSocket 实时通知联邦服务器状态变化可接入 services/dispatcher/dispatcher.go 的既有分发通道向管理端 UI 推送实时状态历史状态追踪federated_servers表已含LastSeenOnline、LastStatusUpdate时间戳字段为后续基于时间线的状态历史提供了数据基础。九、总结Server Federation Phase 4 通过 ActivityPub Leave 活动为 Owncast 的联邦体系补齐了下播即广播的对称通知能力使目录型服务器能够立即将条目移出直播列表而无需等待超时扫描。该计划的核心价值在于零新依赖完全复用 outbox / inbox / crypto / persistence / workerpool 既有设施对称设计SendStreamPingOffer/live与SendStreamGoingOfflineLeave/offline共享同一构建器接收侧handleOfferInboxRequest与handleLeaveInboxRequest对称实现防御性工程签名验证、actor 白名单、元数据截断上限、投递重试、worker 异常隔离层层把关可验证可回归状态库离线更新、元数据解析等关键路径均有对应单测覆盖。从计划到源码读者可以沿着services/stream/stream.go→services/activitypub/outbox/ping.go→services/activitypub/inbox/leave.go→persistence/federatedserversrepository/sqlfederatedserversrepository.go这条调用链完整追踪一条 Leave 活动从本地下播到远端目录标记离线的全生命周期。【免费下载链接】owncastTake control over your live stream video by running it yourself. Streaming chat out of the box.项目地址: https://gitcode.com/GitHub_Trending/ow/owncast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考