部署模式¶

plaita 的部署形态分四档，由低到高：本地单机（SQLite）→ 单机标准（Redis）→ 分布式（Redis 多实例），外加 SDK 嵌入（不作为独立部署，而是把引擎当库用）。四档共用同一套流程定义与编排台，逐档平滑升级、不必推倒重来。

总览¶

	① 本地单机	② 单机标准	③ 分布式	SDK 嵌入
外部依赖	无	Redis 5+	Redis 5+（可多机）	无
流程执行	console 进程内	flow_worker（console 拉起）	多实例 worker 水平扩容	你的进程内
执行历史	SQLite	Redis	Redis	内存/自选存储
画布试跑 + pin 调试	✅	✅	✅	—
RBAC / 审计 / 凭据	✅	✅	✅	—
集群管理 / 队列 / 事件	❌	✅	✅	—
定时触发器（cron）	✅ 内置调度循环	✅ schedule_service	✅	—
执行日志查看	✅ SQLite	✅ Redis Stream	✅	—
挂起-恢复（审批/事件）	✅ 单进程	✅	✅	✅（配 EventBus）
适用场景	个人试用 / 演示 / 轻量自动化	团队共享编排台	生产规模 / 高可用	把编排嵌进你的应用

* 本地单机档的挂起-恢复运行在 console 单进程内：checkpoint 存 SQLite，重启后仍可显式恢复；但进程内事件订阅会随重启丢失，且 resume 必须走同一个 console 进程。多实例/跨进程的审批恢复请升到 Redis 档。

① 本地单机（SQLite）—— 零依赖起步¶

一条命令可用，不需要 Redis、不需要 worker：

pip install plaita-console
python -m plaita_console

console 启动时探测 Redis 不可达，即自动进入本档（local_mode）：

流程在 console 进程内的后台线程执行，执行记录与节点级 trace 存 SQLite（local_executions 表）
首次启动自动进入「创建管理员」向导；RBAC、审计、凭据、试跑调试全部可用
发布/删除只写 SQLite，跳过引擎同步

边界（对应页面会明确提示 503）：

集群管理 / 任务队列 / 事件管理不可用
挂起-恢复为单进程语义（见上表注）
单进程执行，无水平扩展；cancel 为尽力而为（标记状态，不中断线程）
local_mode 在启动时判定：运行中 Redis 掉线不会自动切换档位，需重启 console
定时触发器由 console 内置调度循环承担（cron 语义与集群档一致），但无队列持久化：console 进程退出时进行中的本地执行会丢失
本地调度只写入 SQLite（local_schedules）。以集群档启动（或运行中切到集群）时不启动本地调度循环：遗留条目保留原样但不会执行、也不在集群调度列表中显示。切回本地档可继续使用；要在集群档长期运行，请按相同 cron 在集群档重建后删除本地条目

升级到 ②：装好 Redis → 重启 console → 完成。已有流程定义在 SQLite 里继续有效，发布开始同步到引擎。

② 单机标准（Redis）—— 团队共享编排台¶

在 ① 的基础上加 Redis，即可获得完整能力：

# Redis 就绪后重启 console，即退出本地单机模式
PLAITA_CONSOLE_ADMIN_API_KEY=<服务账号密钥> PLAITA_CONSOLE_ENV=prod \
  plaita-console

发布的流程同步到引擎存储（plaita:flow:{id}:{version}），「集群」页可一键拉起 flow_worker / 调度 / 事件服务等实例（模板见 cluster_config.yaml）
挂起-恢复、审批、延迟任务全部生效；执行历史与实时流（SSE）来自 Redis
拉起的 worker 自动带上凭据文件与密钥环境

基础设施可用 console「集群」页的容器化生命周期一键拉起（Redis/PostgreSQL），或自备。生产建议再设置 PLAITA_CONSOLE_ADMIN_API_KEY（服务账号）并关闭 ALLOW_INSECURE_ADMIN。

Docker / compose 部署¶

plaita-console/docker/ 提供三套 compose 与一个可选叠加文件，按需组合：

