跳到主要内容

在 Kubernetes 上部署 SkillFlaw 开发环境

当你的集群需要为开发者、测试人员或内部用户提供完整的 SkillFlaw 编辑器体验时，请使用这种部署形态。

本指南刻意对齐项目现有部署契约，而不是依赖外部 Helm Chart：

  • backend 镜像：ghcr.io/cwinux/skillflaw_backend:latest
  • frontend 镜像：ghcr.io/cwinux/skillflaw_frontend:latest
  • 可选 docs 镜像：ghcr.io/cwinux/skillflaw_docs:latest
  • 有状态依赖：PostgreSQL 与 Redis

何时使用这个拓扑​

当你希望同一个环境同时提供以下能力时，请选择开发环境拓扑：

  • 浏览器编辑器与管理 UI
  • backend API
  • 用于内部协作测试的共享状态
  • 可选的独立 docs 站访问

如果只是纯程序化服务，不需要 frontend，请直接使用生产环境指南中的 API 优先形态。

前置条件​

  • 一个 Kubernetes 集群
  • kubectl
  • 能够从 ghcr.io 拉取镜像
  • PostgreSQL 与 Redis 的方案：可以集群内，也可以外部托管
  • 为 SKILLFLAW_CONFIG_DIR 准备好可写持久卷

推荐服务布局​

对于内部开发或 UAT 环境，最简单的集群布局通常是：

  • backend 服务，端口 7860
  • frontend 服务，端口 80
  • docs 服务，端口 80，仅在你需要独立文档主机或独立文档服务时启用
  • postgresql 服务
  • redis 服务

frontend 镜像只提供应用 UI。如果该环境需要对外或对内共享文档访问，请单独部署 docs 镜像。

1. 创建命名空间、配置与密钥​

参考 compose 文件已经给出了最小环境契约。到了 Kubernetes 中，请复用这套契约，而不是重新发明第二套配置模型。


_29
apiVersion: v1
_29
kind: Namespace
_29
metadata:
_29
name: skillflaw
_29
---
_29
apiVersion: v1
_29
kind: ConfigMap
_29
metadata:
_29
name: skillflaw-backend-config
_29
namespace: skillflaw
_29
data:
_29
SKILLFLAW_CONFIG_DIR: /var/lib/skillflaw
_29
SKILLFLAW_DATABASE_URL: postgresql://skillflaw:skillflaw@postgresql:5432/skillflaw
_29
SKILLFLAW_CONFIG_MODEL: local
_29
SKILLFLAW_CACHE_TYPE: redis
_29
SKILLFLAW_REDIS_HOST: redis
_29
SKILLFLAW_REDIS_PORT: "6379"
_29
SKILLFLAW_HOST: 0.0.0.0
_29
SKILLFLAW_PORT: "7860"
_29
SKILLFLAW_OPEN_BROWSER: "false"
_29
---
_29
apiVersion: v1
_29
kind: Secret
_29
metadata:
_29
name: skillflaw-runtime-secrets
_29
namespace: skillflaw
_29
type: Opaque
_29
stringData:
_29
skillflaw_secret_key: replace-with-your-secret-key-file-content

请将 secret 挂载为文件，并让 SKILLFLAW_SECRET_KEY_FILE 指向那个文件路径。

2. 部署 PostgreSQL 与 Redis​

对于短生命周期的本地集群实验，集群内 PostgreSQL 与 Redis 是可以接受的。

但对于任何共享内部环境，建议至少做到：

  • PostgreSQL 使用持久化存储
  • 有明确备份策略
  • Redis 部署具有可预期的内存限制

你可以使用 chart、operator 或托管服务。关键点在于：backend 最终收到的连接配置仍应与上文示例一致。

3. 部署 backend​

backend 镜像暴露 7860 端口，并通过 /health 提供健康检查。


