Docker - 05 - Railway 部署

Railway 部署流程

一、Railway 账号与项目

1. 登录 Railway

• 打开 https://railway.com
• 用 GitHub 账号 登录（后面要从 GitHub 拉代码，建议直接用 GitHub 登录）

2. 新建 Project

• 点 New Project
• 选 Empty Project（先空项目，不要立刻 Deploy from GitHub）
• 给项目起名，例如：nodejs-study-api

二、基础设施（数据库与密钥）

3. 添加 PostgreSQL

• 在项目里点 + New → Database → Add PostgreSQL

• 等状态变成 Active / Running

• 点进 PostgreSQL 服务 → Variables（或 Connect）

• 找到 DATABASE_URL，先复制保存到本地记事本（后面 API 要用）

• Railway 给的连接串类似：

  postgresql://postgres:xxxx@xxxx.railway.app:5432/railway

内网 URL vs 公网 URL ：此处的 DATABASE_URL 是 Railway 项目内网 地址，供 API / Worker 等服务在 Railway 内互连使用。本地执行 prisma migrate deploy 无法直连内网，需在第 13 步改用 DATABASE_PUBLIC_URL（公网代理地址）。

4. 添加 Redis

• 回到 Project 画布，再点 + New → Database → Add Redis

• 等 Active / Running

• 点进 Redis → Variables

• 复制 REDIS_URL 保存

• 通常类似：

  redis://default:xxxx@xxxx.railway.app:6379

5. 生成 JWT_SECRET（本地生成，稍后写入 Railway）

在 PowerShell 执行：

[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }) -as [byte[]])

把输出字符串保存好，不要提交到 Git。

三、代码准备（推送仓库）

6. 修改 PORT 并推送

须在连接 GitHub（第 7 步）之前完成以下修改并推送到仓库。

将入口文件（如 index.ts）中的：

const PORT = 8080;

改为：

const PORT = Number(process.env.PORT) || 8080;

提交并推送。Railway 会为容器注入 PORT，服务需监听该端口才能正常对外提供服务。

关于 PORT（可选手动配置） ：若在 Railway > API 服务 > Variables 中额外设置了 PORT=B，服务会在 B 端口监听；此时 Settings > Networking 中的端口号也需设为 B，外网请求才会转发到该端口。一般只需使用 process.env.PORT，无需手动设置变量。

四、部署 API 服务

7. 添加 GitHub

• 回到 Project 画布，点 + New
• 选 GitHub Repo
• 若首次使用，按提示授权 Railway 访问 GitHub
• 选择仓库：HideInTheWind/nodejs-study-api（请替换为你自己的 GitHub 仓库）
• Railway 会创建一个新服务（可能叫 nodejs-study-api）

8. 仓库确认构建方式

点进这个新服务 → Settings：

项	值
Root Directory	留空（项目根目录）
Builder	应自动识别为 Dockerfile
Start Command	留空（用 Dockerfile 的 CMD "npm", "start"）

9. 仓库配置环境变量（Variables）

进入 API 服务的 Variables 标签，添加 3 个变量：

变量名	值	怎么填
DATABASE_URL	引用 Postgres	点 Add Variable Reference → 选 Postgres → DATABASE_URL
REDIS_URL	引用 Redis	Add Variable Reference → 选 Redis → REDIS_URL
JWT_SECRET	你第 5 步生成的随机串	点 New Variable，手动粘贴

建议再加一个（可选）：

变量名	值
NODE_ENV	production

10. 触发部署

• 保存变量后 Railway 会自动重新部署。也可到 Deployments 点 Deploy。
• 等构建完成（通常 2--5 分钟），状态变为 ACTIVE。

11. 生成公网域名

• 进入 API 服务 → Settings → Networking
• 点 Generate Domain
• 会得到类似 nodejs-study-api-production-xxxx.up.railway.app 的地址。
• 服务监听端口由第 6 步的 process.env.PORT 决定；若手动设置了 PORT 变量，Networking 端口需与之保持一致（详见第 6 步说明）。

12. 验证（本步只测 health）

浏览器或 PowerShell 访问：

curl https://你的域名.up.railway.app/health

注意 ：本步仅确认 API 进程已启动。/health 通常不依赖数据库，通过并不代表业务接口可用。完成第 13--15 步 Prisma 迁移后，才能正常调用依赖数据库的接口。

五、数据库迁移（Prisma）

13. 拿到 Railway 公网库

• Railway → 点 Postgres 服务
• 打开 Variables 或 Connect
• 复制 DATABASE_PUBLIC_URL（或 Public Network URL）

与第 3 步的 DATABASE_URL 不同：DATABASE_PUBLIC_URL 带 *.proxy.rlwy.net 等公网代理，供本地机器 连入 Railway 上的 Postgres。API 服务在 Railway 内仍应引用内网 DATABASE_URL，不要混用。

14. 临时设置环境变量（不要写进 .env）

在项目根目录 PowerShell 执行（把连接串换成你复制的 DATABASE_PUBLIC_URL）：

$env:DATABASE_URL="postgresql://postgres:你的密码@xxxx.proxy.rlwy.net:端口/railway"
npx prisma migrate deploy

15. 验证 migration 是否生效（或者 postman 调接口）

npx prisma studio

浏览器里应能看到 User、Todo、Product 等表。

六、部署 Worker 服务

16. 新建 Worker 服务

• Railway Project 画布 → + New → GitHub Repo
• 选同一个仓库：HideInTheWind/nodejs-study-api（请替换为你自己的 GitHub 仓库）
• 服务创建后，点服务名 → Settings，改名为 worker（可选，便于区分）

17. 配置构建方式

Settings → Build（与 API 相同）：

配置项	值
Builder	Dockerfile
Root Directory	留空
Dockerfile Path	Dockerfile

Settings → Deploy：

配置项	值
Custom Start Command	npm run worker:email

这会覆盖 Dockerfile 里的 CMD "npm", "start"，容器启动后跑 Worker 而不是 API。

18. 配置环境变量

Variables 标签，只需 1 个：

变量	值
REDIS_URL	Add Variable Reference → Redis → REDIS_URL

当前项目的 email worker 只消费 Redis 队列，配置 REDIS_URL 即可。若后续扩展为读库或接入真实邮件服务，再按需补充相应环境变量。

19. 部署

• 保存后点 Deploy，等状态 Success。
• 打开 Deployments → View Logs，应看到：
  • Email worker 已启动，等待任务...

20. 看 Worker 日志

• 下单，Railway → worker 服务 → Deployments → View Logs
• 期望出现：
  • [Mock Email] 订单 #1 → worker-test@example.com（userId=...）

七、后续维护与补充说明

21. 后续修改代码

后续修改代码直接提交到仓库即可，会自动触发构建

补充说明

prisma migrate deploy 会按 prisma/migrations/ 里已有的 4 个 migration，一次性建齐所有表（生产环境专用，不会交互提问）。