new

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

New Project / Service / Database

新项目/服务/数据库

Create Railway projects, services, and databases with proper configuration.

使用正确配置在Railway上创建项目、服务和数据库。

When to Use

适用场景

User says "deploy to railway" (add service if linked, init if not)
User says "create a railway project", "init", "new project" (explicit new project)
User says "link to railway", "connect to railway"
User says "create a service", "add a backend", "new api service"
User says "create a vite app", "create a react website", "make a python api"
User says "deploy from github.com/user/repo", "create service from this repo"
User says "add postgres", "add a database", "add redis", "add mysql", "add mongo"
User says "connect to postgres", "wire up the database", "connect my api to redis"
User says "add postgres and connect to the server"
Setting up code + Railway service together

用户说“deploy to railway”（若已关联则添加服务，未关联则初始化）
用户说“create a railway project”“init”“new project”（明确创建新项目）
用户说“link to railway”“connect to railway”
用户说“create a service”“add a backend”“new api service”
用户说“create a vite app”“create a react website”“make a python api”
用户说“deploy from github.com/user/repo”“create service from this repo”
用户说“add postgres”“add a database”“add redis”“add mysql”“add mongo”
用户说“connect to postgres”“wire up the database”“connect my api to redis”
用户说“add postgres and connect to the server”
同时设置代码与Railway服务

Prerequisites

前置条件

Check CLI installed:

bash

command -v railway

If not installed:

Install Railway CLI:
npm install -g @railway/cli
or
brew install railway

Check authenticated:

bash

railway whoami --json

If not authenticated:

Run
railway login
to authenticate.

检查CLI是否已安装：

bash

command -v railway

如果未安装：

安装Railway CLI：
npm install -g @railway/cli
或
brew install railway

检查是否已认证：

bash

railway whoami --json

如果未认证：

运行
railway login
进行认证。

Decision Flow

决策流程

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 (在当前目录执行)
     │
┌────┴────┐
已关联    未关联
  │            │
  │       检查父目录：cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    父目录已关联      未关联任何项目
  │       │            │
  │   添加服务   railway list
  │   设置rootDir      │
  │   部署       ┌───┴───┐
  │       │      匹配？  无匹配项
  │       │        │        │
  │       │      关联    初始化新项目
  └───────┴────────┴────────┘
           │
    用户是否需要创建服务？
           │
     ┌─────┴─────┐
    是         否
     │           │
  生成代码框架   完成
     │
railway add --service
     │
按需配置
     │
准备部署

Check Current State

检查当前状态

bash

railway status --json

If linked: Add a service to the existing project (see below)
If not linked: Check if a PARENT directory is linked (see below)

bash

railway status --json

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

When Already Linked

已关联项目时

Default behavior: "deploy to railway" = add a service to the linked project.

Do NOT create a new project unless user EXPLICITLY says:

"new project", "create a project", "init a project"
"separate project", "different project"

App names like "flappy-bird" or "my-api" are SERVICE names, not project names.

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

默认行为：“deploy to railway” = 为已关联的项目添加服务。

除非用户明确说明以下内容，否则不要创建新项目：

"new project"、"create a project"、"init a project"
"separate project"、"different project"

类似“flappy-bird”或“my-api”的名称是服务名称，而非项目名称。

用户：“create a vite app called foo and deploy to railway”
当前项目：已关联到“my-project”

错误操作：railway init -n foo
正确操作：railway add --service foo

Parent Directory Linking

父目录关联

Railway CLI walks up the directory tree to find a linked project. If you're in a subdirectory:

bash

cd .. && railway status --json

If parent is linked, you don't need to init/link the subdirectory. Instead:

Create service:
```
railway add --service <name>
```
Set
```
rootDirectory
```
to subdirectory path via environment skill
Deploy from root:
```
railway up
```

If no parent is linked, proceed with init or link flow.

Railway CLI 会遍历目录树查找已关联的项目。如果当前处于子目录：

bash

cd .. && railway status --json

如果父目录已关联，无需初始化/关联子目录。只需：

创建服务：
```
railway add --service <name>
```
通过environment技能设置
```
rootDirectory
```
为子目录路径
从根目录部署：
```
railway up
```

如果无父目录关联，执行初始化或关联流程。

Init vs Link Decision

初始化 vs 关联决策

Skip this section if already linked - just add a service instead.

Only use this section when NO project is linked (directly or via parent).

