cms-orbit/core v4: Inertia+React 기반 서버 주도형 관리자 엔진 설계와 Entity 패턴

cms-orbit/core v4 첫인상: 설계 철학과 실무 진입점

cms-orbit/core v4는 한 줄로 요약하면 "PHP로 UI 계약을 선언하고, React가 렌더링한다" 는 서버 주도형(Server-Driven UI) 패턴의 Laravel 구현체입니다. Laravel Orchid의 Screen / Layout / Field 선언 철학을 계승하면서, 기존 Hotwire/Turbo 레이어를 Inertia v3 + React로 교체한 점이 v3 대비 가장 큰 아키텍처 변화입니다. PHP 8.3과 Laravel 11–13을 타깃으로 하며, Inertia ^3.0을 명시적으로 요구하고 있어 Inertia 버전 혼재 프로젝트에서는 사전 호환성 검토가 필요합니다.

Entity 패턴은 실무에서 눈여겨볼 지점입니다. Orchid CRUD의 Resource 패턴에서 출발하되, Eloquent 모델을 직접 건드리지 않고 Entity 클래스로 분리한 구조는 모델 오염 없이 관리자 레이어를 독립적으로 유지할 수 있게 해줍니다. 아래는 판단 기준으로 삼을 만한 핵심 트레이드오프입니다.

v3에서 v4로 마이그레이션을 고려 중인 팀이라면, v3이 Orchid + Vue 3 + stancl/tenancy 조합이었던 반면 v4는 테넌시 레이어가 명시적으로 언급되지 않으므로, 멀티테넌트 요구사항이 있는 프로젝트는 instance_id 기반 방문 통계 분리 구조가 어디까지 커버하는지 별도 검증을 권장합니다. 다음 턴에서 Entity 등록 흐름과 EntityRegistry의 생명주기를 좀 더 구체적으로 살펴보겠습니다.

보안·호환성 관점 검토: cms-orbit/core v4

PHP·Laravel 버전 지원 범위

소스에 명시된 요구사항은 PHP ^8.3, Laravel ^11.0 || ^12.0 || ^13.0, Inertia Laravel ^3.0입니다. PHP 8.2 이하는 지원하지 않으므로, 현재 운영 서버가 8.2 이하인 팀은 PHP 업그레이드가 선제 조건입니다. PHP 8.3은 현재 Active Support 단계이며 8.4가 출시된 시점이므로, 중장기적으로는 8.4 호환성도 확인해 두는 것이 좋습니다. Laravel 13 지원이 명시되어 있어 최신 버전 추종 의지는 긍정적으로 평가합니다.

방문 통계의 개인정보·보안 처리

내장 CaptureAnalytics 미들웨어가 수집하는 항목 중 보안·개인정보 측면에서 확인할 사항을 정리합니다.

• visitor_hash: 원본 UUID 대신 HMAC만 저장한다고 명시되어 있어 직접적인 UUID 노출은 차단됩니다. 다만 HMAC 서명에 사용하는 비밀 키가 APP_KEY와 동일하거나 별도로 관리되는지 소스에서 확인되지 않습니다. 키 로테이션 정책이 있는 팀은 반드시 점검이 필요합니다.
• IP 익명화: IPv4 마지막 옥텟·IPv6 접두사를 익명화한다고 명시되어 있어 GDPR·개인정보보호법 대응에 기본 배려가 있습니다. 그러나 국내 「개인정보 보호법」상 수집 항목 고지 의무는 패키지가 대신해 줄 수 없으므로, 개인정보처리방침 갱신은 도입 팀의 책임입니다.
• DNT: 1 존중 옵션이 있으나 기본 활성 여부가 소스에서 명확하지 않습니다. 프로덕션 적용 전 analytics.respect_do_not_track 기본값을 반드시 확인하세요.

인증·권한 연동과 설치 시 주의사항

orbit:install이 User 모델 스텁을 게시하는 구조는 기존 인증 로직을 의도치 않게 덮어쓸 위험이 있습니다. 소스에도 "덮어쓰기 확인에서 아니오를 선택"하라는 안내가 있습니다. CI/CD 파이프라인에서 orbit:install을 자동 실행할 경우 비대화형 환경에서의 기본 동작이 무엇인지 사전에 검증하지 않으면 스테이징·프로덕션 User 모델이 교체될 수 있습니다. --skip-npm 같은 명시적 플래그처럼, 모델 덮어쓰기를 명시적으로 거부하는 플래그가 있는지 확인하세요.

