자주 묻는 질문

시작하기

Q: ObjectOS를 가장 빠르게 사용해 볼 수 있는 방법은 무엇인가요? A: npm i -g @objectstack/cli && os start — 그런 다음 http://localhost:3000 을 엽니다. Quickstart를 참고하세요.

Q: Docker가 필요한가요? A: 아니요. Node 20+ 와 CLI만 있으면 충분합니다. Docker는 권장되는 프로덕션 배포 형태입니다.

Q: 데이터베이스가 필요한가요? A: 아니요, 시작하는 데는 필요하지 않습니다 — ObjectOS는 기본적으로 로컬 SQLite를 사용합니다. 프로덕션으로 전환할 때 Postgres / MySQL / Turso / Mongo로 교체하세요.

Q: 계정 / 클라우드 서비스가 필요한가요? A: 아니요. ObjectOS는 완전히 독립적입니다. ObjectStack Cloud는 컨트롤 플레인을 갖춘 다중 환경 / 다중 앱 배포를 위한 선택 사항입니다.

아키텍처

Q: Postgres / MySQL / MongoDB를 사용할 수 있나요? A: 예 — Postgres, MySQL, SQLite, Turso/libSQL, MongoDB가 지원되는 드라이버입니다. Runtime Configuration를 참고하세요.

Q: Console / Account를 비활성화하고 REST API만 사용할 수 있나요? A: 예. os start --no-ui를 실행하거나 해당 플래그를 설정하세요. UI가 마운트되어 있든 아니든 REST API는 동일합니다.

