跳到主要内容

SkillFlaw 在 Kubernetes 上的生产最佳实践

本指南说明在 Kubernetes 上更安全、更稳定地运行 SkillFlaw 的生产运维实践。

选择与真实场景匹配的最小拓扑​

部署拓扑应以实际所需的服务能力为依据，而不是以仓库中是否提供镜像为依据。

请有意识地在以下模式中做选择：

  • API 优先生产：backend + PostgreSQL + Redis
  • 完整 Web 生产：backend + frontend + PostgreSQL + Redis
  • 公开文档：只有在确实需要时，才额外增加 docs 服务

把拓扑定义得清楚，扩缩容、安全审查与故障处理都会容易得多。

扩容前先把状态外置​

只有当状态不再绑定在单个 Pod 本地时，水平扩容才会真正可靠。

在提高后端（backend）副本数前，请确认以下条件都成立：

  • SKILLFLAW_DATABASE_URL 指向真实可用的 PostgreSQL 服务
  • SKILLFLAW_CACHE_TYPE=redis 背后是可达的 Redis 部署
  • SKILLFLAW_CONFIG_DIR 已挂载到持久化存储
  • SKILLFLAW_SECRET_KEY_FILE 已通过 Secret 支持的文件方式挂载

其中任何一项仍然是 Pod 本地状态，都应先修复再扩容。

后端与前端分开扩缩容​

后端（backend）与前端（frontend）的扩缩容行为完全不同。

后端（backend）​

后端承担了流程执行、API 流量，以及大部分运维风险。

扩容后端时应依据：

  • 请求并发量
  • 流程复杂度
  • 文件上传或大负载请求压力
  • 高峰期排队或延迟情况

建议先设置明确的资源 requests，观察真实负载，再决定是否增加副本或 CPU / 内存。

前端（frontend）​

前端是无状态服务，通常扩容成本更低。

它主要因以下场景扩容：

  • 并发浏览器用户增多
  • 高峰期页面加载变慢
  • 希望与 backend 的发布节奏解耦

除非你已经测量出真实需求，否则不要把前端副本数和后端副本数强行绑定。

把 PostgreSQL 当作一等生产依赖​

在 SkillFlaw 的生产环境里，PostgreSQL 不是附属件，而是运行契约的核心部分。

建议至少做到：

  • 持久化存储
  • 备份与恢复流程
  • 可控的 schema 迁移方式
  • 连接监控与告警
  • 如果你运行高可用 PostgreSQL，要有明确的故障切换方案

如果你准备运行多个后端副本，数据库与存储策略必须先支撑这种形态。

有意识地使用 Redis​

如果启用了 Redis 缓存，就要把 Redis 当成受管依赖来运行，并明确它的内存与持久化策略。

缓存行为必须具备可观测性。缺乏监控与边界控制的 Redis 配置，往往会成为生产环境中的不稳定因素。

保持路由语义不变​

当前 frontend 的 Nginx 配置已经支持这些行为：

  • / 提供应用 Shell
  • /chat 与 /flow/... 使用专门的 HTML fallback

当你增加入口规则时，请保留这些语义，而不是将所有路径统一收敛为通用 SPA 回退规则。

尤其是：

  • /api/ 流量应直接路由到 backend 服务
  • 当公开 API、公开 UI 与公开文档的受众不同，应优先使用独立主机名

加固密钥与配置边界​

请始终遵循以下原则：

  • API Key、数据库凭据和 secret key 文件都存放在 Kubernetes Secret 或外部 Secret 管理系统中
  • SKILLFLAW_SECRET_KEY_FILE 以文件形式挂载
  • 不要把环境相关的密钥烘焙进镜像
  • 通过网络策略限制 PostgreSQL 与 Redis 的可达范围
  • 对所有真实用户流量都在入口层启用 HTTPS / TLS

用类生产流量验证​

在上线前，不要只验证“Pod 能启动”。

至少应验证：

  • 对 /api/v1/run/{flow_id} 的真实鉴权请求
  • 若客户端依赖 OpenAI 兼容接口，则验证 /api/v1/responses
  • 若你公开了 MCP，则验证 /api/v1/mcp/streamable
  • 如果启用了 UI，则验证浏览器登录与流程执行
  • 如果 docs 需要公网访问，则验证 docs 域名是否可正常渲染

然后再做针对代表性流程的负载测试，而不是只跑几个 hello-world 健康检查。

区分源码部署与镜像部署纪律​

对于源码部署，请记住：前端文件必须重新构建到 src/backend/base/skillflaw/frontend。

对于镜像部署，请记住：对外文档应由独立的 docs 镜像提供。

混淆这两种模型，是把旧 UI 或旧文档带进生产环境的高发原因。

显式设计发布与回滚步骤​

每一次生产发布，你都应该能回答：

  • 当前部署的是哪个镜像标签
  • 哪些配置或 Secret 发生了变化
  • 如何回滚 backend
  • frontend 与 docs 是否应该一同回滚，还是保持固定版本

如果这些问题在发布前无法得到明确答案，则应补充相应的发布与回滚控制流程。

持续观察健康状态​

至少要收集并告警以下指标：

  • backend /health 失败
  • 容器重启
  • API 延迟与错误率
  • PostgreSQL 饱和或连接失败
  • Redis 连通性问题
  • ingress 4xx / 5xx 激增

强烈建议集中化日志，以便在事故处理中关联后端、入口层、数据库与 Redis 的事件。

另请参阅​