_61
apiVersion: apps/v1
_61
kind: Deployment
_61
metadata:
_61
name: skillflaw-backend
_61
namespace: skillflaw
_61
spec:
_61
replicas: 1
_61
selector:
_61
matchLabels:
_61
app: skillflaw-backend
_61
template:
_61
metadata:
_61
labels:
_61
app: skillflaw-backend
_61
spec:
_61
containers:
_61
- name: backend
_61
image: ghcr.io/cwinux/skillflaw_backend:latest
_61
ports:
_61
- containerPort: 7860
_61
envFrom:
_61
- configMapRef:
_61
name: skillflaw-backend-config
_61
env:
_61
- name: SKILLFLAW_SECRET_KEY_FILE
_61
value: /run/secrets/skillflaw_secret_key
_61
volumeMounts:
_61
- name: skillflaw-data
_61
mountPath: /var/lib/skillflaw
_61
- name: skillflaw-secret
_61
mountPath: /run/secrets/skillflaw_secret_key
_61
subPath: skillflaw_secret_key
_61
readOnly: true
_61
readinessProbe:
_61
httpGet:
_61
path: /health
_61
port: 7860
_61
livenessProbe:
_61
httpGet:
_61
path: /health
_61
port: 7860
_61
volumes:
_61
- name: skillflaw-data
_61
persistentVolumeClaim:
_61
claimName: skillflaw-backend-data
_61
- name: skillflaw-secret
_61
secret:
_61
secretName: skillflaw-runtime-secrets
_61
---
_61
apiVersion: v1
_61
kind: Service
_61
metadata:
_61
name: skillflaw-backend
_61
namespace: skillflaw
_61
spec:
_61
selector:
_61
app: skillflaw-backend
_61
ports:
_61
- name: http
_61
port: 7860
_61
targetPort: 7860

4. 部署 frontend​

frontend 依赖 BACKEND_URL，并负责提供应用 UI。在开发型集群中，这通常是用户的主入口。


_36
apiVersion: apps/v1
_36
kind: Deployment
_36
metadata:
_36
name: skillflaw-frontend
_36
namespace: skillflaw
_36
spec:
_36
replicas: 1
_36
selector:
_36
matchLabels:
_36
app: skillflaw-frontend
_36
template:
_36
metadata:
_36
labels:
_36
app: skillflaw-frontend
_36
spec:
_36
containers:
_36
- name: frontend
_36
image: ghcr.io/cwinux/skillflaw_frontend:latest
_36
env:
_36
- name: BACKEND_URL
_36
value: http://skillflaw-backend.skillflaw.svc.cluster.local:7860/
_36
ports:
_36
- containerPort: 80
_36
---
_36
apiVersion: v1
_36
kind: Service
_36
metadata:
_36
name: skillflaw-frontend
_36
namespace: skillflaw
_36
spec:
_36
selector:
_36
app: skillflaw-frontend
_36
ports:
_36
- name: http
_36
port: 80
_36
targetPort: 80

5. 可选：部署 docs​

如果该环境需要文档访问，请把 docs 镜像部署为独立服务，并通过专用 docs 域名对外暴露。


_33
apiVersion: apps/v1
_33
kind: Deployment
_33
metadata:
_33
name: skillflaw-docs
_33
namespace: skillflaw
_33
spec:
_33
replicas: 1
_33
selector:
_33
matchLabels:
_33
app: skillflaw-docs
_33
template:
_33
metadata:
_33
labels:
_33
app: skillflaw-docs
_33
spec:
_33
containers:
_33
- name: docs
_33
image: ghcr.io/cwinux/skillflaw_docs:latest
_33
ports:
_33
- containerPort: 80
_33
---
_33
apiVersion: v1
_33
kind: Service
_33
metadata:
_33
name: skillflaw-docs
_33
namespace: skillflaw
_33
spec:
_33
selector:
_33
app: skillflaw-docs
_33
ports:
_33
- name: http
_33
port: 80
_33
targetPort: 80

6. 通过 Ingress 或端口转发对外暴露​

为了快速验证，你可以先做端口转发：

  • skillflaw-backend → 7860
  • skillflaw-frontend → 8080 或其他本地端口

对于共享环境，可以配置如下入口规则：

  • app.example.com → skillflaw-frontend
  • api.example.com → skillflaw-backend
  • docs.example.com → skillflaw-docs（启用 docs 时）

7. 验证部署结果​

发布完成后，请至少确认：

  1. backend 的 /health 返回 200
  2. frontend 服务可以正常打开 UI
  3. 如果启用了 docs，docs 域名可以正常访问
  4. 编辑器可以通过 backend 触发真实流程运行

实用说明​

  • 除非 PostgreSQL、Redis 与共享存储都已经准备好支持多实例，否则 backend 副本建议保持为 1
  • Kubernetes 开发环境本质上是共享内部环境，不应把它当作规避配置纪律的捷径
  • 如果你是从源码而不是镜像部署，请记住后端提供的是 src/backend/base/skillflaw/frontend 中构建好的前端静态资源

另请参阅​