文件	内容	用法
`docker-compose.yml`	Redis + backend + frontend + flow-worker	`docker compose up -d`
`docker-compose.dev.yml`	开发档（高位端口 18080/15173/16379）	`docker compose -f docker-compose.dev.yml up -d`
`docker-compose.deps.yml`	仅 Redis（`127.0.0.1:6379`）	`docker compose -f docker-compose.deps.yml up -d`
`docker-compose.redis-commander.yml`	可选 Redis 调试 UI	见下

必填环境变量：docker-compose.yml 里的 change-me-* 只是本地模板默认值；共享/生产环境必须覆盖 PLAITA_CONSOLE_ADMIN_API_KEY、 PLAITA_CONSOLE_SECRET_ID、PLAITA_CONSOLE_SECRET_KEY（空密钥时管理 API 与契约接口 fail-closed）。仓库根目录提供 .env.example 样例：cp .env.example plaita-console/docker/.env 后填写三个必填项再 docker compose up -d；也可以 docker compose --env-file .env -f plaita-console/docker/docker-compose.yml up -d。全部变量的默认值与失败形态见分布式 runbook 的「环境变量参考」。集群页的 PostgreSQL/MySQL 模板不再内置固定口令：在 console 进程环境设置 PLAITA_POSTGRES_PASSWORD（PostgreSQL）或 PLAITA_MYSQL_PASSWORD + PLAITA_MYSQL_ROOT_PASSWORD（MySQL）， cluster_config.yaml 里写 ${PLAITA_POSTGRES_PASSWORD} 等引用；变量缺失时「启动」返回可操作错误，不会把字面量当口令传给容器。

端口边界：基础设施模板只绑 127.0.0.1（数据库/队列不暴露到局域网），数据持久化到 named volume（plaita_pg_data / plaita_mysql_data / plaita_redis_data）。docker-compose.yml 的控制台/前端端口仍绑定所有接口，生产请放在反向代理或内网之后。

Redis Commander（可选调试 UI）默认不启动——它能对 Redis 执行任意命令。启用时必须提供 HTTP 基本认证：

REDIS_COMMANDER_USER=admin REDIS_COMMANDER_PASSWORD='<strong-random>' \
  docker compose -f docker-compose.deps.yml \
                 -f docker-compose.redis-commander.yml up -d redis-commander

集群服务镜像：仓库不构建也不发布 plaita/* 服务镜像，console 也不会隐式 docker pull。Docker 模式下需先在目标机构建/拉取镜像，并在 cluster_config.yaml 的 services.<name>.docker.image 显式填写；未配置或本地不存在时「启动」直接返回可操作错误（避免从不可控命名空间拉取 latest）。 console backend 镜像不包含前端产物（compose 里由 nginx 容器托管 SPA）；发布到 PyPI 的 console wheel 才通过 build_package.sh 把 webDist 打进包。

③ 分布式（Redis 多实例）—— 生产规模¶

在 ② 之上把 worker 与外延服务扩到多实例/多机：

worker 命令：python -m plaita.server.flow_worker（集群页或进程管理器拉起）
多实例消费同一 Stream（consumer group），resume 租约防并发恢复，超限进 DLQ
事件恢复（event_filter）、延迟（delay_service）、回调（http_callback_service）按需独立扩容

运维细节（Stream 迁移、租约、DLQ、故障处理）见分布式运维 Runbook。

SDK 嵌入 —— 不部署编排台¶

只要引擎不要界面：

pip install plaita

from plaita.core.flow import Flow
from plaita.core.executor import FlowExecution

flow = Flow.model_validate(definition)
result = FlowExecution().run_compatible(flow, False, **params)

默认 memory 存储 + InMemoryEventBus；需要跨进程时换 Redis 实现（见断点续执总览）。编排台（①②③）只是引擎之上的可选控制面。

各档共同的账号体系¶

四档中只要跑编排台，账号与审计行为一致：users / sessions / audit_logs / credentials 都在 console 的 SQLite 中（与 Redis 无关）；X-Admin-API-Key 服务账号在 ②③ 档同等可用。

选型速查¶

「我想看看这是什么」→ ①，两分钟出画面
「团队要共用一个编排台」→ ②
「执行量大 / 要高可用 / 挂起流程多」→ ③
「我只想在自己的 Python 服务里编排」→ SDK 嵌入