166 lines
4.2 KiB
Markdown
166 lines
4.2 KiB
Markdown
# paseo-relay
|
||
|
||
**_[English](./README.md)_**
|
||
|
||
自托管的 Paseo relay。
|
||
|
||
该存储库将上游 [`getpaseo/paseo`](https://github.com/getpaseo/paseo) 的 `@getpaseo/relay/cloudflare` 适配器封装为一个轻量部署包装层。它不实现自定义 relay 协议、管理 API 或认证层。运行时契约与上游 Paseo 保持一致，而该存储库负责部署、校验和运维打包。
|
||
|
||
## 此存储库提供的内容
|
||
|
||
- 一个极简的 Worker 入口，重新导出上游 relay worker 和 `RelayDurableObject`
|
||
- 通过 Wrangler 完成 Durable Object 绑定
|
||
- 使用 Bun、TypeScript、Vitest 和 Wrangler dry-run 进行本地校验
|
||
- 一个在 `workerd` 上运行打包后 Worker 的 OCI 镜像
|
||
- 用于 PR 校验、`main` 分支部署和 OCI 发布的 GitHub Actions
|
||
|
||
## 运行时契约
|
||
|
||
对外暴露的运行时接口刻意保持精简：
|
||
|
||
- `GET /health` 返回 `200`，并附带 `{"status":"ok"}`
|
||
- `GET /ws?...` 处理 relay 和 WebSocket 流量
|
||
|
||
该存储库不会添加任何存储库特有的 API 端点。
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Bun `1.3.12`
|
||
- 如果你要构建或运行 OCI 镜像，需要 Docker
|
||
- 如果你要部署 Worker，需要一个 Cloudflare 账户
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
### 运行校验
|
||
|
||
```bash
|
||
bun run check
|
||
```
|
||
|
||
该命令会执行：
|
||
|
||
- Worker 类型生成
|
||
- TypeScript 检查
|
||
- Vitest Worker 测试
|
||
- 生成的类型漂移检查
|
||
- `wrangler deploy --dry-run`
|
||
|
||
### 本地 Worker 开发
|
||
|
||
```bash
|
||
bun run dev
|
||
```
|
||
|
||
### 构建并运行 OCI 镜像
|
||
|
||
```bash
|
||
bun run oci:build
|
||
bun run oci:run
|
||
```
|
||
|
||
OCI 镜像会在 `8080` 端口暴露 relay。
|
||
|
||
### 运行预构建 OCI 镜像
|
||
|
||
预构建镜像会发布到 GHCR：
|
||
|
||
```bash
|
||
docker pull ghcr.io/xixu-me/paseo-relay:main
|
||
docker run --rm -p 8080:8080 -v paseo-relay-data:/var/lib/paseo-relay/do ghcr.io/xixu-me/paseo-relay:main
|
||
```
|
||
|
||
## Cloudflare 部署
|
||
|
||
`wrangler.jsonc` 是 Worker 部署的单一事实来源：
|
||
|
||
- entrypoint: `src/index.ts`
|
||
- Durable Object binding: `RELAY`
|
||
- Durable Object class: `RelayDurableObject`
|
||
- SQLite-backed Durable Object migration: `v1`
|
||
|
||
使用以下命令部署：
|
||
|
||
```bash
|
||
bun run deploy
|
||
```
|
||
|
||
> [!NOTE]
|
||
> `workers.dev` 适合做初始验证，但面向生产的目标路径是自定义域名。
|
||
|
||
## 连接 Paseo 守护进程
|
||
|
||
Paseo 要求 relay endpoint 使用 `host:port` 形式。
|
||
|
||
> [!WARNING]
|
||
> 这里不要使用 `https://relay.example.com`。请使用 `relay.example.com:443`。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
export PASEO_RELAY_ENDPOINT="relay.example.com:443"
|
||
export PASEO_RELAY_PUBLIC_ENDPOINT="relay.example.com:443"
|
||
```
|
||
|
||
- `PASEO_RELAY_ENDPOINT` 是守护进程连接的地址
|
||
- `PASEO_RELAY_PUBLIC_ENDPOINT` 是嵌入到配对链接和二维码中的地址
|
||
|
||
## 测试
|
||
|
||
Worker 测试套件覆盖：
|
||
|
||
- `/health` 返回 `200`
|
||
- 未知路径返回 `404`
|
||
- 缺少 `serverId` 时返回 `400`
|
||
- relay 版本无效时返回 `400`
|
||
- 非 WebSocket 的 relay 请求会被拒绝
|
||
- 有效的 WebSocket 升级请求会成功
|
||
|
||
OCI 校验路径还会额外检查：
|
||
|
||
- 容器启动
|
||
- 通过 HTTP 访问 `/health`
|
||
- 针对容器化运行时的 v2 WebSocket 升级冒烟测试
|
||
|
||
## CI/CD
|
||
|
||
存储库使用四个工作流：
|
||
|
||
- `validate-reusable.yml`: 唯一的校验事实来源
|
||
- `ci.yml`: 为 pull request 和 merge group 运行校验
|
||
- `release.yml`: 先校验，再从 `main` 部署 Worker 并发布 OCI 镜像
|
||
- `auto-merge.yml`: 只为带有 `dependencies` 标签的 Dependabot PR 启用自动合并
|
||
|
||
### 发布行为
|
||
|
||
- 推送到 `main` 且变更涉及发布相关文件时，会先运行校验，然后部署 Worker 并发布 `ghcr.io/xixu-me/paseo-relay:main`
|
||
- 手动触发的 `workflow_dispatch` 运行可以选择只部署 Worker 和/或只发布 OCI 镜像
|
||
|
||
### 所需 secrets
|
||
|
||
Worker 部署需要：
|
||
|
||
- `CLOUDFLARE_API_TOKEN`
|
||
- `CLOUDFLARE_ACCOUNT_ID`
|
||
|
||
OCI 发布使用内置的 `GITHUB_TOKEN`。
|
||
|
||
## OCI 说明
|
||
|
||
镜像基于 Wrangler 生成的 Worker bundle 构建，并由 `workerd` 提供服务。预构建镜像会发布为 `ghcr.io/xixu-me/paseo-relay:main`。运行时镜像：
|
||
|
||
- 监听 `:8080`
|
||
- 将 Durable Object 状态持久化到 `/var/lib/paseo-relay/do`
|
||
- 以非 root 用户运行
|
||
|
||
## 设计目标
|
||
|
||
- 尽可能贴近上游 Paseo relay 架构
|
||
- 将存储库自有逻辑限制在部署、校验和打包
|
||
- 让 Worker 和 OCI 两条路径都能通过同一份契约进行测试
|