小橘
24866be8a9
- Agent guide: replace LRU/子Worker section with Dynamic Workers architecture - Backend LRU doc: add evolution note, link to Dynamic Workers docs - Zero DNS latency, single Worker, V8 Isolate sandboxing
396 lines
14 KiB
Markdown
396 lines
14 KiB
Markdown
# Sigil Backend — 抽象接口与 LRU 调度
|
|
|
|
!!! abstract "一句话"
|
|
一套接口，两种实现。$5 方案用 LRU 换页在 500 个 Worker 配额内调度无限能力；$25 方案用 dispatch namespace 直接常驻。用户按预算选择，Agent 代码不用改。
|
|
|
|
**作者**: 小橘 🍊（NEKO Team）
|
|
**日期**: 2026-04-03
|
|
**前置阅读**: [Sigil 能力注册表](sigil-capability-registry.md) · [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)
|
|
|
|
## 为什么需要抽象
|
|
|
|
Sigil 的第一版设计直接选择了 Workers for Platforms（$25/月）。但重新审视后发现：
|
|
|
|
- **单用户场景**：每个 Sigil 实例只服务一个用户（主人）+ 几个 Agent
|
|
- **400 个能力绰绰有余**：$5 方案 500 配额 - 系统保留 ≈ 400+ 可用槽位
|
|
- **$25 对个人用户偏贵**：WfP 的"无限 Worker"是为多租户 SaaS 设计的，我们用不完
|
|
|
|
所以正确的做法不是二选一，而是**抽象出统一接口，底层可切换**。
|
|
|
|
## 抽象接口
|
|
|
|
```typescript
|
|
/**
|
|
* Sigil Backend — 能力生命周期管理
|
|
* 两种实现共享同一套接口，Agent 和 Sigil 网关不感知底层差异
|
|
*/
|
|
interface SigilBackend {
|
|
/** 部署一个能力（新建或更新） */
|
|
deploy(params: DeployParams): Promise<DeployResult>
|
|
|
|
/** 调用一个能力 */
|
|
invoke(name: string, request: Request): Promise<Response>
|
|
|
|
/** 移除一个能力 */
|
|
remove(name: string): Promise<void>
|
|
|
|
/** 列出所有能力 */
|
|
list(filter?: ListFilter): Promise<Capability[]>
|
|
|
|
/** 获取能力元数据 */
|
|
inspect(name: string): Promise<CapabilityMeta | null>
|
|
|
|
/** 获取后端状态（配额、LRU 信息等） */
|
|
status(): Promise<BackendStatus>
|
|
}
|
|
|
|
interface DeployParams {
|
|
agent: string // Agent 标识
|
|
name: string | null // null = 自动生成临时名
|
|
code: string // Worker 源码
|
|
type: 'persistent' | 'normal' | 'ephemeral'
|
|
ttl?: number // 秒，仅 ephemeral
|
|
bindings?: string[] // 所需 bindings 声明
|
|
}
|
|
|
|
interface DeployResult {
|
|
capability: string // 完整名：xiaoju--ping
|
|
url: string // 调用 URL
|
|
expires_at?: string // 仅 ephemeral
|
|
cold_start: boolean // 是否触发了换页（仅 WorkerPool）
|
|
evicted?: string // 被淘汰的能力名（仅 WorkerPool）
|
|
}
|
|
|
|
interface BackendStatus {
|
|
backend: 'worker-pool' | 'platform'
|
|
total_slots: number // 总槽位（WorkerPool: ~400, Platform: Infinity）
|
|
used_slots: number // 已用槽位
|
|
agents: number // 注册 Agent 数
|
|
lru_enabled: boolean // LRU 是否激活
|
|
eviction_count: number // 累计淘汰次数
|
|
}
|
|
```
|
|
|
|
## 两种实现
|
|
|
|
### WorkerPool（$5/月）— 默认推荐
|
|
|
|
**原理**：每个能力是一个独立 CF Worker，Sigil 通过 CF API 管理部署/删除，用 LRU 策略在有限配额内调度。
|
|
|
|
```
|
|
┌──────────────────────────────────────────────┐
|
|
│ Sigil 网关 │
|
|
│ sigil.shazhou.workers.dev │
|
|
│ ┌────────┬────────┬────────┬─────────────┐ │
|
|
│ │ 路由表 │ LRU 表 │ 鉴权 │ CF API 客户端│ │
|
|
│ │ (KV) │ (KV) │ (KV) │ │ │
|
|
│ └───┬────┴───┬────┴───┬───┴──────┬──────┘ │
|
|
└──────┼────────┼────────┼──────────┼──────────┘
|
|
│ │ │ │
|
|
▼ ▼ ▼ ▼
|
|
┌─────────┐ ┌─────────┐ CF API
|
|
│ s-xxx │ │ s-yyy │ (deploy/delete)
|
|
│ (热) │ │ (热) │ │
|
|
└─────────┘ └─────────┘ ▼
|
|
┌─────────┐
|
|
│ s-zzz │
|
|
│ (换入) │
|
|
└─────────┘
|
|
```
|
|
|
|
**请求流（命中）**：
|
|
```
|
|
请求 → Sigil → 查路由表 → 已部署 → 302 重定向到 s-xxx.shazhou.workers.dev
|
|
或 subrequest 转发
|
|
延迟：< 5ms（一次 KV 读 + 重定向）
|
|
```
|
|
|
|
**请求流（未命中 — 换页）**：
|
|
```
|
|
请求 → Sigil → 查路由表 → 未部署 → 触发换入
|
|
→ 配额满？→ LRU 选出最冷 Worker → CF API 删除（换出）
|
|
→ CF API 从 KV 拉代码 → 部署新 Worker（换入）
|
|
→ 更新路由表 + LRU 表
|
|
→ 转发请求
|
|
延迟：1-3s（CF API 部署时间）
|
|
```
|
|
|
|
### Platform（$25/月）— 大规模方案
|
|
|
|
**原理**：使用 Workers for Platforms 的 dispatch namespace，namespace 内 Worker 无限且常驻。
|
|
|
|
```
|
|
┌──────────────────────────────────────────────┐
|
|
│ Sigil 网关 │
|
|
│ sigil.shazhou.workers.dev │
|
|
│ ┌────────┬────────┬─────────────────────┐ │
|
|
│ │ 路由 │ 鉴权 │ DISPATCHER binding │ │
|
|
│ └───┬────┴───┬────┴──────────┬──────────┘ │
|
|
└──────┼────────┼───────────────┼──────────────┘
|
|
│ │ │
|
|
│ │ env.DISPATCHER.get(name)
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────────────────────────────────┐
|
|
│ Dispatch Namespace: production │
|
|
│ 无限 Worker，全部常驻，无需换页 │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
**请求流**：
|
|
```
|
|
请求 → Sigil → 鉴权 → env.DISPATCHER.get("xiaoju--ping") → 响应
|
|
延迟：< 1ms（进程内调用，无网络开销）
|
|
```
|
|
|
|
### 对比
|
|
|
|
| 维度 | WorkerPool ($5) | Platform ($25) |
|
|
|------|-----------------|----------------|
|
|
| 月费 | $5 | $25 |
|
|
| 能力上限 | ~400（LRU 管理） | 无限 |
|
|
| 命中延迟 | < 5ms（KV + 重定向） | < 1ms（进程内） |
|
|
| 未命中延迟 | 1-3s（CF API 部署） | 无（全部常驻） |
|
|
| LRU | **核心机制** | 不需要 |
|
|
| 实现复杂度 | 高 | 低 |
|
|
| 适合 | 个人用户、小团队 | 平台级、多租户 |
|
|
| 子域名占用 | 每个热能力 1 个 | 只占 Sigil 1 个 |
|
|
|
|
## LRU 调度详细设计（WorkerPool 方案核心）
|
|
|
|
### 数据结构
|
|
|
|
用 KV 存储两张表：
|
|
|
|
**路由表** `route:{capability}` → Worker 子域名映射
|
|
|
|
```json
|
|
{
|
|
"worker_name": "s-a3f8c1",
|
|
"subdomain": "s-a3f8c1.shazhou.workers.dev",
|
|
"agent": "xiaoju",
|
|
"deployed_at": 1743648000,
|
|
"type": "persistent"
|
|
}
|
|
```
|
|
|
|
**LRU 表** `lru:{capability}` → 访问时间戳
|
|
|
|
```json
|
|
{
|
|
"last_access": 1743648500,
|
|
"access_count": 42,
|
|
"deployed": true
|
|
}
|
|
```
|
|
|
|
### 淘汰算法
|
|
|
|
```
|
|
function evict():
|
|
candidates = 所有 deployed=true 的 LRU 条目
|
|
|
|
# 分优先级淘汰（先淘汰低优先级）
|
|
# 1. 临时能力（已过期的直接删，未过期的也优先淘汰）
|
|
# 2. 普通能力（按 last_access 排序）
|
|
# 3. 持久能力（最后才动，按 last_access 排序）
|
|
|
|
candidates.sort(by: priority ASC, last_access ASC)
|
|
victim = candidates[0]
|
|
|
|
CF_API.delete(victim.worker_name)
|
|
KV.put("lru:" + victim.capability, { deployed: false, ... })
|
|
KV.delete("route:" + victim.capability)
|
|
|
|
return victim
|
|
```
|
|
|
|
**淘汰优先级**：
|
|
|
|
```
|
|
临时(过期) > 临时(未过期) > 普通 > 持久
|
|
```
|
|
|
|
同优先级内按 `last_access` 升序（最久未访问的先淘汰）。
|
|
|
|
### 换入流程
|
|
|
|
```
|
|
function page_in(capability):
|
|
# 1. 检查配额
|
|
used = count(deployed=true)
|
|
if used >= max_slots:
|
|
evicted = evict() # 换出最冷的
|
|
log("evicted", evicted)
|
|
|
|
# 2. 从 KV 拉代码
|
|
code = KV.get("code:" + capability)
|
|
|
|
# 3. 生成 Worker 名（或复用已有名）
|
|
worker_name = "s-" + hash(capability)[:6]
|
|
|
|
# 4. CF API 部署
|
|
CF_API.deploy(worker_name, code)
|
|
|
|
# 5. 更新路由表 + LRU 表
|
|
KV.put("route:" + capability, { worker_name, ... })
|
|
KV.put("lru:" + capability, { deployed: true, last_access: now() })
|
|
|
|
return worker_name
|
|
```
|
|
|
|
### Worker 命名与子域名
|
|
|
|
```
|
|
能力名：xiaoju--ping
|
|
Worker 名：s-a3f8c1（hash 前 6 位）
|
|
子域名：s-a3f8c1.shazhou.workers.dev
|
|
```
|
|
|
|
用 `s-` 前缀标记 Sigil 管理的 Worker，与用户自己的 Worker 区分。hash 基于能力全名，同一个能力换出再换入会复用同一个子域名，**外部链接不会失效**。
|
|
|
|
!!! tip "解决方案一的子域名失效问题"
|
|
固定 hash 映射意味着 `s-a3f8c1` 永远对应 `xiaoju--ping`。即使被换出，重新换入后子域名不变。这是 WorkerPool 方案相比朴素 LRU 的关键改进。
|
|
|
|
### 配额分配
|
|
|
|
```yaml
|
|
sigil:
|
|
backend: "worker-pool" # 或 "platform"
|
|
worker_pool:
|
|
total_quota: 500 # CF 账户总配额
|
|
system_reserved: 5 # 系统 Worker（sigil 自身、forge 等）
|
|
user_reserved: 50 # 用户自己的 Worker（可配置）
|
|
safety_margin: 5 # 安全余量
|
|
# max_slots = 500 - 5 - 50 - 5 = 440
|
|
|
|
eviction:
|
|
priority: ["ephemeral_expired", "ephemeral", "normal", "persistent"]
|
|
|
|
agents:
|
|
max_agents: 8
|
|
deploy_cooldown: 5s
|
|
|
|
ephemeral:
|
|
max_per_agent: 20
|
|
default_ttl: 3600
|
|
max_ttl: 86400
|
|
```
|
|
|
|
### 预热策略
|
|
|
|
冷启动 1-3s 对首次请求体验不好。两个缓解方案：
|
|
|
|
**1. 热门能力预热**
|
|
|
|
Sigil cron（每小时）扫描 `stats:` 前缀，把访问频率 top-N 的能力提前部署：
|
|
|
|
```
|
|
cron → 读 stats → 排序 → top-N 未部署的 → page_in
|
|
```
|
|
|
|
**2. 异步换入 + 队列响应**
|
|
|
|
对非实时请求，Sigil 可以先返回 202 + 回调 URL：
|
|
|
|
```json
|
|
{
|
|
"status": "warming",
|
|
"callback": "https://sigil.shazhou.workers.dev/_status/xiaoju--heavy-task",
|
|
"eta_seconds": 3
|
|
}
|
|
```
|
|
|
|
Agent 轮询或 webhook 回调拿结果。
|
|
|
|
### 性能指标
|
|
|
|
| 场景 | 延迟 | 说明 |
|
|
|------|------|------|
|
|
| 命中（热能力） | < 5ms | KV 读 + 重定向/subrequest |
|
|
| 未命中（冷启动） | 1-3s | CF API 部署 + 转发 |
|
|
| 命中 + 换出 | 1-3s | 先换出再换入（异步换出可优化到不阻塞） |
|
|
| 临时能力创建 | 1-3s | 部署新 Worker |
|
|
|
|
### 异步换出优化
|
|
|
|
换出操作（CF API 删除）不需要阻塞当前请求。可以：
|
|
|
|
1. 标记 victim 为 `evicting`（路由表保留）
|
|
2. 先部署新 Worker
|
|
3. 新请求可达后，异步删除 victim
|
|
|
|
这样用户感知的延迟只有换入的 1-3s，换出在后台完成。
|
|
|
|
## 配置切换
|
|
|
|
用户在 Sigil 配置中一行切换：
|
|
|
|
```yaml
|
|
# $5 方案（默认）
|
|
sigil:
|
|
backend: "worker-pool"
|
|
|
|
# $25 方案
|
|
sigil:
|
|
backend: "platform"
|
|
```
|
|
|
|
Sigil 网关初始化时根据配置加载对应的 `SigilBackend` 实现。Agent 和调用方完全不感知底层差异。
|
|
|
|
## 演进路径（修订）
|
|
|
|
```
|
|
Phase 0（当前）: 独立 Worker，手动部署
|
|
↓
|
|
Phase 1: Sigil 网关 + WorkerPool backend（$5）
|
|
基础路由 + LRU 换页 + 健康端点
|
|
↓
|
|
Phase 2: Agent 鉴权 + 临时能力 + TTL 清理
|
|
↓
|
|
Phase 3: 抽象接口稳定 + Platform backend 实现（$25 可选）
|
|
↓
|
|
Phase 4: 预热策略 + 异步换出 + 可观测性 + 告警
|
|
```
|
|
|
|
**Phase 1 最小可行产品**：
|
|
|
|
- [ ] Sigil dispatch Worker 骨架
|
|
- [ ] KV 路由表 + LRU 表
|
|
- [ ] `deploy()` → CF API 部署 Worker
|
|
- [ ] `invoke()` → 查路由 → 命中转发 / 未命中换入
|
|
- [ ] `remove()` → CF API 删除 + 清理 KV
|
|
- [ ] `status()` → 返回配额和 LRU 状态
|
|
- [ ] `/_health` 端点
|
|
|
|
## 相关链接
|
|
|
|
- [Sigil 能力注册表](sigil-capability-registry.md)（架构总览）
|
|
- [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)（前置概念）
|
|
- [CF Workers API](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/)（部署/删除 Worker）
|
|
- [Workers for Platforms](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/)（$25 方案参考）
|
|
- [Dynamic Workers](https://developers.cloudflare.com/dynamic-workers/)（实际采用方案）
|
|
|
|
---
|
|
|
|
来源：2026-04-03 主人提出抽象接口 + 双实现方案，小橘基于 LRU 核心地位重新设计
|
|
|
|
---
|
|
|
|
## 架构演进记录（2026-04-03）
|
|
|
|
!!! success "实际落地：Dynamic Workers LOADER"
|
|
设计阶段规划了三种方案（$5 LRU 换页 / $25 WfP / 预分配 Slot Pool），最终采用 **Cloudflare Dynamic Workers LOADER**（open beta），完全跳过了子 Worker 管理的复杂度。
|
|
|
|
**Dynamic Workers 方案**：
|
|
|
|
- Sigil 是唯一的 Worker，能力代码通过 `env.LOADER.get(id, callback)` 在运行时动态加载
|
|
- 代码在 V8 Isolate 沙箱中执行，独立内存，安全隔离
|
|
- 不创建独立 Worker，不占配额，零 DNS 延迟
|
|
- `LOADER.get()` 按 ID 缓存实例，同一能力复用 Worker 实例
|
|
- 计费：每次 invoke = 2 次请求（Sigil + Dynamic Worker）
|
|
|
|
**LRU 的角色变化**：原设计中 LRU 管理"哪些 Worker 在线"（物理部署状态），现在 LRU 管理的是逻辑状态标记（deployed/not-deployed），LOADER 缓存自行管理内存中的实例生命周期。
|
|
|
|
**本文档保留为设计参考**，实际实现以 [Agent 实战指南](sigil-agent-guide.md) 为准。
|