如果已关联项目，请跳过此部分 - 直接添加服务即可。

仅当无任何项目关联（直接或通过父目录）时使用此部分。

Check User's Projects

检查用户的项目

The output can be large. Run in a subagent and extract only:

Project
```
id
```
and
```
name
```
Workspace
```
id
```
and
```
name
```

bash

railway list --json

输出内容可能较多。在子Agent中执行命令并仅提取以下信息：

项目
```
id
```
和
```
name
```
工作区
```
id
```
和
```
name
```

bash

railway list --json

Decision Logic

决策逻辑

User explicitly says "new project" → Use
```
railway init
```
User names an existing project → Use
```
railway link
```
Directory name matches existing project → Ask: link existing or create new?
No matching projects → Use
```
railway init
```
Ambiguous → Ask user

用户明确说“new project” → 使用
```
railway init
```
用户指定现有项目名称 → 使用
```
railway link
```
目录名称与现有项目匹配 → 询问用户：关联现有项目还是创建新项目？
无匹配项目 → 使用
```
railway init
```
存在歧义 → 询问用户

Create New Project

创建新项目

bash

railway init -n <name>

Options:

```
-n, --name
```
- Project name (auto-generated if omitted in non-interactive mode)
```
-w, --workspace
```
- Workspace name or ID (required if multiple workspaces exist)

bash

railway init -n <name>

选项：

```
-n, --name
```
- 项目名称（非交互模式下省略会自动生成）
```
-w, --workspace
```
- 工作区名称或ID（存在多个工作区时必填）

Multiple Workspaces

多工作区场景

If the user has multiple workspaces,

railway init

requires the

--workspace

flag.

Get workspace IDs from:

bash

railway whoami --json

The

workspaces

array contains

{ id, name }

for each workspace.

Inferring workspace from user input: If user says "deploy into xxx workspace" or "create project in my-team", match the name against the workspaces array and use the corresponding ID:

bash

undefined

如果用户有多个工作区，

railway init

需要

--workspace

参数。

从以下命令获取工作区ID：

bash

railway whoami --json

workspaces

数组包含每个工作区的

{ id, name }

信息。

根据用户输入推断工作区： 如果用户说“deploy into xxx workspace”或“create project in my-team”，将名称与workspaces数组匹配，并使用对应的ID：

bash

undefined

User says: "create a project in my personal workspace"

用户：“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>

使用匹配到的ID：railway init -n myapp --workspace <matched-id>

undefined

undefined

Link Existing Project

关联现有项目

bash

railway link -p <project>

Options:

```
-p, --project
```
- Project name or ID
```
-e, --environment
```
- Environment (default: production)
```
-s, --service
```
- Service to link
```
-t, --team
```
- Team/workspace

bash

railway link -p <project>

选项：

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

Create Service

创建服务

After project is linked, create a service:

bash

railway add --service <name>

For GitHub repo sources: Create an empty service, then invoke the

environment

skill to configure the source via staged changes API. Do NOT use

railway add --repo

- it requires GitHub app integration which often fails.

Flow:

```
railway add --service my-api
```
Invoke
```
environment
```
skill to set
```
source.repo
```
and
```
source.branch
```
Apply changes to trigger deployment

项目关联后，创建服务：

bash

railway add --service <name>

对于GitHub仓库源：创建空服务，然后调用

environment

技能通过分阶段变更API配置源。不要使用

railway add --repo

- 它需要GitHub应用集成，经常会失败。

流程：

```
railway add --service my-api
```
调用
```
environment
```
技能设置
```
source.repo
```
和
```
source.branch
```
应用变更以触发部署

Configure Based on Project Type

根据项目类型配置

Reference railpack.md for build configuration. Reference monorepo.md for monorepo patterns.

Static site (Vite, CRA, Astro static):

Railpack auto-detects common output dirs (dist, build)
If non-standard output dir: invoke
```
environment
```
skill to set
```
RAILPACK_STATIC_FILE_ROOT
```
Do NOT use
```
railway variables
```
CLI - always use the environment skill

Node.js SSR (Next.js, Nuxt, Express):

Verify
```
start
```
script exists in package.json
If custom start needed: invoke
```
environment
```
skill to set
```
startCommand
```

Python (FastAPI, Django, Flask):

Verify
```
requirements.txt
```
or
```
pyproject.toml
```
exists
Auto-detected by Railpack, usually no config needed

Go:

