跳转到内容
Eidos Docs

数据中转 (Relay)

Eidos 是一款本地优先的应用——数据存在你的机器上，一切都在本地运行。这对隐私和数据所有权来说很理想，但带来了一个问题：当你的电脑关机时，来自外部服务的数据该怎么办？

把它想象成小区门口的快递柜。你不在家时，快递员仍然可以来投件，包裹会留在柜子里等你回来取。Relay 的工作方式一样——它是一个安全的云端缓冲区，代你接收外部数据，等你打开 Eidos 时再统一送达。

工作方式：生产与消费模型

Section titled “工作方式：生产与消费模型”

Relay 在设计上采用了经典的消息队列 (Message Queue) 模式，包含三个核心部分：生产者 (Producer)、中转与队列 (Broker & Queue)、消费者 (Consumer)。

      [ 生产者 (Producer) ]
      ├── Telegram Bot
      ├── Webhook / API
      └── 浏览器插件 等
              │
              ▼
      [ 云端中转 (Broker) ]
      eidos.space / relay
        (云端安全缓冲区)
              │
              ▼
      [ 本地队列 (Queue) ]
     Eidos 桌面版 inbox.sqlite3
              │
              ▼
      [ 消费者 (Consumer) ]
     ├── Relay A ─▶ Script (追加文本到今日日志)
     ├── Relay B ─▶ Script (提取数据写入指定表格)
     └── Relay C ─▶ Script (保存附件到指定文件中)

整体的流转过程如下：

  1. 生产：外部服务（如 Zapier、iOS 快捷指令、浏览器插件等）作为生产者，将数据通过 Push API 发送到你的 Relay 端点。
  2. 中转与入队：数据首先安全地暂存在云端的 Relay 中转站，作为一个安全的“快递柜”等待取件。当你打开 Eidos 桌面版时，它会自动拉取所有的待接收消息，落地本地的队列缓存中，同时云端的副本立即永久删除。
  3. 消费：你可以建立多个本地的 Relay 频道来对数据流进行路由，每个 Relay 绑定一个专属的 Script（脚本）作为消费者。当数据入队后，绑定的消费脚本会自动异步运行，按需将数据消费并分发（例如：你可以让不同的 Script 分别负责追加文本到今天的日志里面、将结构化数据写入指定的表格，或者把收集到的链接和附件写入指定的文件中）。

1. 生产消息 (Producer)

Section titled “1. 生产消息 (Producer)”

要向 Relay 生产发送数据，你需要一个 Relay API Token。在 Eidos.space 控制台 创建一个，这相当于你的写入授权，只有持有正确 Token 的服务才能向你发送消息。

Terminal window
curl -X POST https://api.eidos.space/v1/relay/channels/{channelId}/messages \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": { "event": "order.created", "orderId": "123" }
  }'

2. 消息队列暂存 (Queue)

Section titled “2. 消息队列暂存 (Queue)”

Eidos 从云端中转站取回消息后，不会直接写入主数据库，而是先落到一个独立的本地文件：inbox.sqlite3，这扮演了消息暂存队列的角色。

  • 文件夹my-space/
    • 文件夹.eidos/
      • db.sqlite3 (主数据库)
      • inbox.sqlite3 (消息队列暂存区)

分开存储的理由很简单。Eidos 会追踪 db.sqlite3 的每一次变动，它受版本控制。如果把成百上千条原始的 Webhook 数据直接塞进去，历史记录会迅速膨胀。inbox.sqlite3 是刻意不纳入版本控制的，作为一块干净的消息缓存区，等待消费者读取。

接下来，你可以编写 script 作为消费者来处理这些数据：提取你关心的字段，整理好结构，再把有价值的内容写入主数据库。你来决定什么值得保留，以及如何存储。

3. 消费消息 (Consumer)

Section titled “3. 消费消息 (Consumer)”

要开始消费队列中的消息，你可以在脚本中定义一个 Relay 处理器 (Relay Handler) 作为消费者。这模拟了 Cloudflare Workers Queue 的模式，接收一批消息并在后台进行异步处理。

export const meta = {
  type: "relayHandler",
  funcName: "handleWebhooks",
  relayHandler: {
    name: "我的消息消费者",
    description: "消费并处理接收到的 Relay 消息",
  },
}


export async function handleWebhooks(batch) {
  for (const message of batch.messages) {
    console.log("准备处理消息:", message.body);
    // 在这里添加你的业务逻辑，解析数据并存入主数据库
  }
}

详情请参考 Script 文档 中的完整 API 规范。

限制 (Limits)

Section titled “限制 (Limits)”
限制项
Free
Spark
说明
API 调用频率1000 次/小时1000 次/小时每个 API Key 的请求上限。
Channel 数量5100Channel 作为路由分类。
单条消息大小128 KB128 KB单条向 Relay 投递的 JSON 消息的最大 Payload。
云端存储配额10 MB100 MB云端待接取的总队列容量。大约相当于 5000 条 Telegram/Discord 消息（Free）或 5 万条消息（Spark）。
消息保留期限3 天14 天暂存在云端尚未被本地拉取消费的最长留存时间，超时自动清理。

下一步

Section titled “下一步”