Back to Details

vpc-air-gapped

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deploying Rivet in a VPC or Air-Gapped Network

在VPC或隔离网络中部署Rivet

IMPORTANT: Before doing anything, you MUST read 
BASE_SKILL.md
in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.
Patterns for running self-hosted Rivet inside a private network: a VPC without internet egress, an on-premises rack, or a fully air-gapped environment. The engine is one service, the recommended single-node storage backend is the local file system, and the engine makes no outbound connections by default. Self-hosting is the only Rivet deployment model that supports air-gapped networks; see the Self-Hosting Overview for the full comparison with BYOC.
重要提示：在进行任何操作之前，您必须阅读本技能目录中的
BASE_SKILL.md
。它包含有关调试、错误处理、状态管理、部署和项目设置的重要指南。这些规则和模式适用于所有RivetKit工作。以下所有内容均假设您已阅读并理解该文档。
在私有网络内运行自托管Rivet的模式：无互联网出口的VPC、本地机架或完全隔离的环境。引擎是一个服务，推荐的单节点存储后端是本地文件系统，且引擎默认不建立对外连接。自托管是唯一支持隔离网络的Rivet部署模式；请参阅自托管概述了解与BYOC的完整对比。

What Runs Inside the Perimeter

网络边界内运行的组件

A self-hosted deployment has three components, all of which live inside your network:
ComponentRoleInside the perimeter
Your backendYour application server, including the runner that executes actor codeYes
Rivet EngineOrchestration service that manages actor lifecycle, routes messages, and serves the dashboard and APIsYes
StoragePersistence for actor state. Local file system for single-node, PostgreSQL or FoundationDB for multi-nodeYes
There is no license server, no Rivet Cloud account, and no callback to 
rivet.dev
. Clients inside the perimeter reach actors through the engine's gateway over your private network. See Architecture.
自托管部署包含三个组件，全部位于您的网络内：
组件角色是否在网络边界内
您的后端您的应用服务器，包括执行actor代码的运行器是
Rivet Engine编排服务，用于管理actor生命周期、路由消息，并提供仪表板和API是
存储用于持久化actor状态。单节点部署使用本地文件系统，多节点部署使用PostgreSQL或FoundationDB是
这里没有许可证服务器、Rivet Cloud账户，也不会回调到
rivet.dev
。网络边界内的客户端通过引擎网关在私有网络中访问actor。请参阅架构。

Single-Binary Install

单二进制文件安装

The engine compiles to a single 
rivet-engine
binary. Build it from source outside the perimeter, then copy the binary across the boundary:
bash
git clone https://github.com/rivet-dev/rivet.git
cd rivet
cargo build --release -p rivet-engine
引擎编译为单个
rivet-engine
二进制文件。在网络边界外从源代码构建，然后将二进制文件复制到边界内：
bash
git clone https://github.com/rivet-dev/rivet.git
cd rivet
cargo build --release -p rivet-engine

Copy target/release/rivet-engine into the perimeter.

将target/release/rivet-engine复制到网络边界内。


Prebuilt binaries are coming soon; see [Installing Rivet Engine](/docs/self-hosting/install) for current options.

Run it with the file system backend, which stores everything on local disk and is the production-ready choice for single-node deployments. The [File System](/docs/self-hosting/filesystem) docs list air-gapped environments as a primary use case because it needs no database infrastructure:

```bash
RIVET__database__file_system__path="/var/lib/rivet/data" ./rivet-engine
Configuration can also come from files. The engine discovers config at 
/etc/rivet/config.json
on Linux (JSON, JSON5, JSONC, YAML, and YML are all supported), and 
--config
overrides the path. Environment variables use the 
RIVET__
prefix with 
__
as the separator. See Configuration.
The engine serves its own dashboard on port 
6420
, so inspection and namespace management work with nothing but a browser inside the perimeter.

预构建二进制文件即将推出；有关当前选项，请参阅[安装Rivet Engine](/docs/self-hosting/install)。

使用文件系统后端运行，它将所有内容存储在本地磁盘上，是单节点部署的生产就绪选择。[文件系统](/docs/self-hosting/filesystem)文档将隔离环境列为主要用例，因为它不需要数据库基础设施：

```bash
RIVET__database__file_system__path="/var/lib/rivet/data" ./rivet-engine
配置也可来自文件。引擎会在Linux系统的
/etc/rivet/config.json
中查找配置（支持JSON、JSON5、JSONC、YAML和YML格式），
--config
参数可覆盖路径。环境变量使用
RIVET__
前缀，以
__
作为分隔符。请参阅配置。
引擎在端口
6420
上提供自己的仪表板，因此只需使用网络边界内的浏览器即可进行检查和命名空间管理。

Docker Compose Deployment

Docker Compose部署

