# Kestra 正式部署架构设计

更新时间：2026-06-02
状态：设计草案；未执行 NAS 常驻部署

## 1. 设计结论

基于本地 POC，推荐采用：

```text
Kestra = 跨机器流程状态机 / 进度 UI / 触发器 / 审计层
Hermes = 用户意图理解 / 安全治理 / profile 选择 / 输出验收 / NAS 写入确认
OpenClaw = 受控执行 worker
Hermes Kanban = Bot1 同机多 profile 持久任务板
```

Kestra 不替代 Hermes，也不替代 Hermes Kanban。正式架构应把 Kestra 放在跨系统编排层，负责“哪一步在跑、卡在哪、能否重试”，而不是负责 agent 的人格、长期记忆、业务判断或 NAS 安全策略。

## 2. 官方资料约束

官方资料确认：

- Kestra 开源版支持 PostgreSQL/MySQL 作为 queue/repository；
- Standalone server 官方最低建议约 4 GiB memory / 2 vCPU；
- Kestra 由 Webserver、Scheduler、Executor、Worker、Repository、Queue、Internal Storage 等组成；
- Open Source 版本现在强制 Basic Auth，`enabled: false` 会被忽略；
- `SECRET` 类型需要配置 `kestra.encryption.secret-key` 才能加密落库；
- Docker Compose + PostgreSQL 是官方推荐起步方式。

## 3. 推荐部署拓扑

### 方案 A：NAS 上跑 Kestra + PostgreSQL，Bot1/Bot2 跑 Bridge

```text
UGREEN NAS Docker
  ├─ kestra-server  : UI/API/Scheduler/Executor/Worker
  └─ kestra-postgres: Kestra repository/queue DB

Bot1
  ├─ hermes profiles
  ├─ openclaw gateway
  └─ kestra-agent-bridge-bot1 : 受控 HTTPS/内网 API

Bot2
  ├─ hermes profiles
  └─ kestra-agent-bridge-bot2 : 受控 HTTPS/内网 API
```

优点：

- 中央 UI 和 execution history 在 NAS；
- Bot1/Bot2 只提供受控执行接口；
- 用户可以在一个面板看跨机器任务进度；
- 便于以后加定时任务、webhook、审批暂停点。

缺点/风险：

- NAS Docker 管理方式需要确认；
- NAS 容器日志和 DB 会持久化 execution 信息，必须脱敏；
- Kestra UI 认证和网络边界必须做好；
- Bridge 不能裸奔，需要 token/mTLS/内网 ACL；
- 不应让 NAS 上的 Kestra 容器直接拿 Bot1/Bot2 的 Hermes auth 文件。

### 方案 B：Bot1 常驻 Kestra，NAS 只存项目文档/不跑服务

```text
Bot1
  ├─ kestra-server + postgres
  ├─ hermes profiles
  ├─ openclaw gateway
  └─ bridge local

Bot2
  └─ remote bridge / SSH
```

优点：

- 和 POC 最接近，改动少；
- 不需要立刻动 NAS Docker；
- 本机调用 Bot1 Hermes/OpenClaw 最简单；
- 适合继续打磨 flow 和 bridge。

缺点：

- Bot1 关机/重启会影响 Kestra；
- 跨机器中心化程度不如 NAS；
- 需要额外考虑 LaunchAgent/常驻服务，用户明确批准前不能做。

### 方案 C：只保留 Hermes Kanban，不上 Kestra

适合只做 Bot1 本机 profile 协作。当前需求包含 Bot1/Bot2/OpenClaw 跨系统状态和 UI，因此不作为推荐主方案。

## 4. 推荐选择

推荐短期走：

```text
继续在 Bot1 保留临时 POC → 做 Bridge/Flow 标准化 → 再决定 NAS 常驻
```

推荐中期目标是方案 A，但不要直接从 POC 迁移到 NAS 常驻。正式部署前需要先完成：

1. Bridge 鉴权；
2. Flow 模板标准化；
3. 日志脱敏；
4. Kestra 镜像来源固定；
5. NAS Docker 部署和数据卷方案；
6. UI 访问控制；
7. 停止/备份/恢复流程。

## 5. 正式部署组件

### Kestra Server

- 运行模式：先 standalone；后续高负载再拆 Webserver/Scheduler/Executor/Worker。
- 镜像：优先官方 `kestra/kestra`，正式环境不要长期依赖非官方镜像源。
- 端口：
  - `8080` UI/API，仅内网或反代认证；
  - `8081` management/health，不应公网开放。

### PostgreSQL

- 使用 Docker named volume 或 NAS 容器平台自己的 volume；
- 不把 PostgreSQL data directory 放 SMB 挂载目录；
- 可考虑复用 NAS PostgreSQL 服务，但建议独立 database/schema/user；
- 配置备份。

### Internal Storage

- 起步用 local volume；
- 不存大 prompt/raw artifact；
- 后续如 flow 输出变大，可考虑 MinIO/S3 风格对象存储。

### Bridge

- Bot1/Bot2 各自运行独立 bridge；
- Bridge 只暴露固定 endpoint；
- 每个 endpoint 只执行固定 wrapper，不接受自由 shell；
- 必须鉴权；
- 返回结构化 JSON；
- stdout/stderr 脱敏；
- 超时、并发、速率限制。

## 6. 网络建议

最低安全版本：

```text
Kestra UI/API：内网-only
Bridge：内网-only + token
Management 8081：仅容器内/localhost
```

如果要外部访问 UI：

- 反向代理；
- HTTPS；
- Basic Auth 或更强认证；
- 不暴露 management 端口；
- 禁止未认证访问 `/api/`。

## 7. 数据和日志边界

Kestra 会持久化 execution metadata 和 task output。正式 flow 要避免写入：

- secrets；
- OAuth token；
- `.env` 值；
- `auth.json`；
- Feishu app secret；
- NAS 密码；
- 用户私密大段聊天；
- 未脱敏命令输出。

允许写入：

- execution id；
- flow id；
- profile 名；
- task 状态；
- 文件路径；
- 文件大小；
- 校验结果；
- 脱敏摘要。

## 8. 与 Hermes Kanban 的分工

| 场景 | 推荐系统 |
|---|---|
| Bot1 同机多 profile 协作 | Hermes Kanban |
| Bot1 短工具噪音任务 | `delegate_task` |
| 指定一个 Hermes profile 执行 | profile delegation / wrapper |
| Bot1 + Bot2 + OpenClaw 跨系统流程 | Kestra |
| 需要用户审批/暂停/重试的跨系统流程 | Kestra |
| 需要 Hermes 业务判断和最终验收 | Hermes IT |

## 9. 正式上线前置确认项

正式部署到 NAS 前，需要用户确认：

1. 是否允许在 NAS Docker 中创建 Kestra/PostgreSQL 容器；
2. 具体镜像来源；
3. 具体 volume 名称/路径；
4. 端口映射；
5. UI 访问方式；
6. Basic Auth/认证策略；
7. Bridge token 管理方式；
8. 是否允许 Bot1/Bot2 bridge 常驻；
9. 是否需要定期备份 PostgreSQL 和 flow definitions；
10. 是否允许某些 flow 触发 Feishu 通知。

## 10. 当前建议动作

下一阶段不直接 NAS 常驻，而是先做：

1. Bridge v1 规范；
2. Flow 模板库；
3. 一个真实但低风险的跨系统流程，例如“Bot1 计划 → Bot2 执行 ping/摘要 → OpenClaw 状态检查 → Hermes 汇总”。

等标准化跑稳后，再迁移到 NAS 常驻。