跳到主要内容

SkillFlaw 部署架构

SkillFlaw 支持两种主要部署形态：

  1. 编辑器部署：同时运行后端 API 与前端 UI，让团队可以在产品界面中构建、调试和运维流程。
  2. API 优先部署：只运行后端服务用于程序化访问；如果环境确实需要 UI，再额外加上前端和文档服务。

在 Kubernetes 上，这两种形态都应基于项目既有的容器镜像与运行时配置进行装配。当前 SkillFlaw 并未提供官方 Kubernetes Helm Chart，因此本节 Kubernetes 指南都以 manifest 方式部署为主，并复用 GHCR 发布镜像以及 docker/docker-compose.yml 中已经使用的环境变量契约。

核心组成模块​

一个典型的 SkillFlaw 部署通常包含以下服务：

  • Backend API：ghcr.io/cwinux/skillflaw_backend:latest
    • 在 7860 端口提供 REST API
    • 通过 /health 提供健康检查
    • 通过 /api/v1/run/{flow_id}、/api/v1/responses 等端点执行流程
  • Frontend UI：ghcr.io/cwinux/skillflaw_frontend:latest
    • 提供 Web 应用界面
  • Documentation site：ghcr.io/cwinux/skillflaw_docs:latest
    • 当你希望文档以独立主机或独立服务形式存在时，可选启用
  • PostgreSQL
    • 用于持久化应用数据，属于必需依赖
  • Redis
    • 当 SKILLFLAW_CACHE_TYPE=redis 时使用
  • 持久化存储
    • 用于 SKILLFLAW_CONFIG_DIR 以及其他你不希望因 Pod 重建而丢失的运行时状态

源码、容器与 Kubernetes 交付方式​

源码部署​

源码部署更适合本地开发与快速调试。

  • 执行 make init
  • 用 make init_db 初始化数据库
  • 用 make backend 启动后端
  • 用 make frontend 启动前端
  • 用 make docs 或 make docs_build 构建文档

这里有一个很重要的实现细节：源码部署时，后端会从 src/backend/base/skillflaw/frontend 提供前端静态资源，因此任何基于源码的 UI 发布，都必须先执行 make build_frontend，或者执行包含它的命令，例如 make run_cli。

容器部署​

项目在 docker/docker-compose.yml 中提供了基于 compose 的参考部署。

该栈会启动：

  • backend
  • frontend
  • doc
  • pgsql
  • redis

默认本地访问地址：

  • 前端：http://localhost:3001
  • 后端健康检查：http://localhost:7860/health
  • 文档：http://localhost:3002

Kubernetes 部署​

Kubernetes 应该复用同样的服务边界，而不是重新发明一套不同的运行契约：

  • backend Pod 使用与 compose 相同的环境变量
  • frontend Pod 通过 BACKEND_URL 指向 backend Service
  • docs 在需要时应作为独立文档服务部署
  • PostgreSQL 和 Redis 可以部署在集群内，也可以在生产环境中使用托管服务

推荐的环境划分​

开发与内部测试环境​

当团队需要以下能力时，建议部署完整编辑器形态：

  • 在 UI 中设计或编辑流程
  • 使用管理页面
  • 通过浏览器验证端到端交互
  • 从同一集群中访问文档

这类环境通常会包含 backend、frontend、PostgreSQL、Redis，以及可选的独立 docs 服务。

生产服务环境​

如果集群主要用来给应用程序提供已经管理好的流程服务，则建议采用 API 优先形态。

典型生产流量包括：

  • /api/v1/run/{flow_id_or_alias}
  • /api/v1/responses
  • /api/v1/mcp/streamable

如果该环境并不需要 Web UI，就只公开后端，把 frontend/docs 留在非公网路径中。

路由模式​

建议使用明确的服务边界进行公网路由：

  • 应用 UI 使用应用域名，例如 app.example.com
  • backend API 使用接口域名，例如 api.example.com
  • docs 使用文档域名，例如 docs.example.com

文档站应始终挂载在 docs 服务的根路径 /，而不是作为 frontend 的子路径存在。

仅后端模式​

对于源码运行和 CLI 场景，后端支持通过运行时入口与相关环境变量进入仅后端模式。

如果你就是想要无界面的 API 进程，可以使用这个模式；但它应被视为一种部署选择，而不是兼容兜底。在容器化环境里，更清晰的模式通常是：如果不需要 UI，就只部署 backend 镜像。

各环境都必须保持一致的契约​

无论部署在哪个平台，这些基础契约都应保持稳定：

  • backend 监听 7860 端口
  • frontend 通过 BACKEND_URL 访问 backend
  • SKILLFLAW_SECRET_KEY_FILE 挂载为真实文件，而不是写死进镜像
  • SKILLFLAW_CONFIG_DIR 指向可写的持久化存储
  • PostgreSQL 与 Redis 连接设置明确且与环境绑定

下一步​