For Docker hosts without registry access, move the engine image across the boundary the standard way:
bash
undefined
对于没有注册表访问权限的Docker主机，按标准方式将引擎镜像复制到边界内：
bash
undefined

Outside the perimeter.

在网络边界外。

docker pull rivetdev/engine:latest docker save rivetdev/engine:latest -o rivet-engine.tar
docker pull rivetdev/engine:latest docker save rivetdev/engine:latest -o rivet-engine.tar

Inside the perimeter.

在网络边界内。

docker load -i rivet-engine.tar

Then run the engine and your app together in one Compose file:

```yaml
services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - rivet-data:/data
    environment:
      RIVET__FILE_SYSTEM__PATH: "/data"
    restart: unless-stopped

  my-app:
    build: .
    environment:
      RIVET_ENDPOINT: "http://default:admin@rivet-engine:6420"
    depends_on:
      - rivet-engine
    restart: unless-stopped

volumes:
  rivet-data:
RIVET_ENDPOINT
uses the format 
http://namespace:token@host:port
and tells your app to connect to the engine as a runner instead of running standalone. After both services start, register your runner with the engine through the dashboard or its API. The full walkthrough, including PostgreSQL setup for multi-node deployments, is in Docker Compose.
docker load -i rivet-engine.tar

然后在同一个Compose文件中一起运行引擎和您的应用：

```yaml
services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - rivet-data:/data
    environment:
      RIVET__FILE_SYSTEM__PATH: "/data"
    restart: unless-stopped

  my-app:
    build: .
    environment:
      RIVET_ENDPOINT: "http://default:admin@rivet-engine:6420"
    depends_on:
      - rivet-engine
    restart: unless-stopped

volumes:
  rivet-data:
RIVET_ENDPOINT
使用
http://namespace:token@host:port
格式，告知您的应用作为运行器连接到引擎，而非独立运行。两个服务启动后，通过仪表板或API向引擎注册您的运行器。包括多节点部署的PostgreSQL设置在内的完整指南，请参阅Docker Compose。

No Outbound Telemetry

无对外遥测

The engine exports traces and metrics only when you opt in with OpenTelemetry. Export is disabled unless 
RIVET_OTEL_ENABLED=1
is set, and the export target defaults to a local collector at 
http://localhost:4317
. With no configuration, nothing crosses the perimeter.
When you want observability, keep it inside the network:
  • Set 
    RIVET_OTEL_ENABLED=1
    and point 
    RIVET_OTEL_GRPC_ENDPOINT
    at a collector you run inside the perimeter.
  • Adjust 
    RIVET_OTEL_SAMPLER_RATIO
    to control trace sampling.
  • Use the engine's health endpoint for liveness and readiness probes.
See the Production Checklist for monitoring guidance.
仅当您通过OpenTelemetry选择启用时，引擎才会导出跟踪和指标。除非设置
RIVET_OTEL_ENABLED=1
，否则导出功能处于禁用状态，导出目标默认为本地收集器
http://localhost:4317
。无配置时，不会有任何数据跨越网络边界。
当您需要可观测性时，将其保留在网络内：
  • 设置
    RIVET_OTEL_ENABLED=1
    ，并将
    RIVET_OTEL_GRPC_ENDPOINT
    指向您在网络边界内运行的收集器。
  • 调整
    RIVET_OTEL_SAMPLER_RATIO
    以控制跟踪采样率。
  • 使用引擎的健康端点进行存活和就绪探测。
有关监控指南，请参阅生产检查清单。

Embedding Rivet in a Customer's Environment

在客户环境中嵌入Rivet

If you ship software that runs inside your customers' VPCs, the same setup turns Rivet into an internal component of your product rather than a service your customers must reach over the internet:
  • Ship the engine next to your app. Add 
    rivetdev/engine
    to the Compose file or chart you already deliver. Your app finds it over the private network via 
    RIVET_ENDPOINT
    , so one artifact deploys the whole stack.
  • One namespace per install. The endpoint URL carries the namespace and token (
    http://namespace:token@host:port
    ), so a single image works across customer deployments. See Endpoints.
  • Generate a strong admin token per install. Replace the default token and keep it server-side. Never include the admin token in 
    RIVET_PUBLIC_ENDPOINT
    or anywhere clients can read it.
  • Public endpoint only when needed. 
    RIVET_PUBLIC_ENDPOINT
    with a public (
    pk_
    ) token is only required when browser clients connect to actors in serverless runtime mode. Backend-only deployments can skip it entirely.
  • TLS at the customer's edge. Terminate TLS with the customer's reverse proxy or load balancer in front of the engine.
