跳到主要内容

在 Railway 上部署 SkillFlaw

SkillFlaw 可以运行在 Railway 上，但并未提供官方的一键 Railway 模板。

理解 Railway 的正确方式应该是：它是一个通用容器平台，因此你的 Railway 部署应复用 docker/docker-compose.yml 中已经采用的同一套运行契约，而不是依赖某个外部模板自带的假设。

Railway 需要承载什么​

至少，一个运行在 Railway 上的 SkillFlaw 部署需要这些组成部分：

服务镜像 / 依赖说明
后端（backend）ghcr.io/cwinux/skillflaw_backend:latest必需
PostgreSQLRailway PostgreSQL 或其他托管 PostgreSQL必需
RedisRailway Redis 或其他托管 Redis当使用 SKILLFLAW_CACHE_TYPE=redis 时必需
持久化存储Railway volume 或等价方案SKILLFLAW_CONFIG_DIR 必需
Secret 文件挂载你的部署方式必须提供 SKILLFLAW_SECRET_KEY_FILE 所需真实文件必需
前端（frontend）ghcr.io/cwinux/skillflaw_frontend:latest如果需要 Web UI，则可选
文档站（docs）ghcr.io/cwinux/skillflaw_docs:latest可选

先决定部署形态​

请有意识地选择：

  • API 优先：后端 + PostgreSQL + Redis
  • 完整 Web 部署：再增加前端
  • 文档暴露：只有当你也要在 Railway 上公开文档站时，才增加 docs 服务

不要因为 Railway 能运行它们，就把所有服务都加上。

后端（backend）的运行契约​

后端服务应保持与既有运行契约一致的设置与语义。

至少要确保 Railway 为后端提供以下变量：

  • SKILLFLAW_DATABASE_URL
  • SKILLFLAW_CACHE_TYPE=redis
  • SKILLFLAW_REDIS_HOST
  • SKILLFLAW_REDIS_PORT
  • SKILLFLAW_CONFIG_DIR
  • SKILLFLAW_SECRET_KEY_FILE
  • SKILLFLAW_HOST=0.0.0.0
  • SKILLFLAW_PORT=7860

后端的健康检查地址仍然是 /health。

重要：SKILLFLAW_SECRET_KEY_FILE 依然必须是文件​

SkillFlaw 的部署契约要求 SKILLFLAW_SECRET_KEY_FILE 指向真实文件。

如果你的 Railway 方案无法提供稳定的文件型 secret 路径，不要假装这个要求已经消失。先解决运行时文件需求，再继续部署；否则请换一个更适合该契约的平台。

前端（frontend）的运行契约​

如果你部署前端镜像，则需要设置：

  • BACKEND_URL：指向 Railway 环境中前端应访问的后端地址

前端应聚焦于提供 UI。后端 API 流量仍应终止在后端服务上；如果文档站需要公开，也可以保持独立。

建议的发布顺序​

  1. 先创建 PostgreSQL 与 Redis 服务。
  2. 部署后端镜像，并确认 GET /health 成功。
  3. 为 SKILLFLAW_CONFIG_DIR 挂载持久化存储。
  4. 提供 SKILLFLAW_SECRET_KEY_FILE 所需的 secret key 文件。
  5. 只有在后端已经健康后，才增加前端服务（若你确实需要浏览器 UI）。
  6. 只有在 Railway 环境也要公开文档时，才增加文档站服务。

验证部署结果​

请验证你真正要支持的那些公网能力：

  • 后端健康检查：/health
  • API 流量：/api/v1/run/{flow_id} 或 /api/v1/responses
  • MCP 流量：/api/v1/mcp/streamable
  • 前端 UI（如果已部署）
  • 文档站（如果已部署）

本页不承诺什么​

本页刻意不提供一键按钮、自动生成模板仓库，或 Railway 专用兼容层，因为这些内容都不属于当前维护的部署路径。

如果你想要首选部署参考，请阅读：