railway-new

新建项目／服务／数据库

通过适当的配置创建 Railway 项目、服务和数据库。

使用场景

• 用户说“部署到 Railway”（如果已关联，则添加服务；如果未关联，则初始化）
• 用户说“创建 Railway 项目”“初始化”“新建项目”（明确要新建项目）
• 用户说“关联到 Railway”“连接到 Railway”
• 用户说“创建服务”“添加后端”“新建 API 服务”
• 用户说“创建 Vite 应用”“创建 React 网站”“创建 Python API”
• 用户说“从 github.com/user/repo 部署”“从这个仓库创建服务”
• 用户说“添加 Postgres”“添加数据库”“添加 Redis”“添加 MySQL”“添加 Mongo”
• 用户说“连接到 Postgres”“接入数据库”“将我的 API 连接到 Redis”
• 用户说“添加 Postgres 并连接到服务器”
• 同时设置代码和 Railway 服务

先决条件

检查是否已安装 CLI：

command -v railway

如果尚未安装：

安装 Railway CLI：

npm install -g @railway/cli

或者

brew install railway

检查是否已完成身份验证：

railway whoami --json

如果尚未完成身份验证：

运行 railway login 进行身份验证。

决策流程

railway status --json (in current dir)
     │
┌────┴────┐
Linked    Not Linked
  │            │
  │       Check parent: cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    Parent      Not linked
  │    Linked      anywhere
  │       │            │
  │   Add service   railway list
  │   Set rootDir      │
  │   Deploy       ┌───┴───┐
  │       │      Match?  No match
  │       │        │        │
  │       │      Link    Init new
  └───────┴────────┴────────┘
           │
    User wants service?
           │
     ┌─────┴─────┐
    Yes         No
     │           │
Scaffold code   Done
     │
railway add --service
     │
Configure if needed
     │
Ready to deploy

检查当前状态

railway status --json

• 如果已关联：向现有项目添加服务（见下文）
• 如果未关联：检查父目录是否已关联（见下文）

已关联时

默认行为：“部署到 Railway”＝向已关联的项目添加服务。

除非用户明确表示以下意图，否则不要创建新项目：

• “新建项目”“创建项目”“初始化项目”
• “独立项目”“不同的项目”

“flappy-bird”或“my-api”这样的应用名称是服务名称，不是项目名称。

User: "create a vite app called foo and deploy to railway"
Project: Already linked to "my-project"

WRONG: railway init -n foo
RIGHT: railway add --service foo

关联父目录

Railway CLI 会沿目录树向上查找已关联的项目。如果当前位于子目录中：

cd .. && railway status --json

如果父目录已关联，则无需初始化或关联子目录。应改为：

1. 创建服务：railway add --service <name>
2. 通过环境技能将 rootDirectory 设置为子目录路径
3. 从根目录部署：railway up

如果没有父目录已关联，则继续执行初始化或关联流程。

初始化还是关联

如果已关联，则跳过本节——只需添加服务。

仅当没有项目已关联（包括通过父目录关联）时，才使用本节。

检查用户的项目

输出可能很长。请在子 Agent 中运行，并仅提取以下内容：

• 项目的 id 和 name
• 工作区的 id 和 name

railway list --json

决策逻辑

1. 用户明确表示“新建项目” → 使用 railway init
2. 用户指定了现有项目 → 使用 railway link
3. 目录名称与现有项目匹配 → 询问用户：关联现有项目还是创建新项目？
4. 没有匹配的项目 → 使用 railway init
5. 意图不明确 → 询问用户

创建新项目

railway init -n <name>

选项：

• -n, --name - 项目名称（在非交互模式下，如果省略则自动生成）
• -w, --workspace - 工作区名称或 ID（如果存在多个工作区，则为必填项）

多个工作区

如果用户有多个工作区，railway init 必须指定 --workspace 标志。

通过以下方式获取工作区 ID：

railway whoami --json

workspaces 数组包含每个工作区的 { id, name }。

根据用户输入推断工作区： 如果用户说“部署到 xxx 工作区”或“在 my-team 中创建项目”，请将名称与 workspaces 数组进行匹配，并使用相应的 ID：

# User says: "create a project in my personal workspace"
railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'
# Use the matched ID: railway init -n myapp --workspace <matched-id>

关联现有项目

railway link -p <project>

选项：

• -p, --project - 项目名称或 ID
• -e, --environment - 环境（默认为 production）
• -s, --service - 要关联的服务
• -t, --team - 团队／工作区

创建服务

关联项目后，创建服务：

railway add --service <name>

对于 GitHub 仓库来源：创建一个空服务，然后调用 railway-environment skill，通过暂存更改 API 配置来源。不要使用 railway add --repo——它需要 GitHub 应用集成，而该集成经常失败。

流程：

1. railway add --service my-api
2. 调用 railway-environment skill，设置 source.repo 和 source.branch
3. 应用更改以触发部署

根据项目类型配置

构建配置请参阅 railpack.md。 monorepo 模式请参阅 monorepo.md。

静态站点（Vite、CRA、Astro static）：

• Railpack 会自动检测常见的输出目录（dist、build）
• 如果使用非标准输出目录：调用 railway-environment skill 设置 RAILPACK_STATIC_FILE_ROOT
• 不要使用 railway variables CLI——始终使用环境 skill

Node.js SSR（Next.js、Nuxt、Express）：

• 确认 package.json 中存在 start 脚本
• 如果需要自定义启动命令：调用 railway-environment skill 设置 startCommand

Python（FastAPI、Django、Flask）：

• 确认存在 requirements.txt 或 pyproject.toml
• Railpack 会自动检测，通常无需配置

Go：

