ObjectOS环境变量
ObjectOS 运行时环境变量参考。
环境变量
使用环境变量进行部署级配置和密钥管理。 使用系统设置进行租户/用户可编辑的应用配置。
命名。 所有 ObjectStack 自有变量统一使用
OS_前缀。1.0 之前的无前缀名称（PORT、AUTH_SECRET、OS_MULTI_TENANT等）仍可使用,但会触发一次性弃用警告。新部署请优先使用规范的OS_*名称,参见旧别名。
核心
| 变量 | 是否必需 | 说明 |
|---|---|---|
OS_PORT | 否 | 运行时监听的 HTTP 端口。默认 3000。旧别名:PORT。 |
OS_AUTH_SECRET | 启用 auth 时必需 | 用于派生各项目 auth 密钥的基础密钥。旧别名:AUTH_SECRET。 |
Artifact 与项目解析
| 变量 | 是否必需 | 说明 |
|---|---|---|
OS_ARTIFACT_FILE | 文件模式 | 已编译 objectstack.json 的路径或 http(s):// URL。由 ObjectOS 配置读取,并作为 artifactPath 传给 createStandaloneStack。云连接部署可将其指向已发布的云端 artifact URL。 |
OS_ARTIFACT_PATH | 备选 | 同一路径或 URL 的框架级名称,由 @objectstack/runtime 直接识别（CLI dev/start）。默认 <cwd>/dist/objectstack.json。 |
OS_PROJECT_ID | 可选 | OS_ENVIRONMENT_ID 的旧别名,ObjectOS 配置为向后兼容接受。新部署中优先使用 OS_ENVIRONMENT_ID。 |
OS_ENVIRONMENT_ID | 可选 | standalone stack 的环境 id（默认 proj_local）。也用于派生项目级 auth 密钥。ObjectOS 配置也接受旧别名 OS_PROJECT_ID。 |
OS_ORGANIZATION_ID | 可选 | 文件支持模式下的默认组织 id（默认 org_local）。 |
OS_MCP_SERVER_ENABLED | 否 | 设为 true 以通过 Streamable HTTP 在 /api/v1/mcp 暴露 Model Context Protocol 服务器（8.0+）。默认关闭——开启前端点返回 404,开启后需要已认证的主体。 |
OS_CLOUD_URL | 可选 | marketplace 代理与本地 package 安装的控制平面基础 URL。设为 off 或 local 可禁用 marketplace 功能。在 standalone 分发中不再用于 host stack 的主机名路由。 |
OS_MULTI_ORG_ENABLED | 否 | 设为 true 以启用多租户路由/组织切换（默认 false）。旧别名:OS_MULTI_TENANT。 |
OS_RUNTIME_PORT | 仅开发 | 当在 http://localhost:<port> 开发时,用于构建平台 SSO 回调 URL 的本地端口。 |
Artifact 热重载。 standalone stack 在非生产环境下（由
NODE_ENV控制） 自动重载本地 artifact;不再需要 7.x 的显式OS_WATCH_ARTIFACT=1标志。
缓存
| 变量 | 默认值 | 说明 |
|---|---|---|
OS_KERNEL_CACHE_SIZE | 32 | 缓存项目内核的最大数量。 |
OS_KERNEL_TTL_MS | 900000 | 项目内核的空闲 TTL。 |
OS_ENV_CACHE_TTL_MS | 300000 | 环境/主机名缓存 TTL。 |
OS_ARTIFACT_CACHE_TTL_MS | 300000 | Artifact 响应缓存 TTL。 |
Auth 与可信来源
| 变量 | 说明 |
|---|---|
AUTH_SECRET | OS_AUTH_SECRET 的旧别名。本版本仍可使用;请优先使用 OS_AUTH_SECRET。 |
OS_TRUSTED_ORIGINS | 逗号分隔的额外可信来源。 |
OS_ROOT_DOMAIN | 平台 SSO 部署中信任项目子域的根域。 |
OS_PLATFORM_SSO | 设为 false 以禁用平台 SSO 装配。 |
OS_RUNTIME_PORT | 用于 localhost 项目主机名的本地开发辅助。 |
数据库
云端联动模式下,控制平面在 artifact 响应中返回每个项目的运行时数据库配置。文件支持模式下,ObjectOS 从 artifact 读取数据源声明。作为最后回退,框架还识别以下变量：
| 变量 | 说明 |
|---|---|
OS_DATABASE_URL | 连接 URL（file:./db.sqlite、libsql://…、postgres://…、mongodb://…、memory://）。独立模式与 CLI dev 使用。 |
OS_DATABASE_DRIVER | 覆盖根据 URL 自动检测的驱动。 |
OS_DATABASE_AUTH_TOKEN | 用于 Turso/libSQL 等托管驱动的 auth token。 |
OS_BUSINESS_DB_URL | ObjectOS wrapper 对每个项目业务数据库 URL 的约定。在部署中将其解析到 OS_DATABASE_URL 或运行时数据源覆盖。 |
OS_CACHE_DIR | 本地 artifact 与运行时缓存目录（默认 /var/cache/objectos）。 |
OS_SKIP_SCHEMA_SYNC | 设为 1 时在启动时跳过 ObjectQL DDL 同步。schema 由外部管理时使用。 |
对 ObjectOS 客户部署,优先使用显式控制平面运行时配置或 artifact 数据源配置,而非依赖容器本地默认值。
可观测性
追踪与指标导出为按需启用。导出器默认为 noop,因此在你选择之前部署不会发出任何数据 —— 仅设置端点不起作用。
| 变量 | 默认值 | 说明 |
|---|---|---|
OS_OBS_EXPORTER | noop | 遥测导出器:noop | console | json | otlp。本地调试用 console/json,接入采集器用 otlp。 |
OS_OTLP_ENDPOINT | — | OTLP/HTTP 根 URL（例如 https://otlp.grafana.net/otlp）。当 OS_OBS_EXPORTER=otlp 时必需;若为空,运行时会告警并回退到 noop。 |
OS_OTLP_HEADERS | — | 额外的 OTLP 头（例如鉴权）,以逗号分隔的 key=value 对表示。 |
OS_OBS_SERVICE_NAME | — | 发出的 span/指标上的 service.name 资源属性。 |
OS_OBS_DEPLOYMENT_ENV | production | deployment.environment 资源属性。 |
OS_OTLP_FLUSH_MS | — | OTLP 导出器的刷新间隔,单位毫秒。 |
设置命名空间覆盖
系统设置（租户/用户可编辑的 ai、email、feature_flags 等命名空间）可在部署级用一个名为 OS_<NAMESPACE>_<KEY> 的环境变量固定 —— 全部大写,并将 . 与 - 替换为 _。例如 ai.openai_base_url → OS_AI_OPENAI_BASE_URL,feature_flags.ai_enabled → OS_FEATURE_FLAGS_AI_ENABLED。自 9.0 起,无前缀的别名已被移除 —— 只读取带 OS_ 前缀的形式。
Google 登录（在 Setup → Authentication 中配置）也在部署级读取 GOOGLE_CLIENT_ID 与 GOOGLE_CLIENT_SECRET。
旧别名
以下 1.0 之前的名称在本版本仍可使用,但会触发一次性弃用警告,并将在未来的主版本中移除。请优先使用规范名称。
| 规范名称 | 旧别名 |
|---|---|
OS_PORT | PORT |
OS_AUTH_SECRET | AUTH_SECRET |
OS_MULTI_ORG_ENABLED | OS_MULTI_TENANT |
OS_ENVIRONMENT_ID | OS_PROJECT_ID |