在 Railway 上部署智能体

将 Flue Node 服务器作为长期运行的 Railway 服务运行。本指南假设你已经有一个正在运行的 Flue 项目。

Flue 的 Node 目标是一个长期运行的 HTTP 服务器，而非函数。它在进程中持有智能体会话，并通过长连接提供流式响应。在 Railway 上，这意味着将其作为长期运行的服务运行 — 不是 serverless 函数，不是 cron 作业。

先决条件

你需要：

• 一个 Railway 账户
• 一个正在运行的 Flue 项目（flue run 应该可以工作）
• 一个 GitHub 仓库包含你的项目

设置

1. 连接 GitHub 仓库

1. 登录 Railway Dashboard
2. 点击 “New Project”
3. 选择 “Deploy from GitHub repo”
4. 选择你的 Flue 项目仓库
5. Railway 会自动检测这是一个 Node.js 项目

2. 配置环境变量

在 Railway 项目设置中添加你的环境变量：

1. 转到你的服务 → Variables
2. 添加以下变量：

ANTHROPIC_API_KEY=sk-...
MODEL_SPECIFIER=anthropic/claude-sonnet-4-6
PORT=8080

Railway 会自动设置 PORT，但你可以在代码中覆盖它。

3. 设置数据库

没有数据库，Flue 将对话保存在内存中 — 重启时会丢失。

1. 在 Railway 项目中，点击 “New” → “Database” → “PostgreSQL”
2. Railway 会自动创建数据库并设置 DATABASE_URL 环境变量
3. 你的 Flue 应用可以自动使用这个变量

4. 创建 Dockerfile

虽然 Railway 可以自动检测 Node.js 项目，但使用 Dockerfile 可以更好地控制构建过程：

# syntax=docker/dockerfile:1

FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npx vite build

FROM node:22-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
ENV PORT=8080
EXPOSE 8080
CMD ["node", "dist/server.mjs"]

5. 配置部署

Railway 会自动部署你的应用。确保你的 package.json 有正确的构建脚本：

{
  "scripts": {
    "build": "vite build",
    "start": "node dist/server.mjs"
  }
}

6. 部署

将你的更改推送到 GitHub：

git add .
git commit -m "Setup Railway deployment"
git push

Railway 会自动检测更改并开始部署。

自定义域名

1. 添加自定义域名

1. 转到你的服务 → Settings → Networking
2. 点击 “Custom Domain”
3. 输入你的域名
4. 按照说明配置 DNS 记录

2. 配置 DNS

在你的 DNS 提供商中添加 CNAME 记录：

your-domain.com  CNAME  your-app.up.railway.app

扩展

垂直扩展

1. 转到你的服务 → Settings → Resources
2. 调整 CPU 和内存限制

水平扩展

Railway 目前不支持自动水平扩展。你可以：

• 使用多个 Railway 项目
• 使用外部负载均衡器

健康检查

Flue 不会自动生成健康检查端点。在你的 app.ts 中添加一个：

import { createAgentRouter } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { MyAgent } from './agents/my-agent.ts';

const app = new Hono();

app.get('/health', (c) => c.text('ok'));
app.route('/agents/my-agent', createAgentRouter(MyAgent));

export default app;

Railway 会自动使用这个端点进行健康检查。

日志和监控

查看日志

1. 转到你的服务 → Deployments
2. 点击最新的部署
3. 查看 “Logs” 选项卡

监控

Railway 提供基本的监控：

• CPU 使用率
• 内存使用率
• 请求量
• 响应时间

环境变量参考

故障排除

部署失败

1. 检查构建日志是否有错误
2. 确保 package.json 有正确的构建脚本
3. 验证所有依赖都已安装

应用崩溃

1. 检查运行时日志
2. 确保环境变量正确设置
3. 验证数据库连接（如果使用）

连接问题

1. 确保 PORT 环境变量正确设置
2. 检查 Railway 的网络设置
3. 验证域名配置

参考资料

• Railway 文档 — 官方 Railway 文档。
• Railway 部署指南 — 部署指南。
• Docker 部署 — 底层 Docker 镜像的详细信息。