railway-auth

用途

Railway Authentication 用于管理 Railway 在 CLI、API 和 CI/CD 工作流中的认证。Railway 针对不同使用场景支持多种认证方式：交互式登录（面向开发者的基于浏览器的 OAuth）、无浏览器登录（适用于 SSH/Codespaces/无头环境的设备码流程）、API 令牌（用于自动化和 CI/CD 的编程式访问）。

适用时机包括：首次设置 Railway CLI、在 CI/CD 流水线中认证、为自动化创建 API 令牌、验证认证状态、排查认证问题。

主要能力

操作 1：交互式登录

面向本地开发的标准基于浏览器的认证。

命令：

railway login

流程：打开浏览器到 Railway OAuth 页面；使用 GitHub/邮箱认证；CLI 接收认证令牌；令牌存储在 ~/.railway/config.json。

验证：

railway whoami
# Output: Logged in as: your-email@example.com

适用场景：本地开发、首次设置。

操作 2：无浏览器登录

面向无头环境的设备码认证。

命令：

railway login --browserless

流程：CLI 生成设备码；向用户显示 URL 和代码；用户在任何设备上访问 URL；输入代码完成认证；批准后 CLI 接收令牌。

示例输出：

To authenticate, visit: https://railway.app/cli-auth
Enter code: ABCD-1234
Waiting for authentication...

适用场景：SSH 会话、GitHub Codespaces、远程服务器、Docker 容器、任何没有浏览器的环境。

操作 3：基于令牌的认证

使用 API 令牌进行编程式访问和 CI/CD。

令牌类型：

类型	范围	请求头	使用场景
Account Token	所有个人 + 团队资源	Authorization: Bearer <TOKEN>	完整 API 访问
Team Token	仅团队资源	Team-Access-Token: <TOKEN>	团队自动化
Project Token	单个环境	Project-Access-Token: <TOKEN>	限定范围的部署

创建令牌：访问 https://railway.com/account/tokens；点击 "Create Token"；选择令牌类型和范围；复制令牌（仅显示一次！）。

使用令牌进行 CLI 认证：

# For Project Tokens
export RAILWAY_TOKEN=<your-project-token>

# For Account/Team Tokens
export RAILWAY_API_TOKEN=<your-account-or-team-token>

# Verify
railway whoami

API 认证：

# Account Token
curl -H "Authorization: Bearer $RAILWAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { me { name email } }"}' \
  https://backboard.railway.com/graphql/v2

# Project Token
curl -H "Project-Access-Token: $RAILWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { projectToken { projectId } }"}' \
  https://backboard.railway.com/graphql/v2

适用场景：CI/CD 流水线、自动化脚本、API 集成。

操作 4：验证认证

检查当前认证状态。

命令：

# Check who you're logged in as
railway whoami

# Check current project context
railway status

# Verify token via API
curl -s -H "Authorization: Bearer $RAILWAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { me { name } }"}' \
  https://backboard.railway.com/graphql/v2

排查认证问题：

问题	解决方案
"Not logged in"	运行 railway login
"Not Authorized" (API)	检查令牌类型是否与请求头匹配
令牌过期	在 railway.com/account/tokens 创建新令牌
项目上下文错误	运行 railway link 重新关联项目

使用方式

CI/CD 集成

GitHub Actions：

name: Deploy to Railway
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Railway CLI
        run: npm install -g @railway/cli

      - name: Deploy
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
        run: railway up --ci

设置：在 Railway 仪表盘创建 Project Token；在 GitHub 仓库设置中添加为 RAILWAY_TOKEN secret；使用 --ci 标志进行非交互式部署。

GitLab CI：

deploy:
  stage: deploy
  image: node:20
  script:
    - npm install -g @railway/cli
    - railway up --ci
  variables:
    RAILWAY_TOKEN: $RAILWAY_PROJECT_TOKEN
  only:
    - main

令牌安全最佳实践

切勿提交令牌——使用环境变量或密钥管理器
使用最小范围——单项目 CI/CD 使用项目令牌
定期轮换——定期删除并重新创建令牌
监控使用——检查 Railway 仪表盘是否有异常活动
分离环境——为 dev/staging/prod 使用不同令牌

快速参考

任务	命令
登录（浏览器）	railway login
登录（无头）	railway login --browserless
检查认证	railway whoami
登出	railway logout
设置令牌（CLI）	export RAILWAY_TOKEN=xxx
API 认证请求头	Authorization: Bearer <token>

适用场景

首次设置 Railway CLI
在 CI/CD 流水线中认证
为自动化创建 API 令牌
验证认证状态
排查认证问题
SSH 会话、GitHub Codespaces、远程服务器、Docker 容器等无浏览器环境

限制

资料未提供具体的价格、收费、平台支持范围或效果数据。令牌创建入口、令牌类型与请求头对应关系、CLI 命令与 API 调用示例均以资料为准，未提及的功能暂未提供。

参考资料

token-types.md - 详细的令牌对比与使用
token-troubleshooting.md - 常见认证问题与修复

相关技能：railway-api（GraphQL API 自动化）、railway-automation（CI/CD 模式）、railway-project-management（项目设置）。