Verify
```
go.mod
```
exists
Auto-detected, no config needed

参考railpack.md获取构建配置。参考monorepo.md获取单体仓库（Monorepo）模式。

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

Railpack会自动检测常见输出目录（dist、build）
如果是非标准输出目录：调用
```
environment
```
技能设置
```
RAILPACK_STATIC_FILE_ROOT
```
不要使用
```
railway variables
```
CLI - 始终使用environment技能

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

验证package.json中是否存在
```
start
```
脚本
如果需要自定义启动命令：调用
```
environment
```
技能设置
```
startCommand
```

Python（FastAPI、Django、Flask）：

验证是否存在
```
requirements.txt
```
或
```
pyproject.toml
```
Railpack会自动检测，通常无需配置

Go：

验证是否存在
```
go.mod
```
自动检测，无需配置

Monorepo Configuration

单体仓库配置

Critical decision: Root directory vs custom commands.

Isolated monorepo (apps don't share code):

Set Root Directory to the app's subdirectory (e.g.,
```
/frontend
```
)
Only that directory's code is available during build

Shared monorepo (TypeScript workspaces, shared packages):

Do NOT set root directory

Set custom build/start commands to filter the package:

pnpm:
```
pnpm --filter <package> build
```

npm:

npm run build --workspace=packages/<package>

yarn:
```
yarn workspace <package> build
```
Turborepo:
```
turbo run build --filter=<package>
```

Set watch paths to prevent unnecessary rebuilds

See monorepo.md for detailed patterns.

关键决策：根目录 vs 自定义命令。

隔离型单体仓库（应用间不共享代码）：

将根目录设置为应用的子目录（例如：
```
/frontend
```
）
构建期间仅可访问该目录下的代码

共享型单体仓库（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。

Project Setup Guidance

项目设置指南

Analyze the codebase to ensure Railway compatibility.

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

Analyze Codebase

分析代码库

Check for existing project files:

```
package.json
```
→ Node.js project
```
requirements.txt
```
,
```
pyproject.toml
```
→ Python project
```
go.mod
```
→ Go project
```
Cargo.toml
```
→ Rust project
```
index.html
```
→ Static site
None → Guide scaffolding

Monorepo detection:

```
pnpm-workspace.yaml
```
→ pnpm workspace (shared monorepo)
```
package.json
```
with
```
workspaces
```
field → npm/yarn workspace (shared monorepo)
```
turbo.json
```
→ Turborepo (shared monorepo)
Multiple subdirs with separate
```
package.json
```
but no workspace config → isolated monorepo

检查现有项目文件：

```
package.json
```
→ Node.js项目
```
requirements.txt
```
、
```
pyproject.toml
```
→ Python项目
```
go.mod
```
→ Go项目
```
Cargo.toml
```
→ Rust项目
```
index.html
```
→ 静态站点
无以上文件 → 引导生成代码框架

单体仓库检测：

```
pnpm-workspace.yaml
```
→ pnpm工作区（共享型单体仓库）
包含
```
workspaces
```
字段的
```
package.json
```
→ npm/yarn工作区（共享型单体仓库）
```
turbo.json
```
→ Turborepo（共享型单体仓库）
多个子目录包含独立
```
package.json
```
但无工作区配置 → 隔离型单体仓库

Scaffolding Hints

代码框架生成提示

If no code exists, suggest minimal patterns from railpack.md:

Static site:

Create an
index.html
file in the root directory.

Vite React:

bash

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

Astro:

bash

npm create astro@latest

Python FastAPI:

Create
main.py
with FastAPI app and
requirements.txt
with dependencies.

Go:

Create
main.go
with HTTP server listening on
PORT
env var.

如果无代码存在，建议使用railpack.md中的最简模式：

静态站点：

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

Vite React：

bash

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

Astro：

bash

npm create astro@latest

Python FastAPI：

创建包含FastAPI应用的
main.py
和包含依赖的
requirements.txt
。

Go：

创建监听
PORT
环境变量的HTTP服务器
main.go
。

Databases

数据库

For adding databases (Postgres, Redis, MySQL, MongoDB), use the

database

skill.

The

database

skill handles:

Creating database services
Connection variable references
Wiring services to databases

添加数据库（Postgres、Redis、MySQL、MongoDB）请使用

database

技能。

database

技能可处理：

创建数据库服务
连接变量引用
将服务与数据库关联

Composability

组合性

