cmux-backend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux Backend

cmux 后端开发

Use this skill for backend TypeScript, Cloud VM, provider, database, auth, rate-limit, retry, timeout, or telemetry work.

当进行后端TypeScript、云VM、服务商、数据库、认证、速率限制、重试、超时或遥测相关工作时，使用此技能。

Core rules

核心规则

Default backend TypeScript to Effect under
```
web/app/api/**
```
,
```
web/services/**
```
, and backend scripts that touch providers, databases, auth, rate limits, retries, timeouts, or telemetry.
Keep Next route handlers thin: parse the request, run one Effect program at the boundary, map typed errors to HTTP responses, and treat unexpected defects separately.
Use plain TypeScript only for trivial data shapes, constants, config files, frontend React code, or small glue where Effect would add ceremony without improving failure handling.
Cloud VM backend logic must stay in Vercel route handlers and Effect services backed by Postgres.
Do not reintroduce Rivet or a raw actor protocol for Cloud VM unless a later architecture doc explicitly changes the control plane.
Production and staging Cloud VM Postgres use the Vercel Marketplace AWS Aurora PostgreSQL OIDC/RDS IAM path.

Runtime env names are

CMUX_DB_DRIVER=aws-rds-iam

AWS_ROLE_ARN

AWS_REGION

PGHOST

PGPORT

PGUSER

, and

PGDATABASE

Run production/staging migrations with
```
bun db:migrate:aws-rds-iam
```
; never run Drizzle migrations from Vercel build or route startup.
Local development keeps using the
```
CMUX_PORT
```
-derived Docker Postgres path from
```
bun dev
```
.
Cloud VM create pricing gates should use Stack Auth team payment items when enabled.
Postgres remains the source of truth for VM lifecycle, active VM limits, idempotency, and usage events.

在
```
web/app/api/**
```
、
```
web/services/**
```
目录下，以及涉及服务商、数据库、认证、速率限制、重试、超时或遥测的后端脚本中，默认使用Effect作为后端TypeScript开发框架。
保持Next路由处理器轻量化：解析请求，在边界处运行一个Effect程序，将类型化错误映射为HTTP响应，并单独处理意外异常。
仅在处理简单数据结构、常量、配置文件、前端React代码，或Effect会增加冗余而无法提升故障处理能力的小型粘合代码时，使用纯TypeScript。
云VM后端逻辑必须保留在Vercel路由处理器和基于Postgres的Effect服务中。
除非后续架构文档明确更改控制平面，否则不要为云VM重新引入Rivet或原始actor协议。
生产和预发布环境的云VM Postgres采用Vercel Marketplace的AWS Aurora PostgreSQL OIDC/RDS IAM路径。

运行时环境变量为

CMUX_DB_DRIVER=aws-rds-iam

、

AWS_ROLE_ARN

、

AWS_REGION

、

PGHOST

、

PGPORT

、

PGUSER

和

PGDATABASE

。

使用
```
bun db:migrate:aws-rds-iam
```
执行生产/预发布环境的迁移；绝不要从Vercel构建或路由启动时运行Drizzle迁移。
本地开发仍使用
```
bun dev
```
中基于
```
CMUX_PORT
```
的Docker Postgres路径。
当启用Stack Auth团队付费项时，云VM创建的付费限制应使用该功能。
Postgres始终是VM生命周期、活跃VM限制、幂等性和使用事件的唯一可信数据源。

Secrets

密钥管理

Cloud VM build, test, and local dev scripts use provider secrets from

~/.secrets/cmux.env

```
E2B_API_KEY
```
```
FREESTYLE_API_KEY
```
R2 upload vars used by
```
web/scripts/build-cloud-vm-images.ts
```
when creating Freestyle snapshots

Load them with:

bash

set -a
source ~/.secrets/cmux.env
set +a

~/.secrets/cmuxterm-dev.env

is for local Stack/web env and does not contain the provider build keys.

bun dev

sources

~/.secrets/cmux.env

first when present, then

~/.secrets/cmuxterm-dev.env

so cmuxterm-specific Stack settings override broader cmux secrets. The web dev loader still accepts the legacy

~/.secret/cmuxterm.env

and

~/.secrets/cmuxterm.env

paths while machines migrate.

云VM构建、测试和本地开发脚本使用

~/.secrets/cmux.env

中的服务商密钥。

```
E2B_API_KEY
```
```
FREESTYLE_API_KEY
```
创建Freestyle快照时，
```
web/scripts/build-cloud-vm-images.ts
```
使用的R2上传变量

通过以下方式加载：

bash

set -a
source ~/.secrets/cmux.env
set +a

~/.secrets/cmuxterm-dev.env

用于本地Stack/web环境，不包含服务商构建密钥。当

~/.secrets/cmux.env

存在时，

bun dev

会先加载它，再加载

~/.secrets/cmuxterm-dev.env

，因此cmuxterm专属的Stack设置会覆盖通用的cmux密钥。在机器迁移期间，web开发加载器仍兼容旧路径

~/.secret/cmuxterm.env

和

~/.secrets/cmuxterm.env

。

Detailed references

详细参考文档

Read references/effect-boundaries.md when shaping route handlers, services, typed errors, retries, or dependency injection.
Read references/cloud-vm-control-plane.md when touching VM lifecycle, migrations, Postgres, provider idempotency, or pricing gates.

当设计路由处理器、服务、类型化错误、重试或依赖注入时，请阅读references/effect-boundaries.md。
当涉及VM生命周期、迁移、Postgres、服务商幂等性或付费限制时，请阅读references/cloud-vm-control-plane.md。