멀티테넌시 설정

개요

|Fess|의 멀티테넌시 기능을 사용하면 단일 |Fess| 인스턴스에서 여러 테넌트(조직, 부서, 고객 등)를 분리하여 운영할 수 있습니다.

가상 호스트 기능을 사용하여 각 테넌트에 대해:

독립된 검색 UI
분리된 콘텐츠
커스터마이즈된 디자인

을 제공할 수 있습니다.

현재의 가상 호스트는 검색 결과 필터링 외에도, 라벨, 관련 콘텐츠, 관련 쿼리, 디자인(테마) 등 |Fess|의 각 기능에 반영됩니다.

가상 호스트 기능

가상 호스트는 HTTP 요청의 호스트명에 따라 다른 검색 환경을 제공하는 기능입니다.

구조

사용자가 ``tenant1.example.com``에 접속
|Fess|가 호스트명을 식별
해당하는 가상 호스트 설정을 적용
테넌트 고유의 콘텐츠와 UI를 표시

가상 호스트 헤더 설정

가상 호스트 기능을 활성화하려면 HTTP 요청의 헤더와 가상 호스트 키의 대응 관계를 설정합니다. 설정 방법은 다음 두 가지가 있습니다.

관리 화면(권장): “시스템” → “전체”의 “가상 호스트” 항목에서 설정합니다. 이 값은 시스템 설정으로 저장되며 재시작 후에도 유지됩니다. fess_config.properties 의 ``virtual.host.headers``보다 우선 적용됩니다.
설정 파일: fess_config.properties``의 ``virtual.host.headers 속성에서 설정합니다.

어느 방법을 사용하든 설정값의 형식은 동일합니다.

설정 형식

각 줄에 헤더명:헤더값=가상호스트키 형식으로 지정합니다:

여러 가상 호스트를 설정하는 경우 줄바꿈으로 구분하여 기술합니다.

매칭 동작

|Fess|는 요청을 받을 때마다 설정된 각 줄의 “헤더명”에 해당하는 요청 헤더의 값을 설정된 “헤더값”과 비교합니다.

헤더값 비교는 대소문자를 구분하지 않습니다.
설정된 줄을 위에서부터 순서대로 평가하여 처음으로 일치한 줄의 가상 호스트 키를 적용합니다.
일치하는 줄이 없는 경우 가상 호스트 없음(공통 환경)으로 처리됩니다.
판정 결과는 요청마다 캐시됩니다.

가상 호스트 키 제약

가상 호스트 키에는 다음과 같은 제약이 있습니다:

사용 가능한 문자는 영숫자와 밑줄( a-zA-Z0-9_ )뿐입니다. 그 외의 문자는 자동으로 제거됩니다.
다음 키 이름은 예약어이므로 사용할 수 없습니다: admin , common , error , login , profile

관리 화면에서 설정

크롤 설정

웹 크롤 설정에서 가상 호스트를 지정하여 콘텐츠를 분리할 수 있습니다:

관리 화면에 로그인
“크롤러” → “웹”에서 크롤 설정 생성
“가상 호스트” 필드에서 설정된 가상 호스트 키를 선택(복수 선택 가능)
이 설정으로 크롤된 콘텐츠는 지정한 가상 호스트에서만 검색 가능

참고

“가상 호스트” 필드는 웹·파일 시스템·데이터 스토어의 각 크롤 설정에 제공됩니다. 여기에서 선택한 가상 호스트 키가 크롤된 각 문서에 부여되어, 검색 시 현재 가상 호스트로 필터링됩니다.

접근 제어

가상 호스트와 역할의 조합

가상 호스트와 역할 기반 접근 제어를 조합하여 더 세밀한 접근 제어가 가능합니다.

크롤 설정에서 가상 호스트와 퍼미션을 함께 설정합니다:

역할 기반 검색

자세한 내용은 :doc:`security-role`를 참조하세요.

UI 커스터마이즈

각 가상 호스트에 대해 UI를 커스터마이즈할 수 있습니다.

테마 적용

가상 호스트별로 다른 테마 적용:

“시스템” → “디자인”에서 테마 설정
가상 호스트 설정에서 테마 지정

커스텀 CSS

가상 호스트별로 커스텀 CSS를 적용하려면 관리 화면의 “시스템” → “디자인”에서 CSS 파일을 편집합니다. 가상 호스트 키에 해당하는 뷰 디렉토리에 커스텀 템플릿을 배치할 수도 있습니다.

라벨 설정

가상 호스트별로 표시할 라벨 제한:

라벨 유형 설정에서 가상 호스트 지정
지정한 가상 호스트에서만 라벨이 표시됨

API 경유 접근

검색 API에 대한 요청도 UI와 마찬가지로 요청의 호스트명(설정한 헤더, 일반적으로 Host 헤더)에 의해 가상 호스트가 판정됩니다. 예를 들어 tenant1.example.com``으로의 요청은 자동으로 ``tenant1 가상 호스트에 스코프되어 해당 가상 호스트의 콘텐츠만 검색 대상이 됩니다.

API 요청

액세스 토큰을 사용하여 인증하는 경우 Authorization 헤더에 Bearer 형식으로 지정합니다:

참고

액세스 토큰은 특정 가상 호스트에 귀속되지 않습니다. 토큰은 어떤 가상 호스트에 대해서도 유효하며, 대상 가상 호스트는 요청을 전송하는 호스트명에 의해 결정됩니다. 동일한 토큰을 다른 호스트명으로 전송하면 다른 가상 호스트에 스코프됩니다. 가상 호스트와 독립적으로 접근 범위를 제어하려면 역할 기반 접근 제어( 역할 기반 검색 설정 )와 함께 사용하세요.

DNS 설정

멀티테넌시를 구현하기 위한 DNS 설정 예:

동일 서버로의 서브도메인

리버스 프록시 설정

Nginx를 사용한 리버스 프록시 설정 예:

server {
    server_name tenant1.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

server {
    server_name tenant2.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

데이터 분리

완전한 데이터 분리가 필요한 경우 다음 접근 방식을 검토하세요:

인덱스 레벨 분리

각 테넌트에 별도의 Fess 인스턴스와 인덱스를 사용:

# 테넌트1용 Fess 인스턴스 (fess_config.properties)
index.document.search.index=fess_tenant1.search

# 테넌트2용 Fess 인스턴스 (fess_config.properties)
index.document.search.index=fess_tenant2.search

참고

``index.document.search.index``는 인스턴스당 하나의 값만 설정할 수 있습니다. 인덱스 레벨의 완전한 분리를 위해서는 테넌트별로 별도의 Fess 인스턴스를 실행하거나 커스텀 구현이 필요합니다. 일반적인 멀티테넌시에서는 가상 호스트 기능에 의한 논리적 분리로 충분합니다.

모범 사례

명확한 명명 규칙: 가상 호스트와 역할에 일관된 명명 규칙 사용
테스트: 각 테넌트에서의 동작을 충분히 테스트
모니터링: 테넌트별 리소스 사용량 모니터링
문서화: 테넌트 설정 문서화

제한 사항

관리 화면은 모든 테넌트에서 공유됩니다
시스템 설정은 모든 테넌트에 영향을 미칩니다
일부 기능은 가상 호스트에 대응하지 않을 수 있습니다

참고 정보

역할 기반 검색 설정 - 역할 기반 접근 제어
가상 호스트 - 가상 호스트 설정 상세
페이지 디자인 - 디자인 커스터마이즈