migrate-to-railcode

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate to Railcode

迁移到 Railcode

A migration is a port, not a rewrite: the project already works somewhere, and the job is to keep what it does for its users while replacing what the old host provided (auth, a database, env vars, cron, file storage) with what Railcode provides.
Most internal tools fit. Usually one or two pieces have no direct equivalent, and almost all of those can be rebuilt a different way that the user will not notice — see Find another way. A short list of things cannot be hosted at all today — see What Railcode cannot host today. Know both lists before you promise anything.
Guides by source project:
Source projectGuideStatus
Next.js (App Router)references/nextjs.mdSupported as
"type": "next"
, built by
@railcode/next
. Proven on a real app, with gaps listed in the guide
A container: a
Dockerfile
or docker-compose stack running a server in any language
references/containers.mdMethod and mappings built from the platform's documented behaviour; not yet backed by a recorded migration
For any other source, follow the method below and build the app with
create-railcode-app
.
Railcode's own
db
is meant for fast, simple use. It has limits for a lot of data or complex queries (no joins, aggregates or transactions; paged reads), so a project that needs those keeps its database. references/databases.md covers those limits, connecting a database as a data source, using it directly with a secret, databases Railcode has no connector for, where schema migrations run, and how to register interest in a managed Postgres through
railcode agent-feedback
.
迁移是一次移植,而不是重写:项目已经在某个环境中正常运行,任务是在保留其对用户提供的功能的同时,用 Railcode 提供的能力替换旧托管环境提供的组件(auth、数据库、环境变量、cron、文件存储)。
大多数内部工具都适合迁移。通常只有一两个部分没有直接对应物,而几乎所有这些部分都能通过用户不会察觉的不同方式重建——参见寻找替代方式。目前还有一小部分功能完全无法承载——参见Railcode 目前无法承载的功能。在做出承诺前,先了解这两份清单。
按来源项目划分的指南:
来源项目指南状态
Next.js(App Router)references/nextjs.md支持
"type": "next"
类型,由
@railcode/next
构建。已在真实应用上验证,未支持的缺口列在指南中
容器:包含运行任意语言服务器的
Dockerfile
或 docker-compose 技术栈
references/containers.md方法和映射依据平台的文档行为制定;尚无已记录的迁移案例佐证
对于其他来源项目,请按照下方方法执行,并使用
create-railcode-app
构建应用。
Railcode 自带的
db
适合快速、简单的使用。对于海量数据或复杂查询,它存在限制(不支持 join、aggregate 或 transaction;采用分页读取),因此需要这些能力的项目应保留自己的数据库。references/databases.md 介绍了这些限制、如何将数据库作为 data source 连接、如何直接配合 secret 使用数据库、Railcode 没有 connector 的数据库、schema migration 在哪里运行,以及如何通过
railcode agent-feedback
登记使用托管 Postgres 的意向。

Update First

先更新

Before running a
railcode
command, update the skills and the CLI and confirm what is published:
bash
npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode version
If npm is unreachable, say so and do not claim this guidance is current. This version was written against CLI 0.3.8,
@railcode/sdk
0.4.0
and
@railcode/next
0.1.0
.
This skill does not restate the SDK, the manifest or the deploy flow. Those live in
create-railcode-app
(
references/worker-sdk.md
,
references/cli-workflow.md
,
references/deployment.md
,
references/app-patterns.md
); read them when a step below names an SDK surface.
运行任何
railcode
命令之前,更新 skills 和 CLI,并确认已发布的版本:
bash
npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode version
如果 npm 无法访问,应如实说明,不要声称本指南为最新版本。本指南基于 CLI 0.3.8、
@railcode/sdk
0.4.0
和
@railcode/next
0.1.0
编写。
本 skill 不会重复说明 SDK、manifest 或部署流程。这些内容位于
create-railcode-app
(
references/worker-sdk.md
、
references/cli-workflow.md
、
references/deployment.md
、
references/app-patterns.md
);当下文提到某个 SDK surface 时,请阅读相应内容。

What Railcode is, for someone arriving from another host

从其他托管环境迁移时,Railcode 是什么

Four facts shape every migration. Check the project against them first.
  • Every viewer is a signed-in member of the organization. There are no anonymous visitors and no self-signup. Railcode hosts internal tools.
  • The backend is one worker module on a Workers runtime (
    nodejs_compat
    ), not a Node server and not a container. It runs once per request and keeps nothing in memory between requests. No filesystem, no child processes, no native addons, no raw TCP.
  • The worker runs only when a signed-in member's browser calls it, or on the app's own cron. Nothing on the public internet can call it.
  • Authentication is ambient. The platform signs the user in before any app code runs and hands the worker a verified
    ctx.user
    . The project's own login goes away, and that is usually the largest deletion in the migration.
