# @evolu/relay 中文文档

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

版本：4\.2\.22
npm 元数据更新时间：2026-10-31T23:06:15.629Z
中文译文更新时间：2026-11-01T03:44:55.332Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：10.6 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.20\.0
- 运行依赖：2 个
- 首次发布：2025-10-14T14:11:49.064Z
- 最新版本发布：2026-10-31T23:06:15.303Z
- 已发布版本数：36（近 12 个月 29 个）

## 中文简介

Evolu中继服务器

## 安装

```sh
npm install @evolu/relay
```

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

## README

# Evolu继电器

Evolu Relay为Evolu应用程序提供同步和备份。这个包裹是 基于Node.js的引用中继。它被发布到npm `@evolu/relay` 和 到Docker Hub [`evoluhq/relay`](https://hub.docker.com/r/evoluhq/relay).

默认情况下，中继侦听端口4000，并将其SQLite数据库存储在端口4000中 这个 `data` 当前工作目录的目录。将应用程序指向 `ws://localhost:4000/` 通过在Evolu配置中设置WebSocket传输。

## 使用npm运行

```bash
npx @evolu/relay
```

## 使用Docker运行

```bash
docker run -d --restart unless-stopped --log-driver local -p 4000:4000 -v evolu-relay-data:/app/data docker.io/evoluhq/relay:4
```

对于Docker Compose，请下载存储库的 [`docker-compose.yml`](https://github.com/evoluhq/evolu/blob/main/apps/relay/docker-compose.yml)， 设置相同的重启策略，然后运行 `docker compose up` 从 包含该文件的目录。

标签跟随npm包版本： `4.0.0`， `4.0`， `4`, `latest` 为 最新的稳定版本。预发布版本只获得完整版本标签。

## 在服务器上运行

通过HTTPS服务的应用程序只能连接到a `wss://` 继电器。存储库的 [`docker-compose.caddy.yml`](https://github.com/evoluhq/evolu/blob/main/apps/relay/docker-compose.caddy.yml) 把接力棒跑到后面 [球童](https://caddyserver.com/)，它获取并更新a 让我们为您的域名加密证书。只有卡迪可以联系到 外面：它提供服务 `wss://` 在443端口上，并使用端口80作为证书 挑战和重定向到HTTPS。

指向一个DNS名称，例如 `relay.example.com`，在服务器上使用Docker 安装从 [码头工人的包](https://docs.docker.com/engine/install/)， 其中包括Docker Compose，并开放端口80和443。然后跑在一个空 服务器上的目录：

```bash
curl -fsSL -o compose.yaml https://raw.githubusercontent.com/evoluhq/evolu/main/apps/relay/docker-compose.caddy.yml
echo "RELAY_DOMAIN=relay.example.com" > .env
docker compose up -d
```

将应用程序指向 `wss://relay.example.com/`，以及正常运行时间监视器 `https://relay.example.com/health`． 中继的数据库和凯迪的 证书保存在卷中，因此它们在重新启动后仍然有效。要升级，请运行 `docker compose pull` 和 `docker compose up -d` 在那个目录里。

继电器读出它的 `EVOLU_RELAY_*` 变量 [配置](https://npmcn.com/package/%40evolu/relay/#readme-configure) 从 `.env` 太;运行 `docker compose up -d` 再换一次。离开 `PORT` 未设置，因为Caddy代理到端口4000。中继器接受任何符合以下条件的所有者 连接，所以任何找到它的人都可以存储数据，直到磁盘满； `EVOLU_RELAY_MAX_OWNER_BYTES` 限制每个所有者，而不是总数。

## 验证映像

每个映像都使用GitHub工件认证签名。与 [GitHub CLI](https://cli.github.com/)，检查该存储库是否为Docker 工作流在 `main` 建立一个图像，并打印它验证的摘要：

```bash
gh attestation verify oci://docker.io/evoluhq/relay:4.2.15 \
  --repo evoluhq/evolu \
  --signer-workflow evoluhq/evolu/.github/workflows/docker.yaml \
  --source-ref refs/heads/main \
  --format json \
  --jq '.[].verificationResult.statement.subject[] | "\(.name)@sha256:\(.digest.sha256)"'
```

要完全运行已验证的映像，请替换 `docker.io/evoluhq/relay:4` 在 这个 `docker run` 上面的命令，或者中继器 `image` 在撰写文件中，使用 印刷的参考资料，例如 `docker.io/evoluhq/relay@sha256:…`． 标签，例如 `4` 迁移到每个新版本，因此在迁移到每个新版本之前要对其进行验证。 [供应链](https://www.evolu.dev/docs/supply-chain) 解释了 认证能证明什么，不能证明什么。

## 重新启动

一个缺陷，一个继电器无法修复的错误，会使它关闭连接 并以代码1退出，因为它无法证明其共享状态是静止的 完好无损。在重启它的东西下运行它：Docker重启策略 上面的Compose文件，或者npm的systemd等服务管理器 包中。客户端重新连接并同步他们错过的内容。

## 配置

继电器上写着 `PORT` 和Relay-specific `EVOLU_RELAY_*` 环境变量:

| 变量 | 默认的 | 描述 |
| --- | --- | --- |
| `PORT` | `4000` | 要侦听的TCP端口，也由托管平台提供。 |
| `EVOLU_RELAY_MAX_OWNER_BYTES` | 没有限制 | 每个所有者的存储配额，作为大小字面值，例如 `10MiB`. |
| `EVOLU_RELAY_LOG_LEVEL` | `log` | 控制台级别，从 `trace` 来 `silent`. `debug` 也记录连接， `trace` 每个SQL查询。 |

在 `debug`，日志包括ownerid和被拒绝连接的url。在 `trace`，它还包括每个SQL查询的参数和结果行，其中 它们是每个所有者的写密钥和加密的更改。使用这些级别仅用于 调试，并使这些日志与中继的数据库一样私有。

配额值使用 `ByteSizeLiteral`，例如 `0B`， `512KiB`，或者 `1.5GiB`. 空字节计数，例如 `1048576` 不被接受；使用 `1MiB` 代替。 如果没有每个所有者的存储限制，则不设置该变量，或者设置配额 适合您的部署。 `0B` 不允许存储字节；它不会禁用 配额。每个所有者配额不是对磁盘总使用情况的限制。

一个无效的 `PORT`或空的、畸形的或未知的 `EVOLU_RELAY_*` 变量, 使用格式化的验证错误停止中继。提供的值无效 永远不要退回到默认状态。 `EVOLU_RELAY_PORT` 不支持；使用 `PORT`.

```bash
PORT=4001 EVOLU_RELAY_MAX_OWNER_BYTES=10MiB npx @evolu/relay
```

对于正常运行时间监视器和负载平衡器，由中继应答 `GET` 和 `HEAD` 请求 `/health` 状态为200，而它的数据库文件可以读取和 状态为503。Docker健康检查请求启用它 `PORT`． 使用一个 固定的，非零端口在Docker； `PORT=0` 选择一个不可预测的端口 健康检查无法发现。 图像暴露端口4000，因此显式映射自定义端口：

```bash
docker run -d --restart unless-stopped --log-driver local -e PORT=4001 -p 4001:4001 -v evolu-relay-data:/app/data docker.io/evoluhq/relay:4
```

要添加授权或将中继集成到您自己的服务器中，请使用 `createRelay` API从 `@evolu/nodejs` 代替。这个包的 [`src/index.ts`](https://github.com/evoluhq/evolu/blob/main/apps/relay/src/index.ts) 是完整的例子。

## 常见问题

### @evolu/relay 是什么？

Evolu中继服务器

### 如何安装 @evolu/relay？

在项目目录运行 npm install @evolu/relay，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 evolu-relay，可以用 npx evolu-relay 直接运行。

### @evolu/relay 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/evolu\_\_relay 是否存在。

### @evolu/relay 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @evolu/relay 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.20\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @evolu/relay 可以商用吗？

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

### @evolu/relay 还在维护吗？

最新版本 4\.2\.22 发布于 2026/11/01（2 天前）；至今共发布 36 个版本，其中过去 12 个月发布了 29 个；首次发布于 2025/10/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。