버전 1.0.0-alpha.1최신
챕터 2.1
아키텍처
Nexus 차트의 각 서비스가 담당하는 역할과 그 아래에 자리한 스토어, 그리고 서비스 간 ID부터 모든 모델 호출이 거치는 경로까지 이들을 하나로 묶어주는 규칙을 설명합니다.
이 페이지는 AI에 의해 영어 원문에서 번역되었습니다. 불명확한 내용이 있는 경우 영어 페이지를 기준으로 삼으십시오. 이 페이지를 영어로 읽기

Tomás Reilly가 Harrow Port Authority에서 첫 설치를 마쳤을 때, kubectl -n nexus get pods에는 10개의 Deployment와 7개의 StatefulSet, 그리고 3개의 CronJob이 표시되었습니다. 데이터베이스를 구축한 마이그레이션 Job들은 성공 시 스스로 삭제되기 때문에 이미 사라진 상태였습니다. 그 목록이 플랫폼 전체입니다. 운영 단계(day-two)에서 발생하는 대부분의 질문이 "이 중 어느 것이 저것을 소유하는가?"에서 시작되므로 이를 숙지하시기 바랍니다.
이 장에서는 각 구성 요소에 대해 그 질문에 답하고, 구성 요소들을 통과하는 하나의 요청을 추적한 다음, 모두가 따르는 규칙을 다룹니다. 2부의 나머지 내용은 이 전체 그림을 바탕으로 전개됩니다.
서비스와 각 서비스의 담당 영역
이 차트는 Kubernetes 1.33 이상을 위한 단일 Helm 차트(nexus, 버전 1.0.0-alpha.1)입니다. 모든 워크로드는 자체 ServiceAccount 아래에서 루트가 아닌 사용자(non-root user)로 실행되며, 모든 Linux 기능(capabilities)이 제거됩니다. ID와 키를 보호하는 서비스에 대한 호출은 상호 TLS(Transport Layer Security)를 통해 이루어지며, 퍼블릭 API(application programming interface)는 AI(인공지능) 라우터와 프로세스를 공유합니다.
| 구성 요소 | Deployment 및 Service | 서비스 포트 | 소유 대상 |
|---|---|---|---|
| 콘솔 | nexus-alpha |
3000 | 사용자가 보는 페이지; 콘솔 호스트에서 HTML(Hypertext Markup Language) 제공 |
| BFF(backend for frontend) | nexus-alpha-bff |
8080 | 콘솔 자체 데이터, 각 사용자가 받는 메뉴, 릴리스 레지스터 |
| Auth | nexus-auth |
9101(8443에서 상호 TLS) | 사용자, 조직, 세션, 토큰, API 키, 조직의 모델 키 풀 |
| 게이트웨이 | nexus-gateway |
9092, WebSocket 8093 | The AI Provider Router, and the public API edge for REST (representational state transfer) and MCP (Model Context Protocol) |
| 오케스트레이터 | nexus-orchestrator |
8080 | UNO 디스패치: 모든 작업을 수락하고 대기열에 추가 |
| 워크플로 | nexus-workflows |
8081 | UNO 실행: 대기열에 있는 작업을 실행하는 워커 |
| GraphRAG | nexus-graphrag |
8090, WebSocket 8091 | 메모리: 지식 그래프 및 이를 통한 검색 |
| Probitas | nexus-probitas |
9151 (HTTPS) | 증거: 거버넌스 기록 및 봉인된 원장 |
| 스킬 엔진 | nexus-skills-engine |
8095 | 스킬 라이브러리; 스킬 탐색 및 실행 |
| 키 | nexus-keys |
8080(HTTPS, 상호 TLS) | OpenBao 내 조직별 키, 보관(custody), 설치 ID |
| 플러그인 | nexus-plugins |
9111 | 플러그인 레지스트리 및 카탈로그 기록; 기본적으로 꺼져 있음 |
| 파일 처리 | nexus-fileprocess |
9109 | 업로드된 문서 및 이미지 읽기; 기본적으로 꺼져 있음 |
처음 10개는 필수입니다. 마지막 2개는 선택 사항으로, Enterprise 설치나 도메인 팩에서 사용할 때 components.plugins.enabled 및 components.fileprocess.enabled로 켤 수 있습니다. 포트 8080의 또 다른 선택적 서비스인 nexus-alive은 자체 스위치인 components.alive.enabled를 가지며 이 역시 기본적으로 꺼져 있습니다. 각 서비스의 레플리카와 리소스는 components.<name> 아래에 위치합니다.
콘솔은 데이터베이스가 없는 서버 렌더링 페이지입니다. 퍼블릭 인증 호스트를 통해 외부로 나갔다 다시 들어오는 일 없이, 클러스터 내부에서 BFF 및 nexus-auth와 통신합니다. 에디션 정보가 없으면 부팅을 거부하며, 차트는 단일 edition 값에서 이를 NEXUS_EDITION로 전달합니다. 조직의 모든 구성원은 자신의 역할에 따라 콘솔에서 작업합니다. 관리 페이지는 소유자와 관리자를 위한 것이며, 일반 구성원이 열면 "관리자가 아님(Not an administrator)" 페이지가 표시됩니다.
BFF는 콘솔의 서버 측 절반에 해당하며, Nexus Alpha 제품으로 등록된 플랫폼의 플러그인으로 구축됩니다. 별도의 데이터베이스인 nexus_alpha에 콘솔 자체 테이블을 보관하며, 사용자가 볼 수 있는 메뉴 그룹을 결정합니다. 콘솔에서 작업을 수행해야 할 때 BFF는 해당 작업을 소유한 서비스에 요청합니다.
nexus-auth는 Go로 작성되었으며 토큰을 발행하는 유일한 서비스입니다. 기본적으로 액세스 토큰은 15분, 리프레시 토큰은 12시간 동안 유효합니다(auth.accessTokenTTL, auth.refreshTokenTTL). 로그인한 각 사용자를 분당 5,000개의 요청으로 제한하며 이를 초과하면 429로 응답합니다(auth.rateLimitPerMinute). 두 개의 리스너를 실행하는데, 하나는 퍼블릭 Ingress가 도달하는 컨테이너 포트 8080의 일반 리스너이고, 다른 하나는 클러스터 내부의 모든 호출자가 사용해야 하는 8443의 상호 TLS 리스너입니다. 클래스 없는 도메인 간 라우팅(CIDR) 범위 목록인 proxy.trustedCIDRs의 홉에서 온 X-Forwarded-For만 신뢰하며, 기본값은 k3s 파드 네트워크인 10.42.0.0/16입니다. 인그레스 컨트롤러가 다른 곳에서 실행 중이라면 이 값을 변경하십시오. 그렇지 않으면 모든 로그인이 컨트롤러에서 온 것처럼 보입니다.
게이트웨이는 하나의 프로세스를 공유하는 두 가지 역할을 수행합니다. 클러스터 내부에서는 조직의 모델 자격 증명을 유일하게 보유한 AI Provider Router(1부 및 콘솔 페이지의 AI 교환기) 역할을 합니다(자세한 내용은 아래 참조). 엣지에서는 api.<domain>이 도달하는 대상으로, 인증 호스트의 OAuth 2.1 권한 부여 서버에서 발급되고 https://<hosts.api>/mcp 오디언스(audience)를 포함하는 토큰을 가진 REST 클라이언트 및 MCP 클라이언트가 여기에 해당합니다(OAuth는 위임된 권한 부여를 위한 개방형 표준입니다).
오케스트레이터와 워크플로는 함께 워크플로 엔진인 UNO를 구성합니다. 모든 연산은 이들을 통해 실행됩니다. 오케스트레이터는 POST /api/v1/dispatch에서 작업을 수락하고, jobId, runId, traceId와 함께 202로 응답한 후 작업을 대기열에 넣습니다. 인라인 실행 경로는 없으며, 클라이언트는 항상 GET /api/v1/dispatch/{jobId}를 폴링하거나 콜백을 받습니다. 워크플로 워커는 기본적으로 레플리카당 한 번에 4개씩(workflows.concurrency) 대기열에서 작업을 가져오며, 단 하나의 HTTP 라우트인 GET /health만을 가집니다.
Probitas는 증거 서비스입니다. 차트가 발급하는 인증서를 통해 자체적으로 TLS를 제공하며, 원장을 위한 별도의 역할과 함께 trust 스키마에 테이블을 보관합니다. 거버넌스 기능은 probitas.flags로 전환됩니다. 몇몇 기능은 shadow 모드로 제공되어 판정이 계산되고 기록되지만, 플래그를 변경하기 전까지는 아무것도 차단되지 않습니다.
nexus-keys는 Go로 작성된 플랫폼 키 서비스입니다. OpenBao 키 저장소에 조직별로 키를 보관하고 매일 밤 이를 교체(rotate)합니다. 야간 작업은 또한 보관 기한이 도래한 키를 파기하고 영수증을 자체 볼륨으로 내보냅니다. 조직의 키를 지우면 그 아래에 잠긴 데이터는 영구적으로 읽을 수 없게 됩니다. 또한 첫 부트스트랩 시 keys.installationName 아래에 설치 ID를 발행하며, 이 이름은 영구적입니다. 차트는 빈 이름(INSTALLATION_NAME_MISSING)과 자체 예제 값에 있는 이름(INSTALLATION_NAME_EXAMPLE)을 거부하므로 신중하게 선택하십시오.
세 개의 퍼블릭 호스트
차트는 정확히 세 개의 호스트 이름을 게시하며, 이들이 합쳐져 설치 ID가 됩니다. 모든 서비스는 이 호스트 이름들이 없으면 부팅을 거부합니다.
| Ingress | 호스트 값 | 백엔드 |
|---|---|---|
nexus-console |
hosts.console |
nexus-alpha, 포트 3000 |
nexus-api |
hosts.api |
nexus-gateway, 포트 9092 |
nexus-auth |
hosts.auth |
nexus-auth, 포트 9101 |
이 책의 예제에서는 console.harrow.example, api.harrow.example, auth.harrow.example을 사용합니다. Ingress들은 각각 경로가 /인 규칙 하나를 가진 일반 networking.k8s.io/v1 객체입니다. 엣지에서의 TLS는 tls.mode을 따릅니다: existing(사용자가 생성하고 tls.existingSecret에 이름을 지정한 Secret), cert-manager(사용자가 실행하고 tls.clusterIssuer에 이름을 지정한 ClusterIssuer) 또는 none(클러스터 앞단에서 TLS가 종료됨). 차트는 자체적인 리다이렉트를 추가하지 않으므로 ACME(Automated Certificate Management Environment) HTTP 챌린지가 솔버에 변경 없이 도달합니다. 2.11장, 변형: 외부 저장소, TLS 및 인그레스에서 각 모드를 다룹니다.
그 외에는 아무것도 노출되지 않습니다. 데이터 저장소, OpenBao 및 모든 내부 서비스는 네임스페이스 내부에서만 수신 대기합니다.
요청의 처음부터 끝까지
다음은 Harrow의 IT 총괄인 Aoife Brennan이 콘솔을 열고 어시스턴트에게 이번 달 선석 일정에 관해 질문할 때 일어나는 일입니다.
- 그녀의 브라우저가
https://console.harrow.example을 로드합니다.nexus-consoleIngress가 이를 포트 3000의nexus-alpha으로 보냅니다. - 그녀는 패스키로 로그인합니다. 로그인 페이지는
auth.harrow.example를 통해nexus-auth과 통신하며, nexus-auth는 그녀의 사용자 정보, 조직, 그리고 세션에 사업부 정보가 있는 경우 사업부 정보를 담은 액세스 토큰을 발행합니다. - 콘솔 서버는 BFF를 호출하고, BFF는 그녀의 토큰을 확인한 뒤 nexus-auth에 그녀의 조직이 해당 제품을 보유하고 있는지, 그리고 그녀의 역할이 허용되는지 묻습니다. 그러면 그녀가 볼 수 있는 메뉴 그룹으로 응답합니다.
- 그녀의 질문은 검증된 토큰에서 추출한 조직 및 사용자 정보와 함께 BFF에서 오케스트레이터의 디스패치 라우트로 전달됩니다. 오케스트레이터는 202로 응답하고 Valkey의 대기열에 작업을 넣습니다.
- 워크플로 워커가 작업을 가져갑니다. 실행할 스킬은 스킬 엔진에 의해 결정되며, Harrow 문서에 대한 검색은 Neo4j, Qdrant 및 자체 PostgreSQL 스키마를 읽는 GraphRAG로 전달됩니다.
- 모델 호출은
/internal/ai/chat에 있는 AI Provider Router로 전달됩니다. 라우터는 Harrow 자체 키 풀과 라우팅 정책에서 제공자와 모델을 선택하고, Harrow의 키로 호출을 수행한 뒤 완료 결과를 반환합니다. - 결과는 작업의 실행 행(run row)에 기록됩니다. BFF가 이를 읽고 콘솔이 인용 출처와 함께 답변을 화면에 그립니다.
서비스 간 홉은 투영된(projected) 서비스 토큰을 전달하며, nexus-auth, nexus-keys 및 Probitas로 향하는 홉은 설치 환경 자체 인증 기관(CA)의 TLS를 통해 실행됩니다. 또한 4단계에서 6단계까지의 모든 데이터 접근은 데이터베이스 자체 내에서 Harrow 조직으로 제한(fenced)됩니다. 아래 섹션에서 이 두 가지를 모두 설명합니다.
데이터 계층
Nexus는 번들에 포함된 각 소스 제공 사항과 함께 모든 저장소의 자체 서명된 사본을 제공합니다. 각 저장소는 기능 못지않게 라이선스를 고려하여 선택되었습니다.
| 저장소 | 버전 | 라이선스 | 사용 이유 | 포트 | 기본 볼륨 |
|---|---|---|---|---|---|
| PostGIS 및 pgvector가 포함된 PostgreSQL | PostgreSQL 16, PostGIS 3, pgvector 0.8 | PostgreSQL Licence; PostGIS GPL-2.0-or-later | 모든 서비스를 위한 기록 시스템(system of record); 지도 데이터를 위한 PostGIS; 행 옆에 보관되는 벡터를 위한 pgvector | 5432 | 50 GiB |
| Valkey | 8.1 | BSD-3-Clause | UNO 작업 대기열 및 nexus-auth의 API 키 캐시와 같은 단기 캐시 | 6379 | 5 GiB |
| Neo4j Community Edition | 5.26 | GPL-3.0 | GraphRAG가 구축하고 탐색하는 지식 그래프 | 7687 (Bolt) | 20 GiB |
| Qdrant | 1.15 | Apache-2.0 | GraphRAG 및 스킬 엔진을 위한 벡터 검색 | 6333(HTTP), 6334(gRPC 원격 프로시저 호출) | 10 GiB |
| SeaweedFS | 4.48 | Apache-2.0 | Amazon Simple Storage Service(S3)와 호환되는 파일용 오브젝트 스토리지 | 8333 | 50 GiB |
| OpenBao | 2.6 | MPL-2.0 | nexus-keys를 위한 키 저장소 및 봉인 해제기 | 8200 | 5 GiB 및 1 GiB |
일부 선택은 더 익숙한 기술들을 대체했습니다. Valkey는 본 릴리스에서 거부하는 현행 라이선스를 가진 Redis 7.4를 대신합니다. MinIO는 AGPL-3.0이므로 오브젝트 스토어는 SeaweedFS를 사용합니다. GraphRAG는 네트워크 프로토콜인 Bolt를 통해 Neo4j Community Edition에 도달하고, 서비스들은 PostgreSQL 프로토콜을 통해 PostGIS에 도달하므로 GPL은 각 구성 요소에만 머뭅니다. OpenBao는 Vault의 라이선스 변경 이전에 Linux Foundation에서 포크한 버전입니다.
모든 저장소는 인증이 활성화된 상태로 생성된 자격 증명(Valkey용 비밀번호, Qdrant용 API 키, SeaweedFS용 액세스 키)을 사용하여 실행됩니다.
dataTier 아래의 다섯 가지 저장소는 각각 클러스터 내부에서 실행되거나(mode: in-cluster, 기본값), 사용자가 이미 운영 중인 외부 저장소(mode: external, external.host 및 external.existingSecret로 지정된 Secret 사용)입니다. 외부 PostgreSQL의 경우 sslmode을 verify-full 또는 verify-ca로 설정하고 해당 Secret에 서버의 인증 기관(CA) 인증서를 넣으십시오. 자세한 내용은 2.11장, 변형: 외부 저장소, TLS 및 인그레스에 나와 있습니다.
# harrow-values.yaml (Helm values): Harrow's own PostgreSQL, every other store in the cluster
dataTier:
postgres:
mode: external
sslmode: verify-full
external:
host: pg.harrow.example
existingSecret: harrow-postgresOpenBao 쌍은 예외입니다. 보관(custody) Job이 설치 환경 내부에서 이를 초기화하기 때문에 항상 설치 환경 내부에서 실행됩니다.
서비스 간 ID
Nexus는 서비스 메시 없이 실행됩니다. 상호 TLS는 차트가 cert-manager를 통해 생성하는 로컬 인증 기관(CA)에서 제공되며, cert-manager가 먼저 설치되어 있어야 합니다(v1.21.3 테스트 완료).
자체 서명된 Issuer가 10년 동안 유효한 ECDSA(타원 곡선 디지털 서명 알고리즘) P-256 기반의 CA 인증서 nexus-local-ca을 하나 생성합니다. 두 번째 Issuer는 해당 CA로 서명합니다. 설치 환경 내부의 TLS 서버를 호출하는 모든 워크로드는 90일 동안 유효하고 만료 15일 전에 갱신되는 <service-account>-client-tls라는 자체 클라이언트 인증서를 받습니다. 이 인증서의 유일한 이름은 SPIFFE ID 형식의 통합 리소스 식별자(URI)입니다:
spiffe://cluster.local/ns/<namespace>/sa/<service-account>
각 워크로드는 자체 인증서 Secret에서 ca.crt으로 CA의 공개 인증서를 찾습니다. 어떤 파드도 CA의 키를 마운트하지 않으며, trust-manager는 필요하지 않습니다.
세 개의 서비스가 인증서로 호출자를 검증합니다. nexus-auth는 두 번째 리스너인 포트 8443에서 검증하며, 클러스터 내부의 모든 호출자는 이 포트로 연결합니다. nexus-keys는 유일한 리스너에서 검증합니다. Probitas는 자체 인증서인 nexus-probitas-tls로 TLS를 제공하며, cert-manager가 이를 갱신할 때 다시 읽어들입니다. 어느 서비스도 X-Forwarded-Client-Cert 헤더를 신뢰하지 않습니다.
또한 각 워크로드는 /var/run/secrets/nexus에서 호출하는 서비스당 하나씩, 해당 서비스를 오디언스(audience)로 하는 1시간짜리 Kubernetes 토큰을 받습니다. ConfigMap nexus-service-identities는 각 <namespace>/<service-account>을 서비스 또는 플러그인 이름에 매핑하며, 여기서 누락된 워크로드는 ID가 없으므로 거부됩니다. 오케스트레이터와 Probitas는 Kubernetes API를 통해 이 토큰들을 확인합니다. 실행 중인 서비스 중 이 두 서비스만이 system:auth-delegator를 보유하거나 API 토큰을 마운트하며, 토큰을 가진 다른 유일한 워크로드는 설치 시 실행되는 보관(custody) Job입니다.
네트워크 정책은 ID가 차단하지 않는 부분을 닫습니다. 차트는 기본 거부(default deny)에서 시작한 다음, 설치 환경 자체 파드들 간의 트래픽, DNS(Domain Name System), 인그레스 컨트롤러의 네임스페이스(networkPolicy.ingressNamespace, 기본값 kube-system)에서 세 개의 퍼블릭 Service로 향하는 트래픽, 그리고 두 토큰 검토자(reviewer)를 위한 API 서버 트래픽을 허용합니다. OpenBao 파드는 플랫폼의 나머지 부분과 다른 레이블을 가지므로 네임스페이스 내 개방 규칙이 적용되지 않으며, 오직 nexus-keys, 그 Job들 및 보관 Job만이 포트 8200을 통해 통과할 수 있습니다. 메일 릴레이와 같이 워크로드가 네임스페이스 외부에서 도달해야 하는 다른 모든 대상은 기본적으로 비어 있는 networkPolicy.externalEgressCIDRs에 추가합니다.
마이그레이션과 스키마 원장
마이그레이션은 post-install 및 pre-upgrade에서 Helm 훅으로 실행됩니다. post-install 훅은 릴리스의 Deployment들이 생성된 후에 실행됩니다. 따라서 첫 설치 시에는 스키마가 아직 존재하지 않는 상태에서 서비스들이 시작되므로, 역할도, 비밀번호도, 테이블도 없는 데이터베이스에 대해 크래시 루프(crash-loop)에 빠지게 될 것입니다. Nexus는 원장(ledger)을 통해 이를 방지합니다.
훅은 가중치(weight) 순서대로 실행되며, Helm은 다음 가중치가 시작되기 전에 각 Job이 완료되기를 기다립니다:
| 가중치 | 훅 | 수행 작업 |
|---|---|---|
| -30 | nexus-migrations-env 및 사전 요구 사항 |
마이그레이터의 자격 증명이 포함된 훅 전용 Secret과 보관 Job이 읽는 모든 항목을 생성합니다 |
| -20 | nexus-db-bootstrap |
nexus 및 nexus_alpha 데이터베이스, 마이그레이터 역할, 모든 서비스의 런타임 역할, 확장 기능 및 원장을 생성합니다 |
| -15 | nexus-openbao-custody-init |
키 저장소와 봉인 해제기를 초기화하고 설치 ID를 발행합니다 |
| -12 | nexus-graphrag-migrations |
nexus-auth의 베이스라인이 참조하는 객체들을 소유하는 GraphRAG의 스키마 |
| -10 | nexus-auth-migrations |
ID 스키마 |
| -5 | 오케스트레이터, 게이트웨이 및 Probitas 마이그레이션 | 각 서비스의 스키마; Probitas는 인증 테이블이 존재하는지 먼저 확인합니다 |
| 0 | nexus-alpha-bff-migrations |
콘솔 자체 데이터베이스 |
각 마이그레이션 Job에는 backoffLimit: 0이 설정되어 있으므로 마이그레이션이 실패하면 설치도 실패합니다.
원장은 체인 및 이미지 다이제스트당 하나의 행을 가지는 단일 테이블(nexus_release.schema_applied)입니다. 각 훅은 마이그레이션 러너가 반환된 후에만 자신의 행을 기록합니다. PostgreSQL을 사용하는 모든 Deployment는 초기화 컨테이너인 wait-for-schema를 포함하며, 이 컨테이너는 다른 어떤 것도 읽을 수 없도록 허용된 역할(nexus_ledger_reader)로 해당 테이블을 읽고 자신이 의존하는 모든 체인이 이번 릴리스의 이미지에 대한 행을 표시할 때까지 기다립니다. 그런 다음에야 서비스가 시작됩니다. 워크플로 워커는 오케스트레이터와 데이터베이스를 공유하므로 오케스트레이터의 체인을 기다리고, 스킬 엔진은 부트스트랩만 기다립니다.
3초마다 폴링하며(schemaWait.intervalSeconds), 1,800초(schemaWait.timeoutSeconds)가 지나면 여전히 누락된 체인의 이름을 나열하는 줄을 출력하고 포기합니다. 서비스 자체 컨테이너는 잘못된 스키마에 대해 절대 시작되지 않습니다.
kubectl -n nexus logs deploy/nexus-gateway -c wait-for-schema이것이 바로 helm install --wait을 절대 실행해서는 안 되는 이유입니다. --wait를 사용하면 Helm은 post-install 훅을 실행하기 전에 Deployment들을 기다리고, Deployment들은 훅을 기다립니다. 양쪽 모두 진행되지 않습니다. 해당 옵션 없이 설치한 후 나중에 기다리십시오. 2.6장, Kubernetes에 Community 설치하기에서 정확한 명령어를 안내합니다.
세 가지 축을 기준으로 한 격리
Nexus의 모든 읽기, 쓰기, 도구 호출 및 스킬 디스패치는 세 가지 축을 기준으로 범위가 지정(scoped)됩니다.
| 축 | 필드 | 분리 대상 |
|---|---|---|
| 테넌트(Tenant) | organization_id |
한 조직을 다른 조직으로부터 분리하는 엄격한 경계 |
| 소유자(Owner) | owner_user_id |
동일한 조직 내부에서조차 한 사람의 항목을 다른 모든 사람의 항목으로부터 분리 |
| 부서(Unit) | business_unit_id |
조직의 하위 구분(선택 사항) |
소유자 축은 사람들을 놀라게 하곤 합니다. 메일함이나 개인 노트북은 같은 부서에서 같은 역할을 가진 동료들에게서도 소유자 개인에게만 비공개로 유지됩니다. 관리자는 정책을 설정할 뿐 콘텐츠를 읽지는 않습니다.
이 축들은 오직 인증된 요청에서만 나오며 다른 어디에서도 나오지 않습니다. 환경 변수, 헤더, 쿼리 파라미터 또는 경로 세그먼트로 이를 설정할 수 없습니다. 조직 이름을 지정하는 요청 본문은 TENANT_NOT_A_PARAMETER과 함께 거부됩니다. 행이 어느 테넌트, 소유자 및 부서에 속하는지 명시할 수 없는 표면(surface)은 403 SCOPE_PREDICATE_MISSING와 함께 거부하며, 본문에는 확인된 축과 확인되지 않은 축이 나열됩니다. 더 넓은 범위의 읽기로 폴백(fallback)하는 일은 절대 없습니다.
이는 두 곳에서 동시에 적용됩니다.
데이터베이스 내부. 모든 서비스는 자체 런타임 역할로 연결합니다: ID 서비스는 nexus_auth, auth_app, auth_platform, Probitas는 nexus_probitas, nexus_probitas_ledger, 그리고 나머지 서비스들은 nexus_gateway, nexus_graphrag, nexus_skills, orchestrator_app, workflows_app 등입니다. 어느 것도 슈퍼유저가 아니며 BYPASSRLS 권한도 없습니다. 또한 자신이 사용하는 테이블을 소유하지도 않으므로 모든 행 수준 보안(RLS) 정책이 적용됩니다. 역할들은 연결 및 스키마 사용 권한만 부여하고 테이블 권한은 전혀 부여하지 않는 그룹인 nexus_runtime을 공유하며, 각 서비스는 자체 마이그레이션을 통해 자신의 테이블에 대한 권한을 부여받습니다. RLS 정책이 읽는 테넌트 설정은 소유자로서 실행되는 각 서비스의 bind_scope 함수를 통해서만 설정할 수 있습니다. 부트스트랩은 다른 모든 대상으로부터 set_config 권한을 회수하며, 오케스트레이터와 Probitas는 자신의 런타임 역할이 이를 직접 호출할 수 있는 경우 시작을 거부합니다(Probitas는 이를 DB_ROLE_SETS_SCOPE_DIRECTLY라고 명명합니다). 전체 설치 환경에서 유일한 슈퍼유저 연결은 부트스트랩 Job과 BFF의 프로비저닝 단계에 속합니다.
공유 범위 지정 쿼리 프리미티브(scoped-query primitive) 내부. 플랫폼의 모든 리포지토리와 SDK(소프트웨어 개발 키트)로 구축된 모든 플러그인은 확인된 범위로부터 SQL 조건절(predicate)을 생성하는 하나의 펜스(fence)를 상속받습니다. 이 범위 함수는 검증된 ID를 받으며 조직 파라미터가 없으므로 호출자가 이를 전달할 수 없고, 어떤 라우트도 이를 우회(opt out)할 수 없습니다.
테넌트 경계를 넘는 경우는 단 하나뿐이며, 그 범위도 좁습니다: 바로 기록된 권한 부여(grant)입니다. 행을 보유한 조직의 두 사람이 어느 조직이 어느 테이블을 언제까지 읽을 수 있는지를 기록합니다. 모든 읽기는 읽기 전용 트랜잭션으로 실행되며 양쪽 테넌트 모두에 기록됩니다. 소유자와 관리자는 절대 경계를 넘어 읽지 못하며, 읽는 측은 부여된 권한을 넓힐 수 없습니다.
AI 경로
호출자는 희망 사항을 표현합니다. AI Provider Router가 자격 증명을 소유하며 최종 선택을 내립니다.
Nexus의 모든 모델 호출은 라우터의 /internal/ai/* 라우트를 거치며, 라우터는 지정된 호출자만 허용합니다. 차트는 게이트웨이에 세 가지 목록을 설정합니다:
| 라우트 | 호출 가능 대상 |
|---|---|
| 채팅 및 채팅 스트리밍 | nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| 임베딩 및 재순위화(rerank) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
| 도구 실행을 포함한 기타 모든 작업 | nexus-orchestrator, nexus-workflows |
호출자 ID가 없는 호출은 403 MISSING_CALLER_IDENTITY로 거부되고, 목록에 없는 호출자는 403 UNAUTHORIZED_CALLER로 거부됩니다. 플러그인은 어떤 목록에도 없으며 이는 의도된 것입니다. 플러그인의 모델 호출은 UNO 디스패치를 통해 플러그인을 대신하여 이루어집니다.
호출자가 보낼 수 있는 것은 선호하는 제공자 및 모델, 그리고 최소 컨텍스트 길이나 도구 사용과 같은 기능 프로필로 구성된 희망 사항입니다. 라우터는 조직에서 해당 제공자를 활성화하고 자격 증명을 등록한 경우에만 희망 사항을 존중합니다. 그렇지 않으면 먼저 동일한 제공자 내에서 대체 모델을 찾고, 그다음에는 조직의 다른 제공자들에서 대체 모델을 찾습니다. 기능 프로필은 필터링 역할만 하며, 그 안의 데이터 레지던시(data-residency) 요구 사항은 엄격하게 적용됩니다. 적합한 것이 하나도 없을 때는 폴백 모델이 없으며, 호출자는 콘솔이 관리자에게 표시하는 해결 방법 문자열과 함께 422 MODEL_CAPABILITY_UNAVAILABLE 또는 422 NO_PROVIDER_FOR_ROLE를 받게 됩니다.
키는 조직에 귀속됩니다. 각 조직의 관리자는 콘솔에서 자체 제공자 키를 풀에 넣으며, 라우터는 호출 시점에 이를 확인합니다. 어떤 모델 키도 차트 값으로 존재하지 않으며 Nexus와 함께 제공되지도 않습니다. 키가 없는 조직은 AI 답변을 받을 수 없으며 콘솔에 그 사실이 명확히 표시됩니다. 다른 곳에서 그 공백을 메우지 않습니다.
두 가지 차트 값이 라우터를 구성합니다. ai.localProvider.baseUrl은(는) 다른 제공자와 마찬가지로 라우팅되어 사용자가 운영하는 OpenAI 호환 모델 서버를 지정합니다. ai.installationHosts은(는) 라우터가 설치 내부에 있는 것으로 간주하는 프라이빗 이름의 모델 서버들을 나열합니다. GraphRAG 역시 해당 콘텐츠를 소유한 조직의 자격으로 라우터를 통해 임베딩합니다. 기본 임베딩 모델은 그래픽 카드 없이 클러스터에서 실행되며, 호스팅된 임베딩의 사용 여부는 각 조직의 선택에 따릅니다.
텔레메트리 없음
사용자가 직접 전송하지 않는 한 어떤 것도 설치 환경을 벗어나지 않습니다. 차트의 telemetry.enabled 값은 오직 false만 될 수 있으며, 스키마는 그 외의 모든 값을 거부합니다. 데이터 계층 자체의 보고 기능도 꺼져 있습니다. Neo4j의 사용량 보고서와 Qdrant의 원격 측정은 차트에서 비활성화되어 있습니다.
기본값인 networkPolicy.enabled이(가) 켜져 있으면, networkPolicy.externalEgressCIDRs에 대상을 나열하지 않는 한 어떤 파드도 인터넷에 연결할 수 없습니다. 호스팅된 모델 제공자가 그러한 대상 중 하나이며, 메일 릴레이도 마찬가지입니다.
동일한 규칙으로 인해 눈에 띄는 기본값 하나가 변경되었습니다. 가입을 위한 nexus-auth의 CAPTCHA에는 인터넷 서비스가 필요하므로 설치 환경에서는 꺼져 있으며, 외부인의 가입은 관리자의 승인을 기다립니다(403 SIGNUP_REQUIRES_APPROVAL). 호스팅 네트워크에서의 가입을 차단하는 필터링도 꺼져 있는데, 이는 Nexus에서 기본 제공하지 않는 라이선스 데이터베이스가 필요하기 때문입니다. 따라서 해당 필터링 기능은 사용할 수 없습니다.