After service created: Use
```
deploy
```
skill to push code
For advanced config: Use
```
environment
```
skill (buildCommand, startCommand)
For domains: Use
```
domain
```
skill
For status checks: Use
```
status
```
skill
For service operations (rename, delete, status): Use
```
service
```
skill

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

Error Handling

错误处理

CLI Not Installed

CLI未安装

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

Railway CLI未安装。请使用以下命令安装：
  npm install -g @railway/cli
或
  brew install railway

Not Authenticated

未认证

Not logged in to Railway. Run: railway login

未登录Railway。请运行：railway login

No Workspaces

无工作区

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

未找到工作区。请在railway.com创建一个或验证认证状态。

Project Name Taken

项目名称已存在

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

项目名称已存在。可选择：
- 关联现有项目：railway link -p <name>
- 使用其他名称：railway init -n <other-name>

Service Name Taken

服务名称已存在

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

该项目中服务名称已存在。请使用其他名称：
  railway add --service <other-name>

Examples

示例

Create HTML Static Site

创建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

用户：“create a simple html site and deploy to railway”

1. 检查状态 → 未关联
2. 执行railway init -n my-site
3. 引导：创建index.html
4. 执行railway add --service my-site
5. 无需配置（根目录下的index.html会被自动检测）
6. 使用deploy技能：railway up
7. 使用domain技能配置公网URL

Create Vite React Service

创建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

用户：“create a vite react service”

1. 检查状态 → 已关联（或先初始化/关联）
2. 生成框架：npm create vite@latest frontend -- --template react
3. 执行railway add --service frontend
4. 无需配置（Vite的dist输出会被自动检测）
5. 使用deploy技能：railway up

Add Python API to Project

为项目添加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

用户：“add a python api to my project”

1. 检查状态 → 已关联
2. 引导：创建包含FastAPI的main.py和requirements.txt
3. 执行railway add --service api
4. 无需配置（FastAPI会被自动检测）
5. 使用deploy技能

Link and Add Service

关联并添加服务

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

用户：“connect to my backend project and add a worker service”

1. 执行railway list --json → 找到“backend”
2. 执行railway link -p backend
3. 执行railway add --service worker
4. 根据Worker类型引导设置

Deploy to Railway (Ambiguous)

部署到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?"

用户：“deploy to railway”

1. 执行railway status → 未关联
2. 执行railway list → 存在项目
3. 当前目录为“my-app”，找到同名项目“my-app”
4. 询问：“找到现有项目'my-app'。是关联它还是创建新项目？”
5. 用户：“link”
6. 执行railway link -p my-app
7. 询问：“是否为此代码创建服务？”

Add Service to Isolated 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/**

用户：“create a static site in the frontend directory”

1. 检查：/frontend有独立的package.json，无工作区配置
2. 属于隔离型单体仓库 → 使用根目录设置
3. 执行railway add --service frontend
4. 调用environment技能设置rootDirectory: /frontend
5. 设置监听路径：/frontend/**

Add Service to TypeScript Monorepo

为TypeScript单体仓库添加服务

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/**

用户：“add a new api package to this turborepo”

1. 检查：存在turbo.json和pnpm-workspace.yaml
2. 属于共享型单体仓库 → 使用自定义命令，不要设置根目录
3. 引导：在packages/api目录创建package.json
4. 执行railway add --service api
5. 调用environment技能设置buildCommand和startCommand（不要设置rootDirectory）
6. 设置监听路径：/packages/api/**, /packages/shared/**

Deploy Existing pnpm Workspace Package

部署现有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

用户：“deploy the backend package to railway”

1. 检查：存在pnpm-workspace.yaml → 共享型单体仓库
2. 执行railway add --service backend
3. 调用environment技能设置buildCommand和startCommand
4. 设置backend及所有共享依赖的监听路径

Deploy Subdirectory of Linked Project

部署已关联项目的子目录

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

用户：“create a vite app in my-app directory and deploy to railway”
当前目录：~/projects/my-project/my-app（父目录已关联到“my-project”）

1. 检查my-app目录状态 → 未关联
2. 检查父目录：cd .. && railway status → 已关联到“my-project”
3. 不要初始化/关联子目录
4. 生成框架：bun create vite my-app --template react-ts
5. 执行cd my-app && bun install
6. 执行railway add --service my-app
7. 调用environment技能设置rootDirectory: /my-app
8. 从根目录部署：railway up