在 Kubernetes 上部署

用 kustomize 把控制台部进集群，以及 KubeRay 执行器依赖的那个 RWX 卷。

kubectl apply -k deploy/k8s/
kubectl -n starforge rollout status deploy/starforge-console

deploy/k8s/ 是一套 kustomize overlay，覆盖命名空间、配置、密钥、RBAC、Deployment、 Service、Ingress 和两个 PVC。

​

它会创建什么

清单	用途
namespace.yaml	starforge
configmap.yaml	非敏感的 FORGE_* 设置
secret.example.yaml	敏感设置——上生产前请替换来源
rbac.yaml	kuberay 执行器需要的 RayJob 权限。没有它下发会 403
deployment.yaml	单副本，/healthz 探针，CPU 250m–2，内存 512Mi–2Gi
service.yaml、ingress.yaml	集群内地址与外部路由
pvc.yaml	存储根的 PVC，加一个可选的本地 SQLite PVC

apply 之前先把镜像指向你的仓库：

deploy/k8s/kustomization.yaml

images:
  - name: registry.company.com/forge/starforge-console
    newTag: "0.3.0"

​

真正要紧的是那个存储卷

accessModes: [ReadWriteMany]
resources:
  requests:
    storage: 2Ti
storageClassName: nfs-client     # 必须是真的支持 RWX 的 StorageClass

ReadWriteMany 不是可选项，而 RWO 是静默失败的。 RWO 的 claim 不会报错—— Kubernetes 会给每个 Pod 各自一个卷。多节点作业于是把 checkpoint 分片散落在不同 Pod 上， 这次 run 再也续不了，而日志里没有任何东西说明原因。

执行器的健康检查会把 FORGE_K8S_STORAGE_SHARED 和 claim 的实际 accessModes 核对。 首次部署后去读那个结果，别想当然。

控制台把这个 claim 挂在 FORGE_STORAGE_ROOT 指定的那个路径上—— 它往 runs/<user>/<exp>/<run_id>/work 里放作业目录、测量磁盘压力、执行回收。 训练 Pod 挂载同一个 claim，所以控制台写的路径就是作业打开的路径。

容量按「权重缓存 + 数据集缓存 + 所有 run 目录」估。2Ti 是一个起点而不是建议值； 光是权重缓存，每个基座模型就是几十 GB。

​

推荐配置

deploy/k8s/configmap.yaml

FORGE_DEFAULT_FLEET_KIND: "kuberay"
FORGE_STORAGE_ROOT: "/starforge"
FORGE_K8S_STORAGE_PVC: "starforge-storage"
FORGE_K8S_STORAGE_SHARED: "true"
FORGE_PUBLIC_URL: "https://starforge.company.com"
FORGE_INGEST_URL: "http://starforge-console.starforge.svc.cluster.local"
FORGE_KUBERAY_RAY_VERSION: "2.55.1"
FORGE_K8S_SHM_SIZE: "64Gi"
FORGE_KUBERAY_PRERUNNING_DEADLINE_S: "1800"
FORGE_JOB_RUNNER_MODE: "bundled"
FORGE_QUOTA_ENFORCE: "1"

其中四项值得理解而不是照抄：

FORGE_INGEST_URL 用的是集群内服务名

训练 Pod 往它回传。用外部 ingress 地址会先出集群再绕回来；服务 DNS 名不会。 绝不能填 127.0.0.1——那是 worker 自己的回环。

FORGE_KUBERAY_RAY_VERSION 必须和训练镜像一致

不一致的症状是「集群起来了但 worker 注册不上」，而唯一的线索是一行很容易淹没在启动输出里的版本警告。

FORGE_K8S_SHM_SIZE，因为容器默认只有 64MB

Ray 的 object store 就在 /dev/shm 里。用默认值的话，稍大一点的 batch 立刻 OOM。 它由内存支撑，所以它加上内存上限不能超过物理内存。

FORGE_KUBERAY_PRERUNNING_DEADLINE_S 给卡住的作业一个上限

没有它，拉不到的镜像或者没有节点满足的 nodeSelector 会让作业无限期 Pending，同时一直占着队列位置。

​

密钥

secret.example.yaml 只是用来说明结构。上生产前请换成真实来源—— kubectl create secret、Sealed Secrets 或 External Secrets Operator—— 并把它从 kustomization.yaml 里移除。

至少要有：FORGE_WEB_JWT_SECRET、FORGE_DB_URL、FORGE_REDIS_URL、 FORGE_S3_SECRET_KEY、FORGE_SECRET_ENC_KEY，以及 OIDC 的 client secret。

​

副本数

清单里是单副本，这是安全的默认值。往上扩之前：

• FORGE_DB_URL 必须指向 Postgres。SQLite 是单写的
• FORGE_WEB_JWT_SECRET 必须固定，否则副本之间互相拒绝对方签的 token
• FORGE_REDIS_URL 必须配置，否则后台角色会整个停掉而不是跨副本不安全地跑—— 存储记账、诊断、看门狗和每日日报全都不再运行
• 把后台角色放进它自己的 Pod。设 FORGE_INPROCESS_WORKERS=0，再应用 worker Deployment——kustomize 路径下是 worker.yaml，Helm 下是 worker.enabled=true。诊断与日报的 tick 会调 LLM 并一次占住事件循环好几秒； 拆出去之后它们不再抬高 API 尾延迟，控制台副本也变成无状态的。副本数保持 1 是对的：每个角色都经 Redis 选主，第二个副本只会空转

​

确认成功

kubectl -n starforge get pods
kubectl -n starforge port-forward svc/starforge-console 8080:80
curl -s localhost:8080/api/version

然后看执行器自己的视角——它才能告诉你存储卷是不是真的 RWX：

curl -s localhost:8080/api/cluster/health | jq .storage