ObjectOS运行时配置
配置 artifact 加载、项目解析、数据库、缓存以及运行时 secret。
运行时配置
ObjectOS 的运行时配置回答三个问题：
- 该请求应服务于哪个项目？
- 已编译的 artifact 在哪里？
- 该项目应使用哪个数据库与哪些运行时服务？
启动模式
| 模式 | 适用场景 | 关键配置 |
|---|---|---|
| Standalone | 无配置直接执行 os start —— 快速演示、空 kernel、约 23 个插件、本地 SQLite 位于 ~/.objectstack/data/standalone.db | 无（使用默认） |
| File-backed | 单项目、演示、客户离线包、内网/离线部署 | OS_ARTIFACT_FILE |
| Cloud-connected | 托管或私有控制面发布项目 artifact | OS_CLOUD_URL、OS_PROJECT_ID 或主机名解析 |
Standalone 模式
在无配置或 artifact 的情况下执行 os start 时的默认行为。ObjectOS 启动一个空 kernel，加载平台插件（auth、security、audit、storage、webhooks、mcp-server、marketplace-proxy、marketplace-install-local ……），打开 ~/.objectstack/data/standalone.db 的本地 SQLite，并提供 Console 与 Account。
从 Console 的 marketplace 标签页安装应用即可在 kernel 中填充对象、视图和流程 —— 无需重建、无需重启。适合演示、评估以及"看看这玩意能干啥"的探索。
os start 会自动升级：
| 检测到 | 行为 |
|---|---|
| 什么都没有 | Standalone 模式（如上） |
当前目录有 objectstack.config.ts | Project 模式 —— 自动编译，HOME=<cwd>/.objectstack |
| 当前目录有已编译 artifact | Artifact 模式 —— 加载该 artifact |
显式 --artifact <path> 或 OS_CLOUD_URL | File-backed / cloud-connected 模式 |
File-backed 模式
设置：
OS_ARTIFACT_FILE=/artifacts/objectstack.jsonObjectOS 使用本地 Artifact API 客户端。所有主机名都解析到同一个项目。运行时配置在 artifact 中存在时从其中读取，否则回退到本地默认值用于评估。
OS_ARTIFACT_FILE 是 ObjectOS app-wrapper 的约定。底层运行时也直接接受 OS_ARTIFACT_PATH（被 @objectstack/cli 的 dev 和 start 命令以及框架的 standalone stack 使用）。两者设置其一即可——不要同时设置。
可选：
OS_ENVIRONMENT_ID=env_prod # 或旧别名 OS_PROJECT_ID
OS_WATCH_ARTIFACT=1watch 模式仅用于开发或冒烟测试。
Cloud-connected 模式
设置：
OS_CLOUD_URL=https://cloud.example.com
OS_CLOUD_API_KEY=replace-with-deployment-tokenObjectOS 请求控制面：
- 把主机名解析为项目/环境；
- 拉取当前 artifact；
- 接收该项目的运行时数据库配置。
ObjectOS 不应直接连接控制面数据库。
认证 secret
设置一个强随机基础 secret：
OS_AUTH_SECRET=replace-with-a-strong-random-secretObjectOS 由此派生每个项目的认证 secret。这样会话签名按项目隔离，同时仍可在重启后保持。轮换该值会使现有会话失效。
Kernel 与 artifact 缓存
ObjectOS 缓存已解析的环境和项目 kernel，避免每次请求都重建 kernel。
| 变量 | 默认值 | 用途 |
|---|---|---|
OS_KERNEL_CACHE_SIZE | 32 | 缓存的项目 kernel 最大数 |
OS_KERNEL_TTL_MS | 900000 | 缓存 kernel 的空闲 TTL |
OS_ENV_CACHE_TTL_MS | 300000 | 主机名/环境解析缓存 |
OS_ARTIFACT_CACHE_TTL_MS | 300000 | Artifact 响应缓存 |
更低的 TTL 让变更更快可见；更高的 TTL 降低控制面流量和冷启动。
数据库配置
在 cloud-connected 模式下，控制面把每个项目的运行时数据库配置随 artifact 响应一起返回。
在 file-backed 模式下，ObjectOS 可以根据 artifact 的数据源声明派生数据库设置。支持的框架驱动包括 SQLite、PostgreSQL、MySQL、MongoDB 以及内存评估驱动。
生产环境请使用客户托管的数据库。不要把业务数据放在容器本地存储中，除非该部署明确是单节点评估。