In exchange the app gets, with no setup: sign-in, a store (
db
), file storage (
files
), an LLM gateway (
llm
), email sending, per-app secrets, cron, connectors to the org's databases and SaaS accounts, managed agents, deploy history and logs.
以下四项事实决定了所有迁移方式。首先用它们检查项目。
  • 每个访问者都是组织中已登录的成员。 不存在匿名访问者,也不支持自行注册。Railcode 用于托管内部工具。
  • 后端是 Workers 运行时(
    nodejs_compat
    )上的一个 worker module
    ,而不是 Node 服务器或容器。它每次请求运行一次,请求之间不会在内存中保留任何内容。不支持文件系统、子进程、native addon 或 raw TCP。
  • 只有已登录成员的浏览器调用 worker,或应用自身的 cron 调用 worker 时,它才会运行。 公共互联网无法调用它。
  • 身份验证是环境内置的(ambient)。 平台会在任何应用代码运行前为用户登录,并将经过验证的
    ctx.user
    交给 worker。项目自身的登录机制会被移除,这通常是迁移中删除量最大的部分。
作为交换,应用无需额外配置即可获得:登录、
db
存储、
files
文件存储、
llm
gateway、邮件发送、per-app secrets、cron、组织数据库和 SaaS 账号的 connectors、managed agents、部署历史与日志。

Method

方法

Work in this order. Do the inventory before touching code: most failed migrations port the UI first and discover on day two that the data layer has no equivalent.
请按以下顺序执行。必须在修改代码之前完成盘点:大多数失败的迁移会先移植 UI,到了第二天才发现 data layer 没有对应物。

1. Inventory

1. 盘点

