ObjectOS환경 변수
ObjectOS 런타임 환경 변수 참조.
환경 변수
배포 수준 구성 및 시크릿에는 환경 변수를 사용하세요. 테넌트/사용자가 편집 가능한 애플리케이션 구성에는 시스템 설정을 사용하세요.
명명 규칙. 모든 ObjectStack 소유 변수는
OS_접두사를 사용합니다. 1.0 이전의 접두사 없는 이름(PORT,AUTH_SECRET,OS_MULTI_TENANT, …)도 여전히 동작하지만 일회성 사용 중단 경고를 출력합니다. 새 배포에서는 표준OS_*이름을 사용하는 것이 좋습니다. 레거시 별칭을 참조하세요.
핵심
| 변수 | 필수 | 설명 |
|---|---|---|
OS_PORT | 아니오 | 런타임이 수신 대기하는 HTTP 포트. 기본값은 3000. 레거시 별칭: PORT. |
OS_AUTH_SECRET | 인증 시 필수 | 프로젝트별 인증 시크릿을 파생하는 데 사용되는 기본 시크릿. 레거시 별칭: AUTH_SECRET. |
아티팩트 및 프로젝트 확인
| 변수 | 필수 | 설명 |
|---|---|---|
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). 프로젝트별 인증 시크릿을 파생하는 데에도 사용됩니다. ObjectOS 구성은 레거시 별칭 OS_PROJECT_ID도 허용합니다. |
OS_ORGANIZATION_ID | 선택 | 파일 기반 모드의 기본 조직 id(기본값 org_local). |
OS_MCP_SERVER_ENABLED | 아니오 | true로 설정하면 Model Context Protocol 서버를 Streamable HTTP로 /api/v1/mcp에 노출합니다(8.0+). 기본값은 꺼짐 — 활성화하기 전에는 엔드포인트가 404를 반환하며, 활성화 후에는 인증된 주체가 필요합니다. |
OS_CLOUD_URL | 선택 | marketplace 프록시 및 로컬 패키지 설치를 위한 컨트롤 플레인 기본 URL. off 또는 local로 설정하면 marketplace 기능을 비활성화합니다. standalone 배포판에서는 더 이상 host stack의 호스트명 라우팅에 사용되지 않습니다. |
OS_MULTI_ORG_ENABLED | 아니오 | 멀티 테넌트 라우팅/조직 전환을 활성화하려면 true로 설정합니다(기본값 false). 레거시 별칭: OS_MULTI_TENANT. |
OS_RUNTIME_PORT | 개발 전용 | http://localhost:<port>에서 개발할 때 플랫폼 SSO 콜백 URL을 구성하는 데 사용되는 localhost 포트. |
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 | 아티팩트 응답 캐시 TTL. |
인증 및 신뢰할 수 있는 출처
| 변수 | 설명 |
|---|---|
AUTH_SECRET | OS_AUTH_SECRET의 레거시 별칭. 이번 릴리스에서도 여전히 처리되지만 OS_AUTH_SECRET을 사용하는 것이 좋습니다. |
OS_TRUSTED_ORIGINS | 쉼표로 구분된 추가 신뢰 출처. |
OS_ROOT_DOMAIN | 플랫폼 SSO 배포에서 프로젝트 하위 도메인을 신뢰하는 데 사용되는 루트 도메인. |
OS_PLATFORM_SSO | 플랫폼 SSO 연결을 비활성화하려면 false로 설정합니다. |
OS_RUNTIME_PORT | localhost 프로젝트 호스트명을 위한 로컬 개발 도우미. |
데이터베이스
클라우드 연결 모드에서는 컨트롤 플레인이 아티팩트 응답과 함께 프로젝트별 런타임 데이터베이스 구성을 반환합니다. 파일 기반 모드에서 ObjectOS는 아티팩트에서 데이터소스 선언을 읽습니다. 최후의 수단으로 프레임워크는 다음도 처리합니다:
| 변수 | 설명 |
|---|---|
OS_DATABASE_URL | 연결 URL(file:./db.sqlite, libsql://…, postgres://…, mongodb://…, memory://). 독립 실행형 모드 및 CLI dev에서 사용됩니다. |
OS_DATABASE_DRIVER | URL에서 자동 감지된 드라이버를 재정의합니다. |
OS_DATABASE_AUTH_TOKEN | Turso/libSQL과 같은 관리형 드라이버를 위한 인증 토큰. |
OS_BUSINESS_DB_URL | 프로젝트별 비즈니스 데이터베이스 URL에 대한 ObjectOS 래퍼 규칙. 배포에서 이를 OS_DATABASE_URL 또는 런타임 데이터소스 재정의로 확인하세요. |
OS_CACHE_DIR | 로컬 아티팩트 및 런타임 캐시 디렉터리(기본값 /var/cache/objectos). |
OS_SKIP_SCHEMA_SYNC | 부팅 시 ObjectQL DDL 동기화를 건너뛰려면 1로 설정합니다. 스키마를 별도로 관리할 때 사용하세요. |
ObjectOS 고객 배포의 경우 컨테이너 로컬 기본값에 의존하기보다는 명시적인 컨트롤 플레인 런타임 구성 또는 아티팩트 데이터소스 구성을 사용하는 것이 좋습니다.
Observability
추적 및 메트릭 내보내기는 옵트인입니다. 익스포터의 기본값은 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 | — | 내보낸 스팬/메트릭의 service.name 리소스 속성. |
OS_OBS_DEPLOYMENT_ENV | production | deployment.environment 리소스 속성. |
OS_OTLP_FLUSH_MS | — | OTLP 익스포터의 플러시 간격(밀리초). |
Settings 네임스페이스 재정의
시스템 설정(테넌트/사용자 편집 가능한 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 |