如果您交付的软件在客户的VPC内运行，相同的设置可将Rivet转变为产品的内部组件，而非客户必须通过互联网访问的服务：
  • 将引擎与应用一起交付。将
    rivetdev/engine
    添加到您已交付的Compose文件或图表中。您的应用通过
    RIVET_ENDPOINT
    在私有网络中找到它，因此一个工件即可部署整个堆栈。
  • 每个安装使用一个命名空间。端点URL包含命名空间和令牌（
    http://namespace:token@host:port
    ），因此单个镜像可用于多个客户部署。请参阅端点。
  • 为每个安装生成强管理员令牌。替换默认令牌并将其保存在服务器端。切勿将管理员令牌包含在
    RIVET_PUBLIC_ENDPOINT
    或客户端可读取的任何位置。
  • 仅在需要时使用公共端点。只有当浏览器客户端以无服务器运行时模式连接到actor时，才需要带有公共（
    pk_
    ）令牌的
    RIVET_PUBLIC_ENDPOINT
    。仅后端部署可完全跳过它。
  • 在客户边缘终止TLS。通过引擎前端的客户反向代理或负载均衡器终止TLS。

Scaling Past One Node

扩展到多节点

BackendUse whenStatus
File System (RocksDB-based)Single-node deployments, including air-gapped installsProduction-ready, single node only
PostgreSQLMulti-node deploymentsRecommended for multi-node today, but experimental
FoundationDBLargest production deploymentsEnterprise
For multi-node deployments, run two or more engine nodes behind a load balancer and add NATS for pub/sub, which replaces the default PostgreSQL 
LISTEN
/
NOTIFY
path at high throughput. Neither is needed for a single-node file system install. See the Production Checklist.
后端使用场景状态
文件系统（基于RocksDB）单节点部署，包括隔离环境安装生产就绪，仅支持单节点
PostgreSQL多节点部署目前推荐用于多节点，但处于实验阶段
FoundationDB大型生产部署企业版
对于多节点部署，在负载均衡器后运行两个或更多引擎节点，并添加NATS用于发布/订阅，这在高吞吐量时替代默认的PostgreSQL 
LISTEN
/
NOTIFY
路径。单节点文件系统安装不需要这两者。请参阅生产检查清单。

Perimeter Checklist

网络边界检查清单

  • Admin token: Generate a strong, random token for engine authentication and verify it is not exposed to clients.
  • TLS termination: Encrypt connections to the engine via a reverse proxy or load balancer.
  • No public exposure: Keep port 
    6420
    reachable only from inside the perimeter unless clients outside it genuinely need access.
  • Health checks: Configure liveness and readiness probes against the engine health endpoint.
  • Telemetry: Leave OpenTelemetry export off, or point it at a collector inside the network.
  • Backups: With the file system backend, back up the data directory. With PostgreSQL, configure automated backups and failover.
  • 管理员令牌：生成强随机令牌用于引擎认证，并验证其未暴露给客户端。
  • TLS终止：通过反向代理或负载均衡器加密与引擎的连接。
  • 不公开暴露：仅在外部客户端确实需要访问时，才让端口
    6420
    可从网络边界外访问，否则仅保留内部可达性。
  • 健康检查：针对引擎健康端点配置存活和就绪探测。
  • 遥测：关闭OpenTelemetry导出，或将其指向网络内的收集器。
  • 备份：使用文件系统后端时，备份数据目录。使用PostgreSQL时，配置自动备份和故障转移。

Full Configuration

完整配置

Reference Map

参考地图

Actors

Actors

  • Access Control
  • Actions
  • Actor Keys
  • Actor Scheduling
  • Actor Statuses
  • AI and User-Generated Rivet Actors
  • Authentication
  • Communicating Between Actors
  • Connections
  • Custom Inspector Tabs
  • Debugging
  • Design Patterns
  • Destroying Actors
  • Errors
  • Fetch and WebSocket Handler
  • Helper Types
  • Icons & Names
  • Input Parameters
  • Lifecycle
  • Limits
  • Low-Level HTTP Request Handler
  • Low-Level KV Storage
  • Low-Level WebSocket Handler
  • Metadata
  • Next.js Quickstart
  • Node.js & Bun Quickstart
  • Queues & Run Loops
  • React Quickstart
  • Realtime
  • Rust Quickstart (Preview)
  • Sandbox Actor
  • Scaling & Concurrency
  • Sharing and Joining State
  • SQLite
  • SQLite + Drizzle
  • State & Storage
  • Testing
  • Troubleshooting
  • Types
  • Vanilla HTTP API
  • Versions & Upgrades
  • Workflows
  • 访问控制
  • 操作
  • Actor密钥
  • Actor调度
  • Actor状态
  • AI和用户生成的Rivet Actors
  • 认证
  • Actor间通信
  • 连接
  • 自定义检查器标签
  • 调试
  • 设计模式
  • 销毁Actors
  • 错误
  • Fetch和WebSocket处理器
  • 辅助类型
  • 图标与名称
  • 输入参数
  • 生命周期
  • 限制
  • 底层HTTP请求处理器
  • 底层KV存储
  • 底层WebSocket处理器
  • 元数据
  • Next.js快速入门
  • Node.js & Bun快速入门
  • 队列与运行循环
  • React快速入门
  • 实时功能
  • Rust快速入门（预览版）
  • 沙箱Actor
  • 扩展与并发
  • 状态共享与合并
  • SQLite
  • SQLite + Drizzle
  • 状态与存储
  • 测试
  • 故障排除
  • 类型
  • 原生HTTP API
  • 版本与升级
  • 工作流

