@fedify/relay

中文文档
2.1.32发布于 2026/11/17MITTypeScriptESM + CJS构建来源已验证近 30 天下载 1.2万

活动Pub中继支持

中文使用文档
文档目录18 节
  1. 什么是活动接力?
  2. 中继协议
  3. 马斯通式接力
  4. LitePub 式继电器
  5. 安装
  6. 使用量
  7. 创建中继器
  8. 订阅处理
  9. 管理追随者
  10. 与网络框架的整合
  11. 如何运作
  12. 储存要求
  13. API 参考
  14. createRelay()
  15. Relay
  16. RelayOptions
  17. SubscriptionRequestHandler
  18. RelayFollower

@fedify/中继:活动Pub中继器用于联邦化

JSR npm Follow @fedify@hollo.social

此包自Fedify 2.0.

此软件包提供了活动Pub中继功能 联邦 生态系统,能够创建和管理能够 在联邦机构之间开展前瞻性活动.

关于建立和运作中继服务器的全面文件, 见 中继服务器 《联邦手册》中的章节。 。 。 .

什么是活动接力?

活动Pub中继器是有助于小实例的基础设施组件 参与联邦社会网络 发布公共内容而不需要的中介服务器 个人演员跟踪关系。 当一个实例订阅 中继器,所有来自该案例的公职都转交给所有其他 订阅实例,创建一个共享的联邦内容库.

中继协议

这个软件包支持两个在fediverse中使用的流行接力协议:

马斯通式接力

Mastodon 风格的中继协议使用 LD 签名进行活动 核查并跟踪公共收藏。 这个协议很广泛 由Mastodon和许多其他活动Pub的实施提供支持.

关键特性:

  • 带有适当内容类型的直接活动中继(Create, (中文(简体) ), Update, (中文(简体) ), Delete, (中文(简体) ), Move(中文(简体) )
  • LD 签名验证和生成
  • 遵循活动Pub 公开收藏
  • 通过简单的订阅机制 Follow 活动

LitePub 式继电器

LitePub 式接力协议使用双向关系 并覆盖活动 Announce 分发活动.

关键特性:

  • 接力和订阅者之间的对接
  • 包含的活动 Announce 分发
  • 分两阶段订阅(待) 已接受)
  • 加强联邦能力

安装

* :密码组

deno add jsr:@fedify/relay
npm add @fedify/relay
pnpm add @fedify/relay
yarn add @fedify/relay
bun add @fedify/relay

* :

使用量

创建中继器

以下是使用工厂功能创建中继服务器的简单例子:

import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";

// Create a Mastodon-style relay
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  // Required: Set a subscription handler to approve/reject subscriptions
  subscriptionHandler: async (ctx, actor) => {
    // For an open relay, simply return true
    // return true;

    // Or implement custom approval logic:
    const domain = new URL(actor.id!).hostname;
    const blockedDomains = ["spam.example", "blocked.example"];
    return !blockedDomains.includes(domain);
  },
});

// Serve the relay
Deno.serve((request) => relay.fetch(request));

您也可以通过更改类型来创建 LitePub 式接力 :

const relay = createRelay("litepub", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,
});

订阅处理

这个 subscriptionHandler 需要并决定是否批准或 拒绝订阅请求 。 对于接受所有订阅的开放式中继器:

const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,  // Accept all
});

也可以执行自定义批准逻辑 :

const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => {
    // Example: Only allow subscriptions from specific domains
    const domain = new URL(actor.id!).hostname;
    const allowedDomains = ["mastodon.social", "fosstodon.org"];
    return allowedDomains.includes(domain);
  },
});

管理追随者

中继器提供了查询和管理追随者的方法而不曝光 内部存储细节.

列出所有追随者

for await (const follower of relay.listFollowers()) {
  console.log(`Follower: ${follower.actorId}`);
  console.log(`State: ${follower.state}`);
  console.log(`Actor name: ${follower.actor.name}`);
  console.log(`Actor type: ${follower.actor.constructor.name}`);
}

获取特定跟踪器

const follower = await relay.getFollower("https://mastodon.example.com/users/alice");
if (follower) {
  console.log(`Found follower in state: ${follower.state}`);
  console.log(`Actor username: ${follower.actor.preferredUsername}`);
  console.log(`Inbox: ${follower.actor.inboxId?.href}`);
} else {
  console.log("Follower not found");
}

与网络框架的整合

中继器 fetch() 方法返回标准 Response 对象, 制作 兼容任何支持获取 API 的网络框架。 这个 与 Hono 相关的示例 :

import { Hono } from "hono";
import { createRelay } from "@fedify/relay";
import { MemoryKvStore } from "@fedify/fedify";

const app = new Hono();
const relay = createRelay("mastodon", {
  kv: new MemoryKvStore(),
  origin: "https://relay.example.com",
  subscriptionHandler: async (ctx, actor) => true,
});

app.use("*", async (c) => {
  return await relay.fetch(c.req.raw);
});

export default app;

如何运作