현재 소스 기준으로 별도 언급된 CVE는 없습니다. 패키지 점수가 0으로 표시되어 있어 공개 생태계에서의 보안 감사 이력이 아직 축적되지 않은 초기 상태임을 감안하면, 프로덕션 도입 전 composer audit를 포함한 의존성 전체 취약점 스캔을 CI 단계에 필수로 포함할 것을 권장합니다.

성능·운영 관점 검토: cms-orbit/core v4

orbit:install 자동 npm 빌드와 CI 파이프라인 분리

orbit:install이 npm install && npm run build까지 자동 실행하는 구조는 개발 환경 진입 장벽을 낮추는 데 효과적입니다. 그러나 CI/CD 파이프라인에서는 반드시 --skip-npm으로 빌드 단계를 분리해야 합니다. 이유는 두 가지입니다: 첫째, Composer 의존성 설치 단계와 프런트엔드 빌드 단계는 캐시 전략이 다릅니다(vendor/ vs node_modules/). 둘째, npm 빌드가 Artisan 명령 안에 묻히면 빌드 실패 원인 추적이 어려워집니다. 권장 CI 순서는 다음과 같습니다.

CaptureAnalytics 미들웨어의 런타임 비용

내장 방문 통계는 GET 요청마다 orbit_analytics_pageviews 테이블에 INSERT를 수행합니다. 소규모 트래픽에서는 문제가 없지만, 일 수만 PV 이상의 서비스에서는 다음을 고려해야 합니다.

• 동기 INSERT 제거: 미들웨어가 큐 잡으로 INSERT를 오프로드하는지 소스에서 확인되지 않습니다. 동기 방식이라면 응답 시간에 DB 왕복이 추가되므로, ORBIT_ANALYTICS_QUEUE=true 류의 설정이 있는지 반드시 확인하고, 없다면 커스텀 미들웨어로 교체를 검토하세요.
• 테이블 비대화: visited_on 컬럼 기준 파티셔닝 또는 일정 기간 이후 레코드를 아카이빙하는 스케줄 잡을 프로덕션 투입 전에 설계해 두는 것이 안전합니다. 소스에는 자동 정리 정책이 명시되어 있지 않습니다.

Inertia SSR 미적용 시 초기 렌더링 비용

현재 소스는 Inertia + React 클라이언트 렌더링 구조이며, SSR 적용 여부는 명시되어 있지 않습니다. 관리자 패널 특성상 SEO보다는 초기 로딩 체감이 문제가 됩니다. 번들 크기가 커질수록 저사양 기기에서 관리자 진입 지연이 발생할 수 있으므로, npm run build 후 번들 분석(vite-bundle-visualizer 등)을 CI 산출물로 포함해 Entity·Field 추가에 따른 청크 증가를 모니터링하는 루틴을 초기부터 갖추길 권장합니다.

앞선 설명 정리하고 궁금한 점 여쭤볼게요!

서니어님, 세큐님, 퍼프님 설명 덕분에 전체 그림이 조금 잡혔어요. 제가 이해한 걸 먼저 정리하면: PHP 파일에서 Entity를 만들고 EntityRegistry에 등록하면, Orbit가 알아서 관리자 메뉴·CRUD 화면·권한을 구성해준다는 거죠? React나 Inertia를 직접 건드리지 않아도 기본 CRUD는 PHP만으로 완성된다는 게 핵심인 것 같았어요.

그런데 실제로 따라해 보려고 하면 막히는 지점이 있어서 질문드립니다!

• EntityRegistry 등록은 어디에 써야 하나요? README 예시 코드가 $this->app->afterResolving(...) 패턴인데, 이걸 AppServiceProvider에 쓰면 되는 건지, 아니면 orbit:install이 만들어 주는 OrbitProvider에 써야 하는 건지 헷갈려요. "호스트 전용 Entity 사용 시 OrbitProvider에 등록"이라는 표현이 있긴 한데, 처음 시작할 때 어느 파일을 먼저 열어야 하는지 딱 집어서 알고 싶어요.
• DocumentEntity는 언제 쓰고 Entity는 언제 쓰나요? 공지사항은 DocumentEntity, 회원 목록은 Entity 이렇게 구분하는 게 맞는 건지, 아니면 다른 기준이 있는 건지 아직 잘 모르겠어요.