Agent Os

Agent Os

  • Agent-to-Agent Communication
  • agentOS vs Sandbox
  • Authentication
  • Benchmarks
  • Configuration
  • Core Package
  • Cron Jobs
  • Deployment
  • Embedded LLM Gateway
  • Events
  • Filesystem
  • Limitations
  • LLM Credentials
  • Multiplayer
  • Networking & Previews
  • Overview
  • Permissions
  • Persistence & Sleep
  • Pi
  • Processes & Shell
  • Queues
  • Quickstart
  • Sandbox Mounting
  • Security & Auth
  • Security Model
  • Sessions
  • Software
  • SQLite
  • System Prompt
  • Tools
  • Webhooks
  • Workflow Automation
  • Agent间通信
  • agentOS vs 沙箱
  • 认证
  • 基准测试
  • 配置
  • 核心包
  • 定时任务
  • 部署
  • 嵌入式LLM网关
  • 事件
  • 文件系统
  • 限制
  • LLM凭证
  • 多人协作
  • 网络与预览
  • 概述
  • 权限
  • 持久化与休眠
  • Pi
  • 进程与Shell
  • 队列
  • 快速入门
  • 沙箱挂载
  • 安全与认证
  • 安全模型
  • 会话
  • 软件
  • SQLite
  • 系统提示词
  • 工具
  • Webhooks
  • 工作流自动化

Clients

Clients

  • Node.js & Bun
  • React
  • Swift
  • SwiftUI
  • Node.js & Bun
  • React
  • Swift
  • SwiftUI

Connect

Connect

  • Deploy To Amazon Web Services Lambda
  • Deploying to AWS ECS
  • Deploying to Cloudflare Workers
  • Deploying to Freestyle
  • Deploying to Google Cloud Run
  • Deploying to Hetzner
  • Deploying to Kubernetes
  • Deploying to Railway
  • Deploying to Rivet Compute
  • Deploying to Supabase Functions
  • Deploying to Vercel
  • Deploying to VMs & Bare Metal
  • 部署到Amazon Web Services Lambda
  • 部署到AWS ECS
  • 部署到Cloudflare Workers
  • 部署到Freestyle
  • 部署到Google Cloud Run
  • 部署到Hetzner
  • 部署到Kubernetes
  • 部署到Railway
  • 部署到Rivet Compute
  • 部署到Supabase Functions
  • 部署到Vercel
  • 部署到虚拟机与裸机

Cookbook

Cookbook

  • AI Agent
  • AI Agent Workspaces
  • Chat Room
  • Collaborative Text Editor
  • Cron Jobs and Scheduled Tasks
  • Database per Tenant
  • Deploying Rivet in a VPC or Air-Gapped Network
  • Live Cursors and Presence
  • Multiplayer Game
  • AI Agent
  • AI Agent工作区
  • 聊天室
  • 协作文本编辑器
  • 定时任务与计划任务
  • 租户专属数据库
  • 在VPC或隔离网络中部署Rivet
  • 实时光标与在线状态
  • 多人游戏

General

General

  • Actor Configuration
  • Architecture
  • Cross-Origin Resource Sharing
  • Documentation for LLMs & AI
  • Edge Networking
  • Endpoints
  • Environment Variables
  • HTTP Server
  • Logging
  • Pool Configuration
  • Production Checklist
  • Registry Configuration
  • Runtime Modes
  • Actor配置
  • 架构
  • 跨域资源共享
  • 面向LLM与AI的文档
  • 边缘网络
  • 端点
  • 环境变量
  • HTTP服务器
  • 日志
  • 池配置
  • 生产检查清单
  • 注册表配置
  • 运行时模式

Self Hosting

Self Hosting

  • Configuration
  • Docker Compose
  • Docker Container
  • File System
  • FoundationDB (Enterprise)
  • Installing Rivet Engine
  • Kubernetes
  • Multi-Region
  • PostgreSQL
  • Production Checklist
  • Railway Deployment
  • Render Deployment
  • TLS & Certificates
  • 配置
  • Docker Compose
  • Docker容器
  • 文件系统
  • FoundationDB（企业版）
  • 安装Rivet Engine
  • Kubernetes
  • 多区域部署
  • PostgreSQL
  • 生产检查清单
  • Railway部署
  • Render部署
  • TLS与证书