Q: Console 대신 제 자체 프런트엔드를 사용할 수 있나요? A: 예. Console은 여러분이 자체 코드에서 호출하는 것과 동일한 /api/v1/* 엔드포인트를 사용합니다. @objectstack/client SDK 또는 임의의 HTTP 클라이언트를 사용하세요.

Q: ObjectOS는 GraphQL을 지원하나요? A: REST가 기본 인터페이스입니다. GraphQL은 로드맵에 있습니다 — 그때까지는 ObjectQL 쿼리 언어(REST ?filter=/?sort= 기반)가 동일한 영역을 다룹니다.

Q: 멀티테넌시는 어떻게 처리되나요? A: 하나의 ObjectOS 프로세스는 여러 Environment(테넌트)를 제공할 수 있습니다. 호스트명 → Environment 해석은 LRU에 캐시됩니다. 각 Environment는 자체 데이터베이스, 신원, 감사 로그를 갖습니다. 쿠키는 호스트명별로 스코프가 지정되므로 세션이 테넌트 간에 누출될 수 없습니다.

Q: ObjectOS를 서버리스 / Lambda 환경에서 실행할 수 있나요? A: 런타임은 장기 실행되는 Node 프로세스입니다 — 상태 비저장 함수가 아니라 컨테이너나 VM을 위해 설계되었습니다. 커널 캐시와 Better Auth 세션 모델은 모두 워밍된 인프로세스 상태에 의존합니다.

Q: 수평적으로 확장되나요? A: 예. 로드 밸런서 뒤에서 여러 인스턴스를 실행하세요. 세션은 데이터베이스에 저장되므로(메모리가 아님) 어떤 인스턴스든 어떤 요청이든 처리할 수 있습니다. 해당 기능을 활성화하는 경우 공유 속도 제한 및 큐를 위해 Redis를 사용하세요.

데이터 및 마이그레이션

Q: 스키마 마이그레이션은 어떻게 처리되나요? A: 드라이버는 부팅 시 선언된 객체에 맞게 데이터베이스 스키마를 동기화합니다. Postgres의 경우 CREATE TABLE / ALTER TABLE 문입니다. 규제 환경에서 통제된 마이그레이션을 수행하려면 OS_SKIP_SCHEMA_SYNC=1을 설정하고 DDL을 직접 관리하세요.

Q: 필드 이름을 변경하면 데이터는 어떻게 되나요? A: 이름 변경은 데이터 계층에서 파괴적인 변경입니다("기존 열 삭제, 새 열 추가"처럼 보입니다). os diff를 사용해 이를 감지하고 마이그레이션 단계를 추가하세요(새 아티팩트를 배포하기 전에 DB에서 열 이름 변경).

Q: CSV / Excel / Salesforce에서 데이터를 가져올 수 있나요? A: CSV: 예, 반복 루프 내에서 os data create를 사용하거나 Console 일괄 업로드를 통해 가능합니다. Salesforce: 현재 가장 좋은 경로는 CSV로 내보낸 후 가져오는 것입니다. 네이티브 커넥터는 로드맵에 있습니다.

Q: ObjectOS를 업그레이드하면 데이터가 손실되나요? A: 아니요. 패치 및 마이너 업그레이드는 비파괴적입니다. 메이저 업그레이드 (예: 4 → 5)는 필요한 마이그레이션을 명시적으로 문서화합니다. 먼저 백업하세요 — Backup & DR.

권한 및 멀티테넌시

Q: 행 수준 보안은 어떻게 하나요? A: 공유 규칙(선언적, Salesforce와 유사)을 선언하거나 객체의 recordAccess 구성에 CEL 술어를 선언하세요. 보안 플러그인은 모든 쿼리에 해당 필터를 주입합니다. Permissions를 참고하세요.

Q: 특정 사용자에게 일부 필드를 보이지 않게 할 수 있나요? A: 예 — 권한 집합의 필드 수준 보안입니다. 권한 집합별로 필드별로 숨김 또는 읽기 전용으로 설정합니다. REST, ObjectQL, Console 전반에 걸쳐 일관되게 적용됩니다. Permission Sets를 참고하세요.

Q: Okta / Entra / Keycloak를 어떻게 통합하나요? A: OIDC. Console → Authentication에서(또는 환경 변수를 통해) 디스커버리 URL + 클라이언트 ID/시크릿을 구성하세요. 제공자 콜백 URL은 /api/v1/auth/oauth2/callback/<provider-id>입니다. Authentication를 참고하세요.

통합

Q: 웹훅을 보낼 수 있나요? A: 예 — requires에서 webhooks를 활성화하세요. ObjectOS는 HMAC-SHA256 서명이 적용된 영구 아웃박스를 사용합니다. Webhooks를 참고하세요.

Q: Zapier / Make / n8n과 통합할 수 있나요? A: 예 — 아웃바운드는 웹훅으로, 인바운드는 REST API + API 키로 가능합니다. 인기 있는 iPaaS 도구를 위한 네이티브 커넥터는 로드맵에 있습니다.

Q: AI 에이전트가 제 ObjectOS를 호출할 수 있나요? A: 예, MCP(@objectstack/plugin-mcp-server)를 통해 가능합니다 — 객체와 액션을 Claude Desktop, IDE 또는 기타 MCP 클라이언트가 사용할 수 있는 MCP 도구로 노출합니다. AI Service를 참고하세요.

커스터마이징

Q: 사용자 정의 플러그인을 작성할 수 있나요? A: 예 — 플러그인은 간단한 DI + 라이프사이클 패턴 (init → start → destroy)을 따릅니다. 예제는 GitHub의 @objectstack/plugin-* 패키지를 참고하세요.

Q: Console의 외관을 커스터마이즈할 수 있나요? A: 브랜딩(로고, 강조 색상, 기본 테마)은 Console → System Settings에 있습니다. 심도 있는 UI 커스터마이징은 @objectstack/client-react를 포크하거나 REST API에 맞춰 자체 프런트엔드를 구축하는 것을 의미합니다.

Q: 영어 외의 언어를 추가할 수 있나요? A: 예 — i18n은 일급 기능입니다. os i18n extract / os i18n check를 사용하고 번역 번들을 배포하세요.

운영

Q: 권장되는 프로덕션 배포는 무엇인가요? A: Docker(또는 다중 파드용 Kubernetes) + 관리형 Postgres + 파일용 S3 또는 R2

• OS_AUTH_SECRET을 위한 시크릿 관리자입니다. Production Readiness를 참고하세요.

Q: ObjectOS에 상태 페이지가 있나요? A: 셀프 호스팅 배포의 경우 상태는 여러분의 책임입니다 — /health를 모니터에 연결하세요. 호스팅 서비스의 경우 status.objectstack.ai를 참고하세요.

Q: 어떤 메트릭을 모니터링해야 하나요? A: 5xx 비율, p95 지연 시간, 인증 실패율, 커널 캐시 미스율, 큐 깊이입니다. 최소한의 Prometheus 예제는 Observability에 있습니다.

Q: 백업은 어떻게 하나요? A: 데이터베이스와 스토리지 버킷을 백업하세요 — 그것들이 모든 고객 데이터를 담고 있습니다. ObjectOS 자체는 상태 비저장입니다. Backup을 참고하세요.

가격 및 법적 사항

Q: ObjectOS는 정말 무료인가요? A: 예. Apache-2.0. 좌석 수, 사용 등급, 라이선스 서버가 없습니다.

Q: 제가 판매하는 상용 제품에 ObjectOS를 사용할 수 있나요? A: 예. Apache-2.0은 상업적 사용을 허용합니다. License를 참고하세요.

Q: 텔레메트리를 수집하나요? A: 아니요. 여러분이 구성하지 않는 한 아웃바운드 호출은 전혀 없습니다(OIDC, 이메일, AI, 웹훅). Security & Compliance를 참고하세요.

Q: ObjectOS는 SOC 2 / ISO 27001 / HIPAA / GDPR를 준수하나요? A: ObjectOS는 모든 프레임워크가 요구하는 기본 요소(RBAC, 감사, 암호화 준비, 데이터 위치)를 제공합니다. 인증은 바이너리가 아니라 여러분의 배포의 속성입니다. 많은 ObjectOS 배포가 인증을 받았습니다. Security & Compliance를 참고하세요.

막혔을 때 해결하기

Q: 무언가 망가졌어요 — 어디서부터 시작해야 하나요? A: os doctor. 이것은 잘못된 구성의 80%를 자체적으로 잡아냅니다. 그 후에는 Troubleshooting을 참고하세요.

Q: 버그는 어디에 보고하나요? A: GitHub Issues. os doctor 출력을 포함해 주세요. 보안 문제는 security@objectstack.ai로 알려주세요.

Q: 사람에게 도움을 받으려면 어디로 가야 하나요? A: GitHub Discussions, 커뮤니티 Discord, 또는 상업적 지원을 위한 sales@objectstack.ai입니다.