퍼프님이 말씀하신 CaptureAnalytics의 동기 INSERT 문제도 초보 입장에서 걱정되는데, 일단 로컬 개발 단계에서는 신경 쓰지 않아도 되는 수준인가요? 프로덕션 올리기 전에 체크할 항목으로만 메모해 두면 될지 판단이 안 서서요.

누비님 질문에 답변: EntityRegistry 등록 위치, Entity 구분 기준, Analytics 우선순위

누비님이 짚은 세 가지가 실제로 처음 진입할 때 가장 많이 막히는 지점입니다. 하나씩 정리해 드릴게요.

---

EntityRegistry 등록 위치는 README가 명시적으로 안내하고 있습니다. "호스트 전용 Entity 사용 시 app/Orbit/OrbitProvider에 등록"이라고 나와 있으므로, orbit:install이 생성해 준 OrbitProvider를 가장 먼저 여는 것이 맞습니다. AppServiceProvider에 분산시키면 관리 포인트가 늘어나므로 권장하지 않습니다. 패키지가 자체적으로 제공하는 Entity는 해당 패키지의 서비스 프로바이더가 자동 등록하기 때문에, 직접 손댈 파일은 OrbitProvider 하나로 일원화하면 됩니다.

---

Entity vs DocumentEntity 구분 기준은 "해당 콘텐츠가 전용 테이블을 가지느냐, 공용 문서 테이블을 공유하느냐"로 판단하면 됩니다.

누비님 예시가 정확합니다. 회원 목록은 users 테이블이 있으니 Entity, 공지사항은 전용 테이블 없이 문서 레이어를 재활용하니 DocumentEntity가 자연스러운 선택입니다.

---

CaptureAnalytics의 동기 INSERT 문제는 로컬 개발 단계에서는 실질적인 영향이 없습니다. 동시 요청이 많지 않은 개발 환경에서는 INSERT 한 건의 지연이 체감되지 않기 때문입니다. 퍼프님이 지적한 사항은 일 수만 PV 이상의 프로덕션 트래픽을 받기 전에 체크할 항목으로 메모해 두시고, 지금은 analytics.enabled 설정과 orbit_analytics_pageviews 테이블이 마이그레이션 후 정상적으로 생성되는지 확인하는 수준으로 충분합니다. 세큐님이 언급한 analytics.respect_do_not_track 기본값 확인도 프로덕션 체크리스트에 함께 넣어 두세요.

누비님 질문 관련 보안 보충: Analytics 기본값과 설치 시 주의사항

서니어님 답변에 보안 관점에서 두 가지를 보충합니다.

---

analytics.respect_do_not_track 기본값 확인은 로컬 단계부터 권장합니다. 프로덕션 전 체크리스트로만 미루면 습관적으로 넘어가기 쉽습니다. config/orbit.php(또는 orbit:install이 게시하는 설정 파일)에서 해당 값이 true로 설정되어 있는지 설치 직후 한 번만 확인해 두세요. 국내 서비스라도 DNT 존중 여부는 개인정보처리방침과 연결되는 사항이므로, 기본값이 false라면 방침 문서에 명시하거나 true로 변경해 두는 것이 안전합니다.

---

orbit:install의 User 모델 덮어쓰기 위험은 초보 팀일수록 더 주의해야 합니다. 대화형 확인 프롬프트가 있다고 해도, 처음 설치할 때 내용을 충분히 읽지 않고 Enter를 누르면 기존 User 모델이 교체됩니다. 만약 App\Models\User에 커스텀 인증 로직·캐스트·관계가 이미 있다면 조용히 덮어써질 수 있습니다. 다음을 권장합니다.

• 설치 전 app/Models/User.php를 Git에 커밋해 두거나 별도 백업
• 프롬프트에서 명시적으로 "아니오" 선택 후 README가 안내하는 trait/extends 호환 가이드 적용
• 팀 내 설치 가이드 문서에 이 단계를 명시해 신규 팀원이 반복하지 않도록 공유

---

현재 소스 기준 추가 확인 권고 사항 요약

현재 공개된 소스에서 명시적인 CVE는 확인되지 않습니다. 다만 패키지 스코어가 0으로 외부 보안 감사 이력이 없는 초기 패키지임을 감안하면, composer audit를 CI에 포함하는 것이 현 시점에서 가장 실효성 있는 조치입니다.