mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 22:18:43 +00:00
* feat(runner): replace server-side bash sandbox with remote runner * fix(runner): address review findings for output bounds, key rotation, defaults, and generated uploads * chore(docker): remove sandbox privileges and env vars from remaining compose files * feat(cli): add runner start with bundled SRT sandboxing (#535) * refactor(agent): expose runner bash without skill gating * feat(cli): add runner start with optional SRT sandboxing * refactor(cli): remove runner Python dependency * feat(cli): bundle SRT and use platform-native runner shells * refactor(cli): delegate runner processes to Execa * chore(cli): upgrade @anthropic-ai/sandbox-runtime to 0.0.83 * feat(cli): discover Bash for Windows runners Use Pi-style Bash discovery and launch behavior, exercise the packaged CLI shell, and wait for pending ZIP metadata reads before closing cancelled downloads. * fix(runner): enforce ownership and safe reconnects Gate dispatch on reconciliation, retain cancellations across disconnects, and stop replaced clients. Guard the single-server runner topology with a database lease. Restage missing generated inputs, report signal exits, and bound generated-file cleanup. * feat(webui): add Korean translations for agent runners * feat(cli): add runner event logging and --verbose flag (#536) * feat(cli): add runner event logging and --verbose flag * fix(cli): log runner capacity rejections accurately and use monotonic duration
101 lines
6.5 KiB
Plaintext
101 lines
6.5 KiB
Plaintext
---
|
||
title: 分布式 Worker 部署
|
||
description: 将媒体转码部署到独立 Worker,智能体随主服务器运行。
|
||
---
|
||
|
||
智能体、嵌入和归档队列随 Shumai 主服务器一起启动。媒体转码仍可通过 PostgreSQL 和 DBOS 队列交给独立 Worker。
|
||
|
||
## 主服务器
|
||
|
||
设置 `SHUMAI_WORKERS=none`(或 `--workers=none`)时,主服务器处理智能体和归档任务,转码交给独立 Worker。`all` 和 `transcode` 会同时在主服务器运行转码队列。旧的 `agent`、`ai`、`archive` 参数仍可使用,均启动智能体和归档队列。
|
||
|
||
主服务器需安装智能体沙箱依赖(Linux 使用 `bubblewrap`,macOS 使用 `sandbox-exec`)。不再支持独立启动智能体 Worker。
|
||
|
||
## 独立转码 Worker
|
||
|
||
在 Worker 上配置与主服务器相同的 PostgreSQL 数据库和 S3 存储。多台机器不共享文件系统时,必须使用 S3 兼容存储。
|
||
|
||
```bash
|
||
npm install -g @shumai-one/shumai-transcode
|
||
shumai-transcode
|
||
```
|
||
|
||
也可以使用 Docker:
|
||
|
||
```bash
|
||
docker run -d --name shumai-transcode-worker --env-file .env shumaione/shumai-transcode:latest
|
||
```
|
||
|
||
Bun 用户可运行 `bun run --bun shumai-transcode`。
|
||
|
||
## 升级现有智能体会话
|
||
|
||
升级主服务器前,请等待旧智能体 Worker 完成任务并将其停止。正常数据库迁移会自动将已有会话上下文复制为独立记录,无需额外运行迁移脚本。过渡期间保留旧记录表。
|
||
|
||
每个会话使用独立的本地 SQLite 工作副本,缺失时自动从 PostgreSQL 恢复。可用 `AGENT_SESSION_CACHE_DIR` 指定缓存目录。主服务器在确认提交前将精简记录同步至 PostgreSQL。本地副本可重建,备份应包含 PostgreSQL。图片和技能内容在两种存储中继续使用动态占位符,在智能体需要时解析。
|
||
|
||
---
|
||
|
||
## Worker 并发与多实例部署
|
||
|
||
### 并发调优
|
||
|
||
Worker 根据可配置的并发上限从 PostgreSQL 队列中拉取任务:
|
||
|
||
- `CONCURRENCY_TRANSCODE`:单个 Worker 最大并发视频转码任务数(默认 `1`)。
|
||
- `CONCURRENCY_AGENT`:单个主服务器最大并发智能体及向量嵌入工作流数(默认 `5`,若搭配本地 `embedding-server` 建议设为 `1`)。
|
||
|
||
### 副本实例标识
|
||
|
||
当在多台机器或 Pod 上运行转码 Worker 或主服务器 的多个副本时:
|
||
|
||
- `DbosExecutor` 会自动基于机器主机名与进程 ID 派生唯一的单实例标识,确保启动恢复时仅重新入队属于该实例的任务。
|
||
- **自定义 Worker ID**:若需显式指定标识符,可设置 `SHUMAI_WORKERS_ID`(或 `SHUMAI_WORKER_ID`)。
|
||
- **Kubernetes 环境**:在 Kubernetes Pod 中,可通过 Downward API(`fieldRef: { fieldPath: metadata.name }`)设置 `POD_NAME`,以在 Pod 重启期间保持稳定且唯一的单 Pod 身份标识。
|
||
|
||
使用智能体运行器时,每个数据库只允许运行一个主服务器。已配置运行器时,请先停止旧主服务器,再启动替换实例。在 Kubernetes 中,主服务器应使用单副本和 Recreate 部署策略。转码 Worker 仍可独立扩展。
|
||
|
||
---
|
||
|
||
## 基于 Kubernetes 与 AWS EKS 的弹性扩展部署
|
||
|
||
对于需要高吞吐媒体处理能力的生产级云端部署,Shumai 可部署在 Kubernetes 或 **AWS Elastic Kubernetes Service (AWS EKS)** 上,并借助 **KEDA (Kubernetes Event-driven Autoscaling)** 实现基于队列驱动的缩容至零(Scale-to-Zero)自动弹性伸缩。
|
||
|
||
```mermaid
|
||
graph TD
|
||
User([用户 / Web 浏览器]) -->|端口 80/3000| Server[Pod: shumai-server<br/>SHUMAI_WORKERS=agent]
|
||
Server -->|入队到 transcode_queue| DB[(PostgreSQL: pgvector18<br/>dbos.workflow_status)]
|
||
Server -->|直传 / 播放代理流| Storage[(S3 / Garage 存储)]
|
||
|
||
KEDA[KEDA ScaledJob<br/>PostgreSQL 触发器<br/>min: 0, max: 10] -.->|监控队列| DB
|
||
KEDA -->|为队列派发任务| Job1[Job: shumai-transcode-1<br/>自动排空 Worker]
|
||
KEDA -->|为队列派发任务| JobN[Job: shumai-transcode-N<br/>自动排空 Worker]
|
||
|
||
Job1 -->|获取源文件 / 存储代理文件| Storage
|
||
JobN -->|获取源文件 / 存储代理文件| Storage
|
||
Job1 -->|标记完成并退出 0| DB
|
||
JobN -->|标记完成并退出 0| DB
|
||
|
||
CA[Cluster Autoscaler / Karpenter] -.->|缩容至零按需节点<br/>0 到 10 实例| JobN
|
||
```
|
||
|
||
### 架构核心优势
|
||
|
||
- **解耦的无状态 Worker**:核心 Web 与 API 服务、数据库以及对象存储均运行在可靠的按需计算节点上(`c9g.large`,`SHUMAI_WORKERS=agent`),媒体转码任务则委派给由 PostgreSQL 中 DBOS 任务队列统一编排的后台 Worker。
|
||
- **专用 Graviton5 按需计算实例 (`c9g.xlarge`)**:媒体编码运行在 4 vCPU / 8 GiB 内存的 AWS Graviton5 按需实例上(约 0.174 美元/小时),充分利用 ARM64 向量优化与高速 DDR5 内存,且免受竞价实例(Spot)非预期中断的影响。
|
||
- **基于 KEDA 的队列驱动缩容至零**:KEDA 持续监听 `dbos.workflow_status` 中已入队与待处理的转码任务,并动态创建 Kubernetes `ScaledJob` 资源(支持 0 到 10 弹性伸缩)。当队列排空时,转码节点完全缩容至零(`minSize: 0`),转码计算成本降至 **0 美元/小时**。
|
||
- **空闲超时自动排空**:Worker Pod 以并发数 `1` 持续处理排队任务。当队列彻底排空且 Pod 持续空闲 10 秒(`SHUMAI_WORKER_IDLE_TIMEOUT_MS=10000`)后,Pod 将以状态码 `0` 正常退出以触发节点缩容,在批量上传时避免了 Pod 频繁冷启动的开销。
|
||
- **停滞任务自动恢复**:核心 Web 服务器运行内置的恢复巡检机制,可自动检测停滞或孤儿任务(例如因节点崩溃导致的任务中断)并在 DBOS 中自动恢复执行,同时设有最多 3 次重试上限以安全防范毒丸异常素材(Poison-Pill Media)。
|
||
|
||
### 完整部署示例与源码
|
||
|
||
生产就绪的完整清单文件、声明式 `eksctl` 集群配置以及分步操作指引,请参阅 Shumai 仓库中的 **[EKS 部署示例](https://github.com/shumaiOne/shumai/tree/main/eks)**:
|
||
|
||
👉 **[在 GitHub 上查看 EKS 部署指南与清单文件](https://github.com/shumaiOne/shumai/tree/main/eks)**
|
||
|
||
仓库包含:
|
||
|
||
- [`eks/eks-cluster.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/eks-cluster.yaml):包含分层计算配置的完整 `eksctl` ClusterConfig。
|
||
- [`eks/kustomization.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/kustomization.yaml):用于所有服务的一键式 Kustomize 部署文件。
|
||
- 详细说明了如何配置公网端点、自动化 Cluster Autoscaler 以及零停机平滑停机(Graceful Shutdown)。
|