• 确认存在 go.mod
• 会自动检测，无需配置

Monorepo 配置

**关键决策：**根目录还是自定义命令。

隔离式 monorepo（各应用不共享代码）：

• 将根目录设置为应用的子目录（例如 /frontend）
• 构建期间只能访问该目录中的代码

共享式 monorepo（TypeScript 工作区、共享包）：

• 不要设置根目录
• 设置自定义构建和启动命令，以筛选目标包：
  • pnpm：pnpm --filter <package> build
  • npm：npm run build --workspace=packages/<package>
  • yarn：yarn workspace <package> build
  • Turborepo：turbo run build --filter=<package>
• 设置监视路径，以避免不必要的重新构建

详细模式请参阅 monorepo.md。

项目设置指南

分析代码库，确保与 Railway 兼容。

分析代码库

检查现有项目文件：

• package.json → Node.js 项目
• requirements.txt、pyproject.toml → Python 项目
• go.mod → Go 项目
• Cargo.toml → Rust 项目
• index.html → 静态站点
• 无 → 指导用户搭建项目

检测 monorepo：

• pnpm-workspace.yaml → pnpm 工作区（共享式 monorepo）
• 包含 workspaces 字段的 package.json → npm/yarn 工作区（共享式 monorepo）
• turbo.json → Turborepo（共享式 monorepo）
• 多个子目录各自包含独立的 package.json，但没有工作区配置 → 隔离式 monorepo

搭建提示

如果没有代码，请参考 railpack.md 中的最简模式：

静态站点：

在根目录中创建一个 index.html 文件。

Vite React：

npm create vite@latest . -- --template react

Astro：

npm create astro@latest

Python FastAPI：

创建包含 FastAPI 应用的 main.py，以及包含依赖项的 requirements.txt。

Go：

创建 main.go，并在其中编写一个监听 PORT 环境变量所指定端口的 HTTP 服务端。

数据库

要添加数据库（Postgres、Redis、MySQL、MongoDB），请使用 railway-railway-database skill。

railway-railway-database skill 负责：

• 创建数据库服务
• 配置连接变量引用
• 将服务连接到数据库

组合使用

• 创建服务后：使用 railway-deploy skill 推送代码
• 高级配置：使用 railway-environment skill（buildCommand、startCommand）
• 配置域名：使用 railway-domain skill
• 检查状态：使用 railway-status skill
• 服务操作（重命名、删除、查看状态）：使用 railway-service skill

错误处理

未安装 CLI

Railway CLI not installed. Install with:
  npm install -g @railway/cli
or
  brew install railway

未通过身份验证

Not logged in to Railway. Run: railway login

没有工作区

No workspaces found. Create one at railway.com or verify authentication.

项目名称已被占用

Project name already exists. Either:
- Link to existing: railway link -p <name>
- Use different name: railway init -n <other-name>

服务名称已被占用

Service name already exists in this project. Use a different name:
  railway add --service <other-name>

示例

创建 HTML 静态站点

User: "create a simple html site and deploy to railway"

1. Check status → not linked
2. railway init -n my-site
3. Guide: create index.html
4. railway add --service my-site
5. No config needed (index.html in root auto-detected)
6. Use deploy skill: railway up
7. Use domain skill for public URL

创建 Vite React 服务

User: "create a vite react service"

1. Check status → linked (or init/link first)
2. Scaffold: npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. No config needed (Vite dist output auto-detected)
5. Use deploy skill: railway up

将 Python API 添加到项目

User: "add a python api to my project"

1. Check status → linked
2. Guide: create main.py with FastAPI, requirements.txt
3. railway add --service api
4. No config needed (FastAPI auto-detected)
5. Use deploy skill

链接并添加服务

User: "connect to my backend project and add a worker service"

1. railway list --json → find "backend"
2. railway link -p backend
3. railway add --service worker
4. Guide setup based on worker type

部署到 Railway（存在歧义）

User: "deploy to railway"

1. railway status → not linked
2. railway list → has projects
3. Directory is "my-app", found project "my-app"
4. Ask: "Found existing project 'my-app'. Link to it or create new?"
5. User: "link"
6. railway link -p my-app
7. Ask: "Create a service for this code?"

将服务添加到隔离的 Monorepo

User: "create a static site in the frontend directory"

1. Check: /frontend has its own package.json, no workspace config
2. This is isolated monorepo → use root directory
3. railway add --service frontend
4. Invoke environment skill to set rootDirectory: /frontend
5. Set watch paths: /frontend/**

将服务添加到 TypeScript Monorepo

User: "add a new api package to this turborepo"

1. Check: turbo.json exists, pnpm-workspace.yaml exists
2. This is shared monorepo → use custom commands, NOT root directory
3. Guide: create packages/api with package.json
4. railway add --service api
5. Invoke environment skill to set buildCommand and startCommand (do NOT set rootDirectory)
6. Set watch paths: /packages/api/**, /packages/shared/**

部署现有的 pnpm 工作区包

User: "deploy the backend package to railway"

1. Check: pnpm-workspace.yaml exists → shared monorepo
2. railway add --service backend
3. Invoke environment skill to set buildCommand and startCommand
4. Set watch paths for backend + any shared deps

部署已链接项目的子目录

User: "create a vite app in my-app directory and deploy to railway"
CWD: ~/projects/my-project/my-app (parent already linked to "my-project")

1. Check status in my-app → not linked
2. Check parent: cd .. && railway status → IS linked to "my-project"
3. DON'T init/link the subdirectory
4. Scaffold: bun create vite my-app --template react-ts
5. cd my-app && bun install
6. railway add --service my-app
7. Invoke environment skill to set rootDirectory: /my-app
8. Deploy from root: railway up