中继器由:

  1. 演员注册:中继器以服务演员的身份呈现于 /users/relay
  2. 订阅:通过发送一个 Follow 活动
  3. 核准:中继器的订阅处理器决定是否 核准订阅 Accept 或者说 Reject(中文(简体) )
  4. 转发: 当一个订阅实例发送活动时(Create, (中文(简体) ), Update, (中文(简体) ), Delete, (中文(简体) ), Move)到继电器的收件箱,继电器转发它们 所有其它订阅实例
  5. 取消订阅: 实例可以通过发送 Undo 活动 包装他们的正本 Follow 活动

储存要求

中继需要密钥- 值存储持续 :

  • 订阅者列表及其后续活动ID
  • 订阅者演员信息
  • 中继密码密钥对 (RSA和Ed25519)

任意 KvStore 可使用来自联邦的实施工作,包括:

  • MemoryKvStore (供开发/试验)
  • DenoKvStore (德诺克V)
  • RedisKvStore (雷迪斯语)
  • PostgresKvStore (PostgreSQL) (英语)
  • MysqlKvStore (MySQL/马里亚DB)
  • SqliteKvStore (SQLite) (英语)

对于生产用途,选择像Redis一样的持久存储后端, PostgreSQL,即MySQL/马里亚DB. 见 补充关于关键价值库存的文件 更多细节.

API 参考

createRelay()

工厂功能创建中继实例 .

function createRelay(
  type: "mastodon" | "litepub",
  options: RelayOptions
): Relay

参数:

  • type: 要创建的继电器类型 ("mastodon" 或者说 "litepub"(中文(简体) )
  • options: 中继的配置选项

回返情况: A 类 Relay 实例

Relay

活动Pub中继执行的公共接口.

方法

  • fetch(request: Request): Promise<Response>: 处理收到的 HTTP 请求
  • listFollowers(): AsyncIterableIterator<RelayFollower>: 列出全部 中继的后继者
  • getFollower(actorId: string): Promise<RelayFollower | null>: 获取 由演员 ID 指定跟踪者
  • getActorUri(): Promise<URL>: 获得接力演员的URI
  • getSharedInboxUri(): Promise<URL>: 获取中继器共享的收件箱 URI

中继类型

呼叫时指定中继类型 createRelay()数字 :

  • "mastodon": Mastodon兼容中继器,使用直接活性转发, 立即批准订阅和LD签名
  • "litepub": LitePub 相容继电器,采用双向跟踪, 包含的活动 Announce,以及两阶段订阅

RelayOptions

中继的配置选项 :

  • kv: KvStore (需要):持续中继数据的关键值存储
  • origin: string (要求):Relay的出处URL(例如,, "https://relay.example.com"(中文(简体) )
  • name?: string: 中继显示名( 默认为 "ActivityPub Relay"(中文(简体) )
  • subscriptionHandler: SubscriptionRequestHandler (需要): 负责 订阅核准/拒绝
  • documentLoaderFactory?: DocumentLoaderFactory: 自定义文档加载器 工厂
  • authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory数字 : 自定义认证的文件加载厂
  • queue?: MessageQueue: 用于背景活动处理的信件队列

SubscriptionRequestHandler

决定是否批准订阅请求的函数:

type SubscriptionRequestHandler = (
  ctx: Context<RelayOptions>,
  clientActor: Actor,
) => Promise<boolean>

参数:

  • ctx: 带有中继选项的上下文对象
  • clientActor: 请求订阅的演员

回返情况:

  • true 核准订阅
  • false 拒绝订阅

RelayFollower

中继器的追随者, 具有有效的代理实例 :

interface RelayFollower {
  readonly actorId: string;
  readonly actor: Actor;
  readonly state: "pending" | "accepted";
}

属性 :

  • actorId:追随者的演员ID(URL)
  • actor: 经验证的演员对象
  • state:后人所领之州"pending" 或者说 "accepted"(中文(简体) )

版本与发布记录

@fedify/relay 共发布 575 个版本,首次发布于 2025/11/13;过去 12 个月发布了 571 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.1.32latest2026/11/17今天
2.0.362026/11/17今天
2.3.16-dev.28452026/11/17今天
2.5.0-dev.28442026/11/17今天
2.0.36-dev.28432026/11/17今天
2.3.16-dev.28412026/11/17今天

其他发布通道:pr-478 → 2.0.0-pr.478.1918,pr-479 → 2.0.0-pr.479.1922,pr-490 → 2.0.0-pr.490.2,pr-559 → 2.0.0-pr.559.6,pr-633 → 2.0.6-pr.633.9,pr-639 → 2.0.7-pr.639.14。

关于 @fedify/relay 的常见问题

@fedify/relay 是什么?

活动Pub中继支持

如何安装 @fedify/relay?

在项目目录运行 npm install @fedify/relay,或使用 pnpm add / yarn add / bun add。

@fedify/relay 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@fedify/relay 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@fedify/relay 可以商用吗?

@fedify/relay 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@fedify/relay 的下载量有多少?

根据 npm 官方下载统计,@fedify/relay 在 2026/10/15 – 2026/11/13 这 30 天内被下载 12,261 次,日均约 409 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fedify/relay 还在维护吗?

最新版本 2.1.32 发布于 2026/11/17(今天);至今共发布 575 个版本,其中过去 12 个月发布了 571 个;首次发布于 2025/11/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。