# @fedify/relay 中文文档

规范地址：https://npmcn.com/package/%40fedify/relay/

版本：2\.1\.32
npm 元数据更新时间：2026-11-17T06:46:03.414Z
中文译文更新时间：2026-11-17T06:46:45.970Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fedify/relay
原文对照：https://npmcn.com/package/%40fedify/relay/?lang=original
项目主页：https://fedify.dev/
源码仓库：https://github.com/fedify-dev/fedify

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.2 MB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-11-13T14:23:36.398Z
- 最新版本发布：2026-11-17T06:46:03.060Z
- 近 30 天下载量：12261（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：575（近 12 个月 570 个）

## 中文简介

活动Pub中继支持

## 安装

```sh
npm install @fedify/relay
```

也可以使用：`pnpm add @fedify/relay`、`yarn add @fedify/relay`、`bun add @fedify/relay`

## README

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

[![JSR](https://jsr.io/badges/@fedify/relay)](https://jsr.io/@fedify/relay) [![npm](https://img.shields.io/npm/v/@fedify/relay?logo=npm)](https://www.npmjs.com/package/@fedify/relay) [![Follow @fedify@hollo.social](https://fedi-badge.deno.dev/@fedify@hollo.social/followers.svg)](https://hollo.social/@fedify)

_此包自Fedify 2.0._

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

关于建立和运作中继服务器的全面文件, 见 [_中继服务器_ 《联邦手册》中的章节](https://fedify.dev/manual/relay)。 。 。 .

## 什么是活动接力?

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

## 中继协议

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

### 马斯通式接力

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

关键特性:

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

### LitePub 式继电器

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

关键特性:

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

## 安装

\* :密码组

```sh
deno add jsr:@fedify/relay
```

```sh
npm add @fedify/relay
```

```sh
pnpm add @fedify/relay
```

```sh
yarn add @fedify/relay
```

```sh
bun add @fedify/relay
```

\* :

## 使用量

### 创建中继器

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

```typescript
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 式接力 :

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

### 订阅处理

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

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

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

```typescript
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);
  },
});
```

### 管理追随者

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

#### 列出所有追随者

```typescript
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}`);
}
```

#### 获取特定跟踪器

```typescript
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 相关的示例 :

```typescript
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. 见 [补充关于关键价值库存的文件](https://fedify.dev/manual/kv) 更多细节.

## API 参考

### `createRelay()`

工厂功能创建中继实例 .

```typescript
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`

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

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

**参数:**

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

**回返情况:**

-   `true` 核准订阅
-   `false` 拒绝订阅

### `RelayFollower`

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

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

**属性 :**

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

## 常见问题

### @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 个月发布了 570 个；首次发布于 2025/11/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