Read the project and write down, with file paths:
WhatWhere to look
AuthNextAuth/Auth.js, Clerk, Supabase auth, Passport, a session cookie, a
/login
route
DataAn ORM (Prisma, Drizzle, SQLAlchemy, ActiveRecord), a database URL, a hosted KV or blob store
Secrets and config
.env*
,
process.env.*
,
ENV
lines in a Dockerfile, the old host's dashboard
Scheduled and background work
vercel.json
crons, a queue and its workers, a
setInterval
in a server, a cron container
Outbound callsEvery host the server code fetches
Inbound callsWebhooks, public API routes, OAuth callbacks, anything not called by the app's own frontend
FilesUploads, generated documents, an S3 client, a mounted volume
Processes and binariesEvery service in docker-compose, every
apt-get install
, every binary the code shells out to
Host-specific packages
@vercel/*
, platform SDKs, edge-only APIs
阅读项目,并连同文件路径记录以下内容:
内容查看位置
AuthNextAuth/Auth.js、Clerk、Supabase auth、Passport、session cookie、
/login
route
数据ORM(Prisma、Drizzle、SQLAlchemy、ActiveRecord)、database URL、托管的 KV 或 blob store
Secrets 和配置
.env*
、
process.env.*
、Dockerfile 中的
ENV
行、旧托管平台的控制台
定时和后台工作
vercel.json
中的 crons、queue 及其 workers、服务端中的
setInterval
、cron 容器
出站调用服务端代码会请求的每一个 host
入站调用Webhooks、公共 API routes、OAuth callbacks,以及任何并非由应用自身前端调用的内容
文件上传内容、生成的文档、S3 client、挂载的 volume
进程和二进制文件docker-compose 中的每个服务、每次
apt-get install
,以及代码会调用的每个二进制文件
特定于托管平台的包
@vercel/*
、平台 SDK、仅适用于 edge 的 API

2. Map each item

2. 映射每一项

The project hasOn Railcode
Its own login and sessionsDelete the authentication machinery. Read
ctx.user
(
id
,
email
,
name
,
is_admin
,
roles
).
appUsers
lists the org's members
A user tableKeep what is application data (profiles, preferences, app-level roles): move it to
db
. Railcode user ids are not the old ids — see step 4 before importing anything keyed by user
Per-user rows in its own database
db
collections — one flat store per app, so put the user id in the key (
<userId>:<id>
) and enforce access in server code. Suited to small, simple data; for large tables or complex queries keep the database
A database it reads (Postgres, BigQuery, Turso)Connect it as a data source: a data connector an org admin sets up. Read-only. Prefer saved queries (
query(name, params)
); direct SQL is
data(name).runSQL(...)
with
adhoc_sql:
in the manifest
A database it reads and writesKeep it and use it directly: the connection credential in
railcode secrets
, the host under
egress:
, and a client that speaks HTTPS (no raw TCP). Or move the app's own tables into
db
. See references/databases.md
A database Railcode has no connector for (MySQL, MongoDB, DynamoDB, Redis and so on)The same: set its credentials as secrets, allow its host, and use it as before over its HTTPS API
Schema migrations (Prisma, Drizzle, Alembic, Rails)Run them in the build or deploy script, on the machine that runs it, never in the worker. See references/databases.md
process.env.SECRET
railcode secrets set NAME
, read as
secrets.NAME
Cron jobs
crons:
in
manifest.yaml
, each calling one of the app's own routes with
POST
Outbound fetchesList each host under
egress:
File uploads, a mounted volume
files
An LLM provider key and client
llm
, with
llm: true
in the manifest
Transactional email
email
, with
email: true
in the manifest
A SaaS API it calls with its own OAuth flow or API keyA connector an admin or the user links, called with
connector(name)
; or a secret plus an
egress:
host
A queue, websockets, a webhook receiver, a native binary, a search indexNo direct equivalent. Go to Find another way
For every item with no direct equivalent, tell the user before porting: what the project does today, how you propose to rebuild it, and what changes for them (for example "new payments show up within a minute instead of instantly"). Get a yes on each one. A different implementation the user agreed to is a good migration; an approximation they discover later is a bug.
项目包含在 Railcode 中
自身的登录和 sessions删除身份验证机制。读取
ctx.user
(
id
、
email
、
name
、
is_admin
、
roles
)。
appUsers
列出组织的成员
用户表保留属于应用数据的部分(profiles、preferences、应用级角色)并迁移到
db
。Railcode user id 与旧 id 不同——在导入任何以用户为 key 的数据前,请参阅步骤 4
自有数据库中的 per-user 行
db
collections——每个应用对应一个扁平存储,因此应把 user id 放入 key(
<userId>:<id>
),并在服务端代码中执行访问控制。适合小型、简单的数据;对于大型表或复杂查询,应保留数据库
仅读取的数据库(Postgres、BigQuery、Turso)将其连接为 data source:由组织管理员设置 data connector。只读。 优先使用 saved queries(
query(name, params)
);直接 SQL 使用
data(name).runSQL(...)
,并在 manifest 中设置
adhoc_sql:
同时读取和写入的数据库保留并直接使用:在
railcode secrets
中保存 connection credential,在
egress:
中声明 host,并使用支持 HTTPS 的 client(不支持 raw TCP)。也可以把应用自身的表迁移到
db
。参见 references/databases.md
Railcode 没有 connector 的数据库(MySQL、MongoDB、DynamoDB、Redis 等)同样处理:将 credentials 设为 secrets,允许其 host,然后像以前一样通过其 HTTPS API 使用
Schema migrations(Prisma、Drizzle、Alembic、Rails)在构建或部署脚本运行的机器上执行,绝不能在 worker 中执行。参见 references/databases.md
process.env.SECRET
railcode secrets set NAME
,通过
secrets.NAME
读取
Cron jobs在
manifest.yaml
中配置
crons:
,每项通过
POST
调用应用自身的某个 route
出站 fetch在
egress:
下声明每一个 host
文件上传、挂载的 volume
files
LLM provider key 和 client
llm
,并在 manifest 中设置
llm: true
Transactional email
email
,并在 manifest 中设置
email: true
使用自有 OAuth flow 或 API key 调用的 SaaS API由管理员或用户关联 connector,并通过
connector(name)
调用;也可以使用 secret 加上
egress:
host
Queue、websockets、webhook receiver、native binary、search index没有直接对应物。请参阅寻找替代方式
对于每个没有直接对应物的部分,必须在移植之前告知用户:项目目前具备什么功能、建议如何重建,以及用户会看到哪些变化(例如,“新支付会在一分钟内出现,而不是立即出现”)。每一项都需要获得用户确认。用户认可的不同实现是成功的迁移;用户事后才发现的近似替代则属于缺陷。

3. Port

3. 移植

  1. Add the Railcode files (
    railcode.json
    ,
    manifest.yaml
    ) and get an unchanged page rendering under
    railcode dev
    .
  2. Replace auth.
  3. Replace the data layer, one entity at a time.
  4. Move secrets, crons and egress into the manifest and
    railcode secrets
    .
  5. Rebuild the pieces from Find another way.
  6. Remove the old host's packages and config.
Keep each step runnable. A migration that only works when all six are done is one you cannot debug.
railcode dev
keeps
db
and
files
in local scratch storage, but SQL, connectors, email,
llm
and agents are forwarded to the real instance. Testing a route that sends email sends email.
  1. 添加 Railcode 文件(
    railcode.json
    、
    manifest.yaml
    ),并让未经修改的页面能够在
    railcode dev
    下正常呈现。
  2. 替换 auth。
  3. 逐个 entity 替换 data layer。
  4. 将 secrets、crons 和 egress 迁移到 manifest 与
    railcode secrets
    。
  5. 重建寻找替代方式中列出的部分。
  6. 移除旧托管平台的包和配置。
每一步都应保持可运行。只有六步全部完成后才能运行的迁移无法调试。
railcode dev
会将
db
和
files
保存在本地 scratch storage 中,但 SQL、connectors、email、
llm
和 agents 会被转发到真实实例。测试发送邮件的 route 会实际发送邮件。

4. Deploy beside the original

4. 与原应用并行部署

Deploy to a new app slug and leave the original running. Nothing about a first deploy is destructive, and the user can compare the two. Only move data and switch people over once the new app has been checked.
Existing data does not move by itself. If it matters, write a one-off import (a script that reads the old store and writes through a temporary admin-only route, or
railcode app kv
from the CLI), run it once, and delete it.
Records owned by a user need their owner translated. The old app's user ids mean nothing on Railcode, so importing rows under their old ids leaves them unreachable. Build the mapping first — old id → email → the Railcode member with that email (
appUsers
) — show the user who did not match, and only then import, writing each record under the Railcode id.
使用新的 app slug 部署,同时保持原应用运行。第一次部署不会造成破坏,用户可以比较两个版本。只有检查完新应用后,才能迁移数据并切换用户。
现有数据不会自动迁移。如果数据很重要,请编写一次性导入程序(读取旧存储并通过临时的 admin-only route 写入,或使用 CLI 中的
railcode app kv
),运行一次后将其删除。
由用户拥有的记录需要转换 owner。旧应用的 user id 在 Railcode 中没有任何意义,因此使用旧 id 导入的行将无法访问。应先建立映射:旧 id → email → email 对应的 Railcode member(
appUsers
),向用户展示未匹配项,确认后再导入,并使用 Railcode id 写入每条记录。

5. Verify, then report

5. 验证,然后报告

Load the deployed app as a real user and exercise each migrated feature; a green deploy says only that the bundle uploaded.
railcode logs app --app <slug>
lists every invocation, and
railcode logs app <invocation-id>
shows its console output and errors.
Report in this order: what works and how it was checked, what was rebuilt differently and what changed for the user, what was left out and why, what the user must still do (secrets to set, connectors to link, data to import).
以真实用户身份加载已部署的应用,并逐一操作每个迁移后的功能;部署成功只说明 bundle 已上传。
railcode logs app --app <slug>
会列出每次 invocation,
railcode logs app <invocation-id>
会显示其 console output 和 errors。
按以下顺序报告:哪些功能可用以及如何验证;哪些部分采用了不同的重建方式以及用户会看到哪些变化;哪些内容未迁移以及原因;用户还需要完成哪些操作(设置 secrets、关联 connectors、导入数据)。

Find another way

寻找替代方式

When a piece of the project has no direct equivalent, do not stop and do not drop it. Ask what the piece is for, not what it is built from. A queue exists so that slow work finishes without the user waiting. A webhook exists so the app learns about a payment. A websocket exists so a list looks current. Each of those outcomes can usually be reached with a cron, the store, and a frontend that polls.
The building blocks you have:
  • A cron that fires as often as once a minute and can use
    db
    ,
    files
    ,
    llm
    ,
    email
    ,
    secrets
    , egress, SQL and org connectors.
  • A store you can use as a queue, a cache, a lock or a cursor.
  • A frontend that can call the worker as often as it likes. A browser tab has no subrequest budget and stays open, so it can drive long work one step at a time.
  • Managed agents for work that is long, needs code execution, or reads files with AI.
  • Connectors to the org's existing databases and SaaS accounts.
  • Outbound HTTP to any host you declare, so a hosted API can do what a local binary did.
Shapes that work:
The project does thisBuild it like thisWhat changes for the user
Receives a webhook to learn that something happened (a payment, a new issue, a form entry)A cron polls the provider's list or events API. Keep the last-seen id or timestamp in
db
as a cursor, and make processing idempotent
Up to a minute of delay
Runs a job queue (BullMQ, Celery, Sidekiq)A
jobs
collection. Routes insert rows with
status: "queued"
; a cron route takes a small batch, processes it, marks each row done. Cron runs are at-least-once and may overlap, so stamp claimed rows with
ctx.invocationId
and keep side effects safe to repeat
Jobs start within a minute, not instantly
Does one long task in a request (a big import, a report over thousands of rows)Split it into steps with a cursor in
db
. The frontend calls a step route in a loop and shows progress, or a cron advances it. Keep each step well under the ~100 subrequest budget
A progress bar instead of a spinner
Pushes live updates over websockets or SSEThe frontend polls a cheap route every few seconds, only while the tab is visible. Return an
updated_at
so an unchanged poll is a tiny response
Updates arrive within the poll interval
Streams text to the browserReturn a streamed
Response
;
toNdjson()
in the SDK does the framing
Nothing
Joins and filters in SQL on its own databaseDesign keys for the reads the screens make (
<userId>:<id>
,
prefix()
), store a little duplicated data, filter with
query().where()
, and paginate until a short page. If the data is shared with other systems, leave it in that database and read it through a data connector
Nothing, if the keys match the screens
Writes to a relational database that must stay relational (transactions, constraints, other systems read it)Keep the database and use it directly from the worker with a secret and an HTTPS driver (references/databases.md). Data connectors are read-only, so they cover the reads only. If the database has no HTTPS interface, put one in front of it or keep a small write service on the old hostNothing, when an HTTPS driver exists
Caches in Redis or in process memoryA
db
collection with an
expires_at
field checked on read. In-memory caches do not survive between requests
Nothing
Rate-limits or locks with RedisA
db
row per key holding a counter and a window start. It is not atomic, so use it for fairness, not for money
Nothing
Full-text search over its own recordsFor a few thousand records, load and filter in the worker or the browser. Beyond that, query the source database through a connector, or call a hosted search API through
egress:
Nothing
Shells out to a binary (ffmpeg, ImageMagick, Chromium, pandoc)First look for a pure-JavaScript library that fits in the worker bundle; PDF and spreadsheet generation usually do. Otherwise call a hosted API through
egress:
, or hand the job to a managed agent, which can run code
Possibly a slower or asynchronous result
Runs its own OAuth flow against Google, Slack, GitHub and so onA connector. An admin links an org account, or each user links their own; the worker calls
connector(name)
and never sees a token
Users link the account once in Railcode instead of in the app
Receives email, or sends from a real person's or team's addressA Gmail connector for that account: polled on a cron with a stored cursor when org-owned, or read by a personal managed agent on a schedule for one person's own inboxUp to a minute of delay on inbound mail
Needs embeddings, vision or another model feature the
llm
gateway lacks
Call that provider directly: the key in
secrets
, the host in
egress:
Nothing
Sends push or chat notifications
email
, or a Slack connector posting to a channel
The notification arrives in email or Slack
Has one public page among many internal ones (a public form, a status page)Split it. Leave the public page on the old host writing to its database; the Railcode app reads that database through a data connectorTwo deployments instead of one
Renders HTML on the server with templates (Jinja, ERB, EJS)A static frontend that fetches JSON from
/api/*
routes
Nothing
Has several services in docker-composeOne worker with several route groups. If two parts have different audiences, make them two appsNothing
Rules for doing this well:
  • Say what changes. Every row trades something, usually latency. State it in one sentence and get agreement before building.
  • Prefer the simplest block. A frontend poll beats a cron; a cron beats an agent.
  • Check the cron limits before designing around one: one-minute minimum, five schedules per app, no caller (
    ctx.user
    is
    null
    ), and it cannot start or read managed agent runs. One cron route can dispatch several kinds of work when five schedules is not enough.
  • Do not fake a guarantee. If the original relied on a transaction, exactly-once delivery or an instant response to a third party, a polling version does not provide it. That belongs in the next section.
If the user needs something that is not in this table, design it from the building blocks, tell them it is a new pattern, and report it (see Feedback) so it can be added.
当项目的某一部分没有直接对应物时,不要停止,也不要将其丢弃。应询问这部分功能是为了什么,而不是它由什么构成。Queue 的存在是为了让耗时工作无需等待用户即可完成。Webhook 的存在是为了让应用获知支付事件。Websocket 的存在是为了让列表看起来保持最新。这些结果通常都可以通过 cron、存储和定期轮询的前端来实现。
可用的 building blocks:
  • 最快可每分钟触发一次的 cron,可使用
    db
    、
    files
    、
    llm
    、
    email
    、
    secrets
    、egress、SQL 和组织 connectors。
  • 可用于 queue、cache、lock 或 cursor 的 store。
  • 可按任意频率调用 worker 的前端。 浏览器 tab 没有 subrequest budget,且会保持打开,因此可以逐步驱动耗时工作。
  • Managed agents,适用于耗时较长、需要执行代码或使用 AI 读取文件的工作。
  • Connectors,用于连接组织现有的数据库和 SaaS 账号。
  • 可向任意已声明 host 发出的 Outbound HTTP,从而让托管 API 替代原本在本地运行的二进制文件。
可行的改造方式:
项目当前行为建议实现方式用户看到的变化
接收 webhook 以获知某事件(支付、新 issue、表单提交)Cron 轮询 provider 的 list 或 events API。在
db
中保存最后处理的 id 或时间戳作为 cursor,并确保处理具备幂等性
最多延迟一分钟
运行 job queue(BullMQ、Celery、Sidekiq)创建一个
jobs
collection。Routes 插入
status: "queued"
的行;cron route 每次处理一小批任务,完成后标记相应行。Cron 按至少一次语义运行且可能重叠,因此应使用
ctx.invocationId
标记已领取的行,并确保副作用可以安全重复
任务在一分钟内启动,而不是立即启动
在单个 request 中执行耗时任务(大型导入、针对数千行的报表)使用
db
中的 cursor 将任务拆成多个步骤。前端循环调用 step route 并显示进度,或由 cron 推进进度。每一步应远低于约 100 次 subrequest 的限制
显示进度条,而不是加载指示器
通过 websockets 或 SSE 推送实时更新前端仅在 tab 可见时每几秒轮询一个低成本 route。返回
updated_at
,使未发生变化的轮询只产生很小的响应
更新会在轮询间隔内到达
将文本流式发送到浏览器返回 streamed
Response
;SDK 中的
toNdjson()
会负责分帧
无变化
在自有数据库中使用 SQL 进行 join 和 filter根据界面读取方式设计 key(
<userId>:<id>
、
prefix()
),存储少量重复数据,使用
query().where()
进行过滤,并持续分页直至返回较短页面。如果数据与其他系统共享,则将其保留在该数据库中,并通过 data connector 读取
如果 key 与界面匹配,则无变化
写入必须保持关系型的数据库(transactions、constraints、其他系统也会读取)保留数据库,并在 worker 中使用 secret 和 HTTPS driver 直接访问(references/databases.md)。Data connectors 是只读的,因此只能覆盖读取操作。如果数据库没有 HTTPS interface,应在其前面增加代理,或在旧 host 上保留一个小型 write service存在 HTTPS driver 时无变化
使用 Redis 或进程内存缓存使用带
expires_at
字段的
db
collection,并在读取时检查该字段。内存缓存不会在请求之间保留
无变化
使用 Redis 进行 rate limit 或 lock为每个 key 使用一行
db
记录,保存计数器和 window start。它不是原子的,因此适用于公平性控制,不适用于资金处理
无变化
对自身记录进行 full-text search对于数千条记录,可在 worker 或浏览器中加载并过滤。超出该范围时,通过 connector 查询源数据库,或通过
egress:
调用托管搜索 API
无变化
调用二进制文件(ffmpeg、ImageMagick、Chromium、pandoc)首先寻找适合 worker bundle 的纯 JavaScript library;PDF 和 spreadsheet generation 通常都适用。否则通过
egress:
调用托管 API,或将任务交给可执行代码的 managed agent
结果可能更慢或变为异步
针对 Google、Slack、GitHub 等运行自有 OAuth flow使用 connector。由管理员关联组织账号,或由每个用户关联自己的账号;worker 调用
connector(name)
,且不会看到 token
用户改为在 Railcode 中关联一次账号,而不是在应用中关联
接收邮件,或从真人或团队的邮箱地址发送邮件使用对应账号的 Gmail connector:组织账号可通过 cron 轮询并保存 cursor;个人收件箱可由 personal managed agent 按计划读取接收邮件最多延迟一分钟
需要 embeddings、vision 或
llm
gateway 不具备的其他模型功能
直接调用对应 provider:key 存放在
secrets
中,host 声明在
egress:
中
无变化
发送 push 或 chat 通知使用
email
,或使用 Slack connector 向 channel 发帖
通知通过 email 或 Slack 送达
多个内部页面中有一个公共页面(公共表单、状态页)将其拆分。公共页面继续保留在旧 host 并写入其数据库;Railcode 应用通过 data connector 读取该数据库变成两个部署,而不是一个
在服务端使用模板渲染 HTML(Jinja、ERB、EJS)使用静态前端,从
/api/*
routes 获取 JSON
无变化
docker-compose 中包含多个服务使用一个 worker 和多个 route groups。如果两部分面向不同受众,则创建两个应用无变化
良好实践的规则:
  • 说明会发生什么变化。 每一项改造通常都会牺牲某些能力,最常见的是延迟。用一句话说明并获得用户同意后再开始构建。
  • 优先采用最简单的 block。 前端轮询优于 cron,cron 优于 agent。
  • 围绕 cron 设计之前,先检查其限制:最短周期为一分钟,每个应用最多五个 schedule,没有调用者(
    ctx.user
    为
    null
    ),并且不能启动或读取 managed agent runs。如果五个 schedule 不够,一个 cron route 可以分派多种工作。
  • 不要伪造保证。 如果原实现依赖 transaction、exactly-once delivery 或对第三方的即时响应,轮询版本无法提供这些保证。这些情况将在下一节中讨论。
如果用户需要的功能不在此表中,应基于现有 building blocks 进行设计,告知用户这属于一种新模式,并进行报告(参见反馈),以便将其补充进来。

What Railcode cannot host today

Railcode 目前无法承载的功能

Some things have no workaround, because they need the internet to reach the app, a process that stays alive, or a runtime the platform does not offer. Recognise these during the inventory, not after the port.
The project needsWhy it does not fit
Inbound webhooks that must be answered — Slack slash commands and interactive buttons, Twilio voice or SMS replies, a provider that retries until it gets an acknowledgement and offers no API to pollNothing outside the organization can call the worker. A webhook that only notifies can be replaced by polling (above); one that expects the app's response cannot
A public API or public endpoints for customers, partners, mobile apps or other serversSame reason. Requests come from a signed-in member's browser or from Railcode's own agents, never from an outside system
Public or customer-facing pages: a marketing site, a storefront, self-signup, anything meant for search enginesEvery viewer is a signed-in org member
Its own identity system: logging in people who are not org members, issuing its own API keys or tokens to third partiesIdentity is the organization's membership
True real time: collaborative editing, presence, multiplayer, a websocket serverThere is no push surface. Polling covers "looks current", not "keystroke by keystroke"
A long-lived process: a daemon, a bot holding a socket open, a stream consumer (Kafka, Postgres
LISTEN
), work that must fire more often than once a minute
The worker runs per request and then stops
Non-HTTP protocols: a database driver over TCP (
pg
,
mysql2
,
ioredis
), an SMTP server, gRPC
No raw TCP in or out. Databases are reached through a data connector (reads) or an HTTPS driver with a secret (reads and writes); see references/databases.md. A database with only a socket interface and nothing in front of it cannot be reached
The container itself: a Python, Go, Ruby, Java or PHP server run as it is, system packages, native addons, a GPU, a local modelThe backend is one JavaScript module. Other languages are ported, not hosted — see the container guide
A large or multi-file backend bundle:
.wasm
modules, a worker over the size cap (10 MB; 5 MB on a server without
worker_routes
)
The worker is a single ESM module
A custom domain, a native mobile app, browser push notificationsApps are web apps at
<app>.<parent>
Its own mail domain: an inbound mail server, an address the app owns, or
email.send()
from a custom sender
email
is send-only from a platform sender. Mail through a Gmail account someone owns is supported; see Find another way
When the project needs one of these:
  1. Tell the user at once, plainly. Name the feature, and say in a sentence that it cannot run on Railcode today and why. Do not present a polling imitation of something that needs a response as if it were equivalent.
  2. Offer what is still possible. Usually the rest of the project migrates and the one piece stays where it is, sharing a database that Railcode reads through a connector. If the missing piece is the core of the project (a public storefront, a Slack bot), say the project should stay on its current host for now.
  3. Submit the request with the CLI. The Railcode team decides what to build next from these reports. Send one for each distinct missing capability, even when part of the project migrated:
    bash
    railcode agent-feedback --category suggestion \
      --message "Migration blocked on inbound webhooks. The project receives POST /webhooks/slack for slash commands and must reply within 3 seconds; there is no API to poll instead. Request: a way for an app to expose a public, signature-verified endpoint." \
      --context "Source: Express + Postgres in a container, about 40 routes. Everything else mapped to db, secrets and crons. The Slack routes stayed on the old host; the rest was migrated." \
      --agent "<your assistant name>" --model "<your model>"
    Write it so someone who has never seen the project understands the need: what the project is (stack and rough size), exactly what it needed, what you did instead, and whether the migration went ahead. Leave out credentials, customer data, source code and anything that identifies the user's customers. The command needs an existing login and prints
    Feedback accepted.
    ; all options are in
    create-railcode-app
    under "Report Railcode feedback". If it fails, tell the user the report was not sent and carry on.
  4. Tell the user you sent it, and what it said.
Do not file a request for something the platform already does a different way; check Find another way and
create-railcode-app
first.
有些功能没有可行的替代方案,因为它们需要公共互联网访问应用、需要持续运行的进程,或需要平台不提供的 runtime。应在盘点阶段识别这些问题,而不是移植完成后才发现。
项目需要不适合承载的原因
必须返回响应的入站 webhooks——Slack slash commands 和 interactive buttons、Twilio voice 或 SMS replies,以及会持续重试直至收到确认且不提供轮询 API 的 provider组织以外的任何内容都无法调用 worker。仅用于通知的 webhook 可以改为轮询(见上文);需要应用返回响应的 webhook 则不行
面向客户、合作伙伴、移动应用或其他服务器的公共 API 或公共 endpoints原因相同。请求只能来自已登录成员的浏览器或 Railcode 自身的 agents,绝不会来自外部系统
公共或面向客户的页面:营销站点、storefront、自助注册,以及任何面向搜索引擎的内容每个访问者都是已登录的组织成员
自有身份系统:允许非组织成员登录、面向第三方签发自有 API keys 或 tokens身份由组织成员资格决定
真正的实时能力:协作编辑、presence、multiplayer、websocket server没有 push surface。轮询可以保证“看起来是最新”,但无法做到逐按键更新
长驻进程:daemon、保持 socket 打开的 bot、stream consumer(Kafka、Postgres
LISTEN
),以及必须比每分钟一次更频繁执行的工作
Worker 每次 request 执行一次,随后即停止
非 HTTP 协议:基于 TCP 的 database driver(
pg
、
mysql2
、
ioredis
)、SMTP server、gRPC
不支持 raw TCP。数据库通过 data connector(读取)或配合 secret 的 HTTPS driver(读取和写入)访问;参见 references/databases.md。只有 socket interface 且前面没有任何服务的数据库无法访问
容器本身:按原样运行的 Python、Go、Ruby、Java 或 PHP server、system packages、native addons、GPU、本地模型后端是一个 JavaScript module。其他语言需要移植,而不是直接托管——参见容器指南
大型或多文件后端 bundle:
.wasm
modules、超过大小上限的 worker(10 MB;在没有
worker_routes
的 server 上为 5 MB)
Worker 是单个 ESM module
自定义域名、原生移动应用、浏览器 push notificationsApps 是部署在
<app>.<parent>
下的 web apps
自有邮件域名:入站 mail server、应用拥有的地址,或使用自定义 sender 调用
email.send()
email
只能使用平台 sender 发送邮件。支持通过某人拥有的 Gmail account 发送邮件;参见寻找替代方式
当项目需要上述能力时:
  1. 立即且明确地告知用户。 指明具体功能,并用一句话说明它目前无法在 Railcode 上运行及其原因。不要把需要返回响应的 webhook 伪装成与原功能等价的轮询实现。
  2. 提供仍然可行的方案。 通常可以迁移项目的其余部分,只让缺失的部分继续留在原 host,并通过 connector 让 Railcode 读取共享的数据库。如果缺失部分正是项目的核心(例如公共 storefront 或 Slack bot),则应说明项目目前应继续保留在当前 host。
  3. 使用 CLI 提交请求。 Railcode 团队会根据这些报告决定接下来构建什么。针对每项不同的缺失能力分别提交一份报告,即使项目只有一部分完成迁移:
    bash
    railcode agent-feedback --category suggestion \
      --message "Migration blocked on inbound webhooks. The project receives POST /webhooks/slack for slash commands and must reply within 3 seconds; there is no API to poll instead. Request: a way for an app to expose a public, signature-verified endpoint." \
      --context "Source: Express + Postgres in a container, about 40 routes. Everything else mapped to db, secrets and crons. The Slack routes stayed on the old host; the rest was migrated." \
      --agent "<your assistant name>" --model "<your model>"
    撰写内容时,应确保从未接触过该项目的人也能理解需求:项目是什么(技术栈和大致规模)、确切需要什么、你改用了什么,以及迁移是否继续进行。不要包含 credentials、客户数据、源代码或任何能够识别用户客户的信息。该命令需要已有登录,并会输出
    Feedback accepted.
    ;所有选项列于
    create-railcode-app
    中的“Report Railcode feedback”。如果执行失败,应告知用户报告未发送成功,并继续后续工作。
  4. 告知用户报告已发送,以及报告的具体内容。
如果平台已经以其他方式支持某项功能,不要提交请求;应先检查寻找替代方式 和
create-railcode-app
。

Machine safety

机器安全

Framework builds are heavy, and a migration runs many of them.
  • Run one build or dev server at a time, and stop every process you start before finishing a turn. Check with
    ps
    rather than assuming.
  • Never point a
    package.json
    build
    script at something that calls the framework's adapter if that adapter runs
    npm run build
    itself. That is an unbounded chain of builds. The Next.js guide has the specific rule.
  • Do not start the project's docker-compose stack to see how it works unless the user asks. Read the code.
框架构建开销较大,而一次迁移会执行许多次构建。
  • 每次只运行一个 build 或 dev server,并在本轮结束前停止所有已启动的进程。使用
    ps
    检查,不要凭空假设。
  • 绝不要让
    package.json
    的
    build
    script 指向某个 adapter,而该 adapter 自身又会调用
    npm run build
    。这会造成无限循环的构建链。Next.js 指南中有具体规则。
  • 除非用户明确要求,否则不要启动项目的 docker-compose 技术栈来了解其行为。请阅读代码。

Feedback

反馈

After every migration, report concrete friction with
railcode agent-feedback
(usage above and in
create-railcode-app
), one report per finding: what the source project used, what had no equivalent, which rebuilt pattern you used, and what broke that the guide did not predict. A missing capability is
--category suggestion
; a wrong or unclear step in this skill is
--category friction
. That is how the next guide gets written.
每次迁移完成后,使用
railcode agent-feedback
(用法见上文及
create-railcode-app
)报告实际遇到的具体障碍,每个发现单独提交一份:源项目使用了什么、什么没有对应物、你采用了哪种重建模式,以及哪些问题超出了本指南的预期。缺失能力使用
--category suggestion
;本 skill 中错误或不清晰的步骤使用
--category friction
。下一版指南将据此编写。