ObjectOS架构
你实际运行的是什么 —— 写给评估是否引入它的工程师。
架构
一个实用视角，帮你看清部署 ObjectOS 后你的机器上跑了什么、什么数据离开了你的网络、什么数据没有。
心智模型是两层薄薄的东西：
- 元数据 —— 对象 / 视图 / Action / 流程 / Agent 的打包。大部分由 AI Builder 通过沙箱工具 API 编写；偶尔人工编辑，始终版本化并被审计。
- 单一 Node.js 运行时，将元数据解释为一个可工作的应用 —— REST API、Console UI、权限、任务、AI 工具 —— 全部在同一个进程内，与你的数据库对话。
没有代码生成步骤，没有从 "用户描述需求" 到 "已上线" 之间的部署流水线。运行时在 HITL 审批后热加载新元数据。
你部署的是什么
每个 ObjectOS 实例对应一个 Node.js 进程。就这些。
┌─────────────────────────────────────────────────────┐
│ ObjectOS 进程 │
│ ┌───────────────────────────────────────────────┐ │
│ │ HTTP 分发器 (/ · /api · /_console …) │ │
│ ├───────────────────────────────────────────────┤ │
│ │ 每项目 ObjectKernel（LRU 缓存） │ │
│ │ ├─ Auth (Better Auth) │ │
│ │ ├─ Security（RBAC + 行级 + 字段级） │ │
│ │ ├─ ObjectQL（数据引擎，生成 SQL） │ │
│ │ ├─ REST API 生成器 │ │
│ │ └─ 按产物加载的能力 │ │
│ │ （审计、存储、任务、队列、AI……） │ │
│ └───────────────────────────────────────────────┘ │
└──────────┬──────────────────────────────────────────┘
│
▼
你的业务数据库
(Postgres / MySQL / SQLite / Turso / MongoDB)复杂度相当于一个静态链接的二进制。没有 sidecar、没有 Kafka、不需要独立缓存层。需要时再加；第一天别为它们付费。
你的数据存放在哪里
| 数据 | 存放在 | 是否离开你的网络？ |
|---|---|---|
| 业务记录 | 你的数据库 | 否 |
| 用户账号、会话、OAuth Token | 你的数据库 | 否 |
| 审计日志 | 你的数据库 | 否 |
| 设置、API Key、密钥 | 你的数据库 / 密钥管理器 | 否 |
| 上传的文件 | 你的磁盘或 S3/R2 桶 | 否 |
编译后的应用定义（objectstack.json） | 磁盘上的一个文件，或从你的控制面拉取 | 可选 |
ObjectOS 不会回拨电话。无遥测。无授权检查。如果你完全切断互联网，它会持续运行。参见 Air-gapped。
一个请求如何被服务
1. 入口 / TLS 终结 （你的负载均衡器）
2. HTTP 分发器 （安全头、请求 ID）
3. 主机名 → 项目解析 （带缓存，TTL 可配）
4. 从 LRU 中获取或构建对应项目的内核
5. AuthPlugin —— 会话 Cookie、Bearer Token 或 API Key
6. SecurityPlugin —— RBAC + 行级 + 字段级检查
7. 路由处理 —— 自动生成的 REST、声明式 Action 或自定义
8. 数据驱动 —— ObjectQL 编译为 SQL / Mongo 查询
9. 响应携带 X-Request-Id内核热起来后，步骤 4-8 通常在 5ms 内执行完。
三个层级（只在你做集成时才重要）
大多数客户只部署 ObjectOS。如果你想知道产物从哪里来，另外两层就在这里：
| 层级 | 是什么 | 运行在哪 |
|---|---|---|
框架 (@objectstack/*) | 开源内核、ObjectQL、插件、驱动 | npm —— 构建时引入 |
| 控制面（可选） | 发布编译后的 objectstack.json 产物；可使用托管的 ObjectStack Cloud、自建，或完全不要 | 你的 CI、我们的云，或你的笔记本 |
| ObjectOS | 你运维的运行时 | 你的基础设施 |
如果你只发布单个应用，根本不需要控制面 —— 在 CI 里把 objectstack.config.ts → dist/objectstack.json 编译出来打进镜像即可。如果你要运营一个面向多租户多应用的内部应用市场，目录就放在控制面。
启动模式
| 模式 | 何时 | 如何 |
|---|---|---|
| Standalone | 单应用、开发、评估、气隙、大多数生产部署 | pnpm dev 或从磁盘运行 dist/objectstack.json |
| File-backed | 由外部管理产物的生产环境 | 设置 OS_ARTIFACT_FILE=/path/to/objectstack.json |
| Cloud-connected | 由控制面驱动的多租户/多应用部署 | 设置 OS_CLOUD_URL + OS_CLOUD_API_KEY |
模式由环境变量自动检测。
性能特征
| 指标 | 数值 |
|---|---|
| 冷启动（进程起来、可接流量） | ~1 秒 |
| 每个内核预热（首次请求该项目） | 50-300ms，视能力而定 |
| 热请求延迟（REST 走 CRUD） | 通常 < 10ms + 数据库延迟 |
| 内存占用 | 基础 ~150MB；每个活跃项目内核 ~10-30MB |
| 单实例并发项目数 | 受 OS_KERNEL_CACHE_SIZE 限制（默认 32） |
为什么是这种形态
- 一个 Node 进程，无 sidecar → 适合
docker run、适合 systemd 单元、适合 Lambda 类环境。 - 每项目内核，LRU 缓存 → 一个实例可以服务多个小应用，且不必为每次请求付预热成本。
- 基于声明元数据生成 API → CI 中没有 codegen 步骤，无需发布客户端 SDK；API 按构造与你的数据模型一致。
- 所有能力都是可选插件 → 镜像大小随你实际用到的部分而扩张。
下一步
- Production Readiness —— 上真实流量前的清单。
- Runtime Configuration —— 数据库、缓存、密钥接线。
- Runtime Capabilities —— 有哪些可选包以及它们启用什么。