Skip to main content

JunkBox Hub와 홈서버 Docker 서비스 로그인 통합 검토

작성일: 2026-10-26 (KST)
상태: 읽기 전용 조사 결과. 구현·설정 변경 전 검토용.
대상: 다음 세션에서 Hub 인증 개선, Nginx 게이트웨이 구성, 서비스별 단계적 전환을 요청할 때 사용할 기준 문서.

1. 핵심 결론​

  1. 브라우저에서 Hub 로그인 한 번으로 끝나는 서비스가 여러 개 있다. 프록시 사용자 헤더를 공식 지원하는 Linkding, Moonlight Web Stream, Guacamole, CloudBeaver CE, File Browser가 대표적이다. Glances처럼 현재 자체 로그인이 없는 화면은 Hub를 유일한 진입 인증으로 둘 수 있다.
  2. Transmission도 웹 UI는 Hub 인증으로 기존 로그인을 대체할 수 있다. 다만 웹 UI와 RPC 클라이언트가 같은 9091 포트를 사용하므로 비브라우저 클라이언트의 인증 경로를 별도로 설계해야 한다. 기존 USER/PASS를 유지하며 Hub 게이트를 더하면 로그인만 두 번 하게 된다.
  3. 포털의 SERVICE 등록과 실제 Docker 실행 목록은 다르다. 이 문서는 2026-10-26에 실행 중인 외부 앱 15개를 기준으로 한다. 포털에 있지만 현재 컨테이너로 실행되지 않는 Vault, Home Assistant, Jenkins, ipTIME은 아래 우선순위에서 제외한다. 반대로 실행 중인 Apprise API와 WebDAV는 포함한다.
  4. 공통 선행 조건은 우회 경로 차단이다. 조사 대상 앱의 호스트 포트는 현재 모두 0.0.0.0에 게시되어 있다. Nginx가 인증하더라도 직접 포트로 접근할 수 있으면 통합 인증이 성립하지 않는다. 사용자 헤더를 신뢰하는 앱은 헤더 위조까지 가능해진다.
  5. 현재 Hub는 OIDC 제공자가 아니다. Komga, Portainer 등의 제품 OIDC/OAuth 연동은 유망하지만, Hub JWT와 로그인 화면만으로 즉시 켤 수 없다. 표준 IdP 도입 또는 Hub의 제공자 기능 구현을 별도 아키텍처 결정으로 다뤄야 한다.

용어와 평가 기준​

용어의미사용자 경험
진입 보호프록시가 Hub 세션을 검사하지만 서비스 자체 인증은 유지서비스 로그인이 남으면 두 번 로그인
웹 로그인 대체서비스가 프록시 사용자 헤더를 받아 자체 세션을 만들거나, 원래 자체 인증이 없는 웹 화면을 Hub로 보호브라우저에서는 Hub 한 번
OIDC/OAuth 로그인 대체서비스가 IdP에서 사용자를 인증하고 자체 계정과 연결브라우저에서는 한 번. 서비스 권한은 별도 관리
API·RPC·WebDAV 인증브라우저 리다이렉트를 수행하지 않는 클라이언트의 자격 증명대개 Hub 브라우저 쿠키와 분리 필요

이 문서의 권장은 Hub 로그인 한 번이라는 편의 개선과 현재 제품 기능을 함께 고려한 것이다. 단순히 Hub 로그인을 하나 더 얹는 방식은 권장으로 세지 않는다.

2. 조사 범위와 현재 구조​

2.1. 조사 근거​

  • 실행 상태와 포트: 2026-10-26 KST의 docker ps, 일부 컨테이너 이미지 메타데이터.
  • 운영 Compose 원본: /home/sleepzz/docker-compose/<서비스>/docker-compose.yaml.
  • Hub 인증 코드·정책: /home/sleepzz/dev/workspaces/junkbox/apps/hub-api, /home/sleepzz/dev/workspaces/junkbox/libs/shared-core, apps/hub-api/var/auth-policy.yml.
  • Nginx 현재 설정: /data001/nginx/conf.d, /data001/nginx/snippets/nexus_auth.conf.
  • Hub 포털: /sorc001/junkbox/db/hub.sqlite3의 tb_portal_menu_m을 읽기 전용으로 조회.
  • 제품 기능: 문서 끝의 제품 공식 문서와 프로젝트 원본. latest 태그의 실제 설치 버전과 최신 문서 기능은 다를 수 있으므로 적용 직전 이미지 버전을 재확인한다.

2.2. 현재 Hub 인증과 Nginx의 간극​

  • JunkBox 앱은 Hub의 JUNKBOX_AUTH JWT 쿠키와 allowed_modules, Hub 내부 세션 검증 API를 사용한다. 운영 쿠키 도메인은 .sleepzz.xyz, Secure=true, SameSite=lax이며 세션 만료는 120분, 슬라이딩 갱신 임계값은 30분이다.
  • Hub의 GET /api/auth/verify?module=...는 JWT와 Hub 세션을 검증하고 사용자 식별자를 X-Nexus-User 응답 헤더로 반환한다. 외부 프록시에서 재사용하려면 서비스별 권한 정책, 인증 실패 응답, 캐시·세션 갱신 책임을 명확히 해야 한다.
  • Hub의 로그인 redirect 허용 origin은 현재 제한 목록에 기반한다. 새 서비스의 복귀 주소를 무조건 허용하거나 요청 헤더에서 그대로 만들면 열린 리다이렉트가 될 수 있다. 등록된 서비스 URL과 정확히 대조해야 한다.
  • 기존 /data001/nginx/snippets/nexus_auth.conf는 예전 nexus-system 주소, EXTERNAL 모듈, 이전 로그인 URL을 사용한다. 현재 Hub의 사용자 허용 모듈에는 EXTERNAL이 없으므로 그대로 쓸 수 없다. Guacamole의 활성 Nginx 설정은 현재 Basic Auth를 쓰며 이 스니펫을 포함하지 않는다.
  • 현재 Nginx의 활성 사이트 설정으로 확인된 것은 Guacamole과 Home Assistant 등 일부다. 다른 서비스의 외부 도메인이 Cloudflare Tunnel에서 Nginx를 경유하는지 직접 원본으로 가는지는 현지 Tunnel 설정을 확인해야 한다. 서비스별 실제 요청 경로 확인이 배포 변경의 첫 단계다.
  • .sleepzz.xyz 범위의 Hub JWT 쿠키가 외부 제품 하위 도메인에도 전송될 수 있다. 서비스·로그·취약점에 JWT가 노출될 범위가 커진다. 장기적으로 Hub 전용 쿠키와 게이트웨이 세션, 또는 표준 OIDC 토큰 흐름을 분리하는 설계를 권장한다.

2.3. 범위 밖의 실행 컨테이너​

junkbox-* 컨테이너는 이미 Hub 인증을 사용하므로 제외했다. nginx, cloudflared, guacd, postgres는 웹 로그인 대상이 아닌 게이트웨이·백엔드·DB로 분류했다. 단, 이들의 네트워크·라우팅·서비스 간 자격 증명은 아래 구현에 영향을 준다. PostgreSQL 5432 공개 여부는 인증 통합과 별개의 접근 통제 과제다.

3. 전체 권장 순위와 재분류​

순위는 Hub 로그인 한 번의 실현 가능성, 편의 효과, 기존 기능 보존, 작업량과 위험을 함께 본 적용 순서다. 앞 순위가 무조건 쉬운 작업이라는 뜻은 아니다. 각 단계의 선행 조건을 충족한 뒤 진행한다.

순위그룹실행 중인 서비스브라우저에서 Hub 한 번범위와 핵심 조건
1권장·쉬움Glances가능현재 자체 인증 없이 웹 모드. API 소비자 확인
2권장·일부 수정Linkding가능프록시 헤더 인증, 기존 사용자·API 토큰 매칭
3권장·일부 수정Moonlight Web Stream가능공식 forwarded_header 기능. WebSocket·WebRTC 확인
4권장·일부 수정Guacamole가능헤더 인증 확장 설치됨. Nginx Basic Auth와 설정 교체
5권장·일부 수정CloudBeaver CE가능CE의 프록시 헤더 인증. DB 자격 증명은 별도
6권장·선행 보안 작업 필수File Browser가능직접 포트 차단과 헤더 덮어쓰기 선행
7조건부 권장·웹 UITransmission가능기존 RPC 인증을 끌 수 있지만 RPC 클라이언트 경로 분리 필요
8조건부 권장·웹 UIApprise API가능관리 UI는 Hub 보호, 알림 API는 서비스 간 인증 유지
9권장·OIDC 기반 작업Komga가능Hub 또는 별도 IdP가 OIDC 제공 필요
10권장·OAuth 기반 작업Portainer CE가능OAuth 제공자와 사용자·팀·관리자 권한 매핑 필요
11조건부·버전/사용 조건 확인LiteLLM가능성 있음현재 고정 이미지가 오래됨. UI SSO 지원·사용 조건 확인
12조건부·웹에 한정Jellyfin웹에서 가능성 있음SSO 플러그인·버전 호환, TV·모바일 로그인 한계
13우선순위 낮음Redmine추가 연동 필요플러그인/외부 인증 검토. 사용자·프로젝트 권한 이관
14현재 방식에선 비권장YDM기능 손실 없이 어려움현재 다중 사용자·내부 로그인. 끄면 사용자별 파일·권한 손실
15비권장WebDAV일반 DAV 클라이언트에 부적합HTTP 자격 증명을 유지하고 접근망만 제한 권장

4. 공통으로 필요한 변경​

4.1. Hub 인증 계약​

  1. 외부 서비스를 서비스 ID → 공개 origin/복귀 URL → 허용 사용자 또는 그룹 → 전달 가능한 사용자 필드로 등록한다. 포털의 SERVICE 메뉴는 링크 목록이므로 인증 권한 정의와 혼동하지 않는다. 기존 HUB 관리자 권한을 모든 서비스 접근권으로 재사용하지 않는 편이 좋다.
  2. 프록시 서브요청 전용 검증 경로를 정의한다. 쿠키에서 JWT를 읽고 Hub의 영속 세션·서비스별 접근권을 검사한 뒤 2xx/401/403을 일관되게 반환한다. 사용자 식별자 헤더는 성공 시에만 반환한다. 기존 /api/auth/verify 재사용 여부는 이 계약과 서비스별 권한 검증을 검토한 뒤 결정한다.
  3. 로그인 복귀 주소는 요청의 Host를 맹신하지 않고 등록된 서비스 URL에 매칭한다. 로그아웃, Hub 세션 만료, 권한 회수와 각 서비스 자체 세션의 잔존 기간을 정의한다. Nginx가 매 요청을 검증하더라도 직접 포트가 열려 있으면 우회할 수 있다.
  4. JUNKBOX_AUTH 쿠키를 모든 외부 하위 도메인에 보내는 현재 방식의 노출 범위를 검토한다. 최소한 상위 프록시와 제품 로그에서 쿠키·JWT를 기록하지 않게 하고, 장기 목표로 Hub 전용 쿠키/게이트웨이 세션 또는 OIDC 분리를 설계한다.
  5. OIDC/OAuth는 별도 결정이다. 검증된 IdP를 운영하고 Hub를 그 IdP의 클라이언트로 연동할지, Hub에 표준 제공자 기능을 구현할지 먼저 정한다. 후자를 택하면 클라이언트 등록, 인가 코드·PKCE, 토큰·JWKS·키 회전, discovery/userinfo, 사용자 claim, 로그아웃, 감사 기록을 포함해 설계해야 한다.

4.2. Nginx·Cloudflared·Docker 네트워크​

  1. 서비스별 공개 주소가 Cloudflare Tunnel → Nginx → 앱을 거치는지 확인한다. Nginx를 건너뛰는 Tunnel route나 LAN 직접 포트가 있으면 인증 게이트를 적용해도 우회된다.
  2. 예전 nexus_auth.conf를 현재 Hub 주소·경로·정책에 맞는 공통 auth_request 설정으로 교체한다. 401은 Hub 로그인으로 복귀시키고 403은 권한 없음으로 처리한다. 로그인 URL의 redirect는 등록된 URL로 만든다. auth_request_set으로 검증 응답의 사용자 ID를 받아 프록시가 인증 헤더를 덮어쓴다. 클라이언트가 보낸 동명 헤더는 신뢰하지 않는다.
  3. 헤더 인증 서비스와 보호 웹 UI의 호스트 ports 게시를 없애거나, 구성에 맞게 루프백에 묶거나, 방화벽·네트워크 ACL로 Nginx만 접근하게 한다. Docker serverzz-net에 붙은 다른 컨테이너에서도 우회 가능한지 확인한다. 필요하면 인증 프록시와 앱 전용 네트워크를 사용한다.
  4. 브라우저 UI와 비브라우저 API/RPC/WebDAV를 경로와 인증 정책에 따라 나눈다. 단순히 /api/*를 전부 예외 처리하면 브라우저 UI의 API도 우회할 수 있다. 서비스별 실제 요청과 클라이언트를 먼저 조사한다.
  5. Moonlight·Guacamole·CloudBeaver의 WebSocket, 장시간 세션, 리다이렉트, 대용량 요청을 검증한다. Hub 장애 시 인증을 우회해 열지 않고 실패 차단한다.

5. 서비스별 변경 항목​

아래 경로는 검토·수정 후보다. 아직 파일은 변경하지 않았다. 비밀번호·토큰 값은 이 문서에 기록하지 않는다.

5.1. Glances — 순위 1, 권장·쉬움​

  • 현재: /home/sleepzz/docker-compose/glance/docker-compose.yaml의 GLANCES_OPT=-w; 61208 공개. 호스트 및 Docker 정보 노출도가 높고 Docker socket을 마운트한다.
  • 변경: 공개 도메인을 인증 Nginx로 연결하고 Hub 검증을 UI·API 경로에 적용한다. Compose의 61208 직접 게시를 차단한다. 별도 API/모니터링 소비자가 있다면 브라우저와 다른 인증 계약을 둔다.
  • 검증: 비로그인 401/리다이렉트, 로그인 후 UI·차트·API 호출, 직접 포트 차단, Hub 장애 시 차단.

5.2. Linkding — 순위 2, 권장·일부 수정​

  • 현재: /home/sleepzz/docker-compose/linkding/docker-compose.yaml에서 8084 공개. 프록시 인증·OIDC 설정은 사용하지 않는다.
  • 변경: Compose에 LD_ENABLE_AUTH_PROXY, 사용자명 헤더명, 로그아웃 URL을 설정한다. Nginx에서 Hub 사용자 헤더를 덮어써 전달한다. 기존 Linkding 계정과 Hub 사용자 ID의 일치·계정 자동 생성 정책을 정한다. 8084 직접 접근을 막는다.
  • 검증: 기존 북마크 소유자 유지, 신규 계정 권한, 로그아웃, 브라우저 확장과 REST API 토큰 호출. Linkding 문서는 외부 API 클라이언트에 별도 경로가 필요할 수 있다고 설명한다.

5.3. Moonlight Web Stream — 순위 3, 권장·일부 수정​

  • 현재: /home/sleepzz/docker-compose/moonlight-web-stream/docker-compose.yaml에서 6001과 UDP 스트리밍 포트 게시. /data001/moonlight-web-stream/config.json의 web_server.forwarded_header는 현재 null이다.
  • 변경: 공식 web_server.forwarded_header.username_header 설정으로 Nginx가 전달하는 사용자 헤더를 지정한다. 자동 사용자 생성과 기본 역할을 검토한다. 6001 직접 접근을 막고 WebSocket·WebRTC·UDP 경로의 접근 정책을 구분한다.
  • 검증: 기존 사용자·호스트 연결, 신규 사용자에게 부여되는 역할, 스트림 연결·재연결, WebSocket과 UDP, 로그인·로그아웃. 이전 세션의 '프록시 진입 보호만 가능' 평가는 최신 공식 문서 확인 후 철회한다.

5.4. Guacamole — 순위 4, 권장·일부 수정​

  • 현재: /home/sleepzz/docker-compose/guacamole/docker-compose.yaml에 헤더 인증 관련 환경변수가 있으나 공식 문서의 HTTP_AUTH_ENABLED/HTTP_AUTH_HEADER 이름과 다르다. guacamole-auth-header-1.6.0.jar는 설치·로드됨. /data001/nginx/conf.d/guacamole.conf에는 Nginx Basic Auth가 있다. Guacamole 8081도 직접 게시돼 있다.
  • 변경: 설치 이미지와 확장 버전 호환을 확인한 뒤 공식 변수명·사용자 헤더를 맞춘다. Nginx Basic Auth를 Hub 서브요청으로 교체하고, 기존 사용자·연결 권한을 매칭한다. 8081 직접 접근을 막고 입력 헤더를 덮어쓴다.
  • 검증: Hub 사용자별 연결 목록, 권한 없는 연결 거부, WebSocket RDP/SSH 세션, 장시간 연결, 로그아웃·Hub 세션 만료. 헤더 인증은 연결 정보를 공급하는 기존 인증 확장과 함께 사용해야 한다.

5.5. CloudBeaver CE — 순위 5, 권장·일부 수정​

  • 현재: /home/sleepzz/docker-compose/cloudbeaver/docker-compose.yaml에서 8978 직접 게시. 현재 런타임 설정에 프록시 인증 제공자 항목이 없다.
  • 변경: CloudBeaver CE의 reverseProxy 인증 제공자를 런타임 설정 또는 관리자 설정에 등록하고 사용자 헤더·자동 생성·팀 매핑을 정한다. Nginx의 사용자·팀 헤더를 신뢰된 값으로 덮어쓰고 8978 직접 접근을 막는다.
  • 검증: 기존 관리자 접근, 신규 사용자 기본 권한, DB 연결별 자격 증명, WebSocket, CSRF, 로그아웃. 화면 SSO가 DB 자체 인증을 대신하지는 않는다.

5.6. File Browser — 순위 6, 권장·선행 보안 작업 필수​

  • 현재: /home/sleepzz/docker-compose/filebrowser/docker-compose.yaml에서 8082 공개. 파일 저장 경로가 마운트돼 있다.
  • 변경: 먼저 8082 직접 접근과 Docker 네트워크 우회를 차단한다. 그 다음 File Browser의 auth.method=proxy와 신뢰할 사용자 헤더를 설정하고 Nginx에서 헤더를 덮어쓴다. 기존 사용자명·권한·파일 범위를 맞춘다.
  • 검증: 직접 포트 및 임의 사용자 헤더로 접근 불가, 관리자 위장 불가, 기존 계정 권한 유지, 다운로드·업로드·공유 링크. 프로젝트는 헤더 위조 위험을 공식 문서로 경고한다. 직접 접근 차단 전에는 인증 방식을 전환하지 않는다.

5.7. Transmission — 순위 7, 조건부 권장·웹 UI​

  • 현재: /home/sleepzz/docker-compose/transmission/docker-compose.yaml에 USER/PASS가 있고 9091을 직접 게시한다. 런타임 settings.json에서 RPC 인증은 켜져 있고 RPC 바인딩은 0.0.0.0이다.
  • 변경: 실제 사용하는 RPC 클라이언트와 호출 출처를 먼저 목록화한다. 웹 UI는 Nginx Hub 인증을 거치게 하고 직접 9091 접근을 차단한다. 웹 경로에서 기존 인증을 해제하려면 RPC 클라이언트의 별도 자격·경로·네트워크 정책을 먼저 마련해야 한다. 포트 51413 TCP/UDP는 피어 통신이므로 웹 인증 경로와 구별한다.
  • 검증: Hub 한 번으로 웹 UI 접속, 토렌트 추가·삭제, RPC 클라이언트 유지, 409 세션 ID 처리, 직접 포트 우회 불가. USER/PASS를 유지하면 이중 로그인이라는 점을 전환 목표에 명시한다.

5.8. Apprise API — 순위 8, 조건부 권장·웹 UI​

  • 현재: /home/sleepzz/docker-compose/apprise-api/docker-compose.yaml에서 APPRISE_API_ONLY=no, STRICT_MODE=yes; 웹 UI가 활성화돼 있고 8086이 직접 게시돼 있다. 현재 Compose에는 APPRISE_AUTH_REQUIRED 설정이 없다.
  • 변경: 관리 UI는 Hub 게이트로 보호하고 직접 포트를 막는다. Message API 등 알림 발송 클라이언트가 쓰는 Apprise API는 브라우저 쿠키가 아닌 서비스 간 자격·네트워크 정책으로 보호한다. 어떤 URL이 UI·관리 API·발송 API인지 실제 트래픽으로 확인해 경계를 나눈다.
  • 검증: 관리 UI, 설정 조회·수정 권한, 정상 알림 발송, 비인가 API 호출 거부, Hub 장애 시 UI 차단.

5.9. Komga — 순위 9, 권장·OIDC 기반 작업​

  • 현재: /home/sleepzz/docker-compose/komga/docker-compose.yaml에서 25600 직접 게시. OIDC 관련 설정은 현재 Compose에 없다.
  • 변경: IdP 결정 후 Komga의 OIDC client ID/secret·issuer·callback을 설정한다. Hub 사용자 이메일과 기존 Komga 사용자 이메일 매칭, 자동 계정 생성, 라이브러리 권한을 정한다. 25600 접근 경로를 정리한다.
  • 검증: 기존 열람 기록·라이브러리 권한, 새 계정, 모바일·리더 API 클라이언트, 로그아웃.

5.10. Portainer CE — 순위 10, 권장·OAuth 기반 작업​

  • 현재: /home/sleepzz/docker-compose/portainer/docker-compose.yaml에서 9000/8000 게시, Docker socket 마운트. OAuth 설정은 Compose만으로 판단할 수 없고 Portainer 관리 설정에서 확인해야 한다.
  • 변경: IdP 결정 후 Portainer의 Custom OAuth를 설정한다. 사용자 식별자·자동 생성·기본 팀·관리자 그룹 매핑을 신중히 정한다. 최초 관리자 계정의 비상 복구 경로를 유지하고 직접 관리 포트를 제한한다.
  • 검증: 일반 사용자에게 Docker 관리자 권한이 잘못 부여되지 않는지, 기존 관리자·팀, IdP 장애 복구, 포트 직접 접속 차단.

5.11. LiteLLM — 순위 11, 조건부·버전/사용 조건 확인​

  • 현재: /home/sleepzz/docker-compose/litellm/docker-compose.yaml의 이미지가 main-v1.60.0으로 고정돼 있고 8083을 게시한다. 현재 최신 문서의 SSO 제공 범위를 이 설치 버전에 그대로 적용할 수 없다.
  • 변경: 이미지 업그레이드 가능성, 현 버전의 UI SSO 기능과 사용 조건을 먼저 확인한다. 관리 UI와 모델 API를 구별하고 API 키·마스터 키 인증을 유지한다. 관리 UI만 Nginx로 보호하는 방식은 가능하지만 기존 UI 로그인이 남으면 편의상 SSO가 아니다.
  • 검증: UI 관리자 로그인과 권한, 모델 API 키 호출, 내부 JunkBox AI 호출, 업그레이드 호환성.

5.12. Jellyfin — 순위 12, 조건부·웹에 한정​

  • 현재: 실행 이미지의 확인된 버전은 10.11.8. 현재 설정 경로에서 SSO 플러그인은 확인되지 않았고 8096이 게시돼 있다.
  • 변경: 설치 버전에 맞는 유지 관리 중인 SSO 플러그인과 IdP를 검토한다. 기존 사용자 매칭·관리자 계정·라이브러리 권한을 확인한다. 웹 프록시에 일괄 Hub 리다이렉트를 걸면 TV·모바일 클라이언트가 실패할 수 있으므로 클라이언트별 경로를 검토한다.
  • 검증: 웹 로그인, TV·모바일 로그인, 라이브러리·시청 기록, 관리자 복구. 기존 9p4 플러그인은 웹 UI 중심이며 로그아웃 연동에도 한계가 있어 현재 유지 상태를 재확인한다.

5.13. Redmine — 순위 13, 우선순위 낮음​

  • 현재: /home/sleepzz/docker-compose/redmine/docker-compose.yaml의 redmine:5.1.9, 8085 게시. 현재 Compose에 Hub/OIDC 연동이 없다.
  • 변경: 설치 버전과 호환되는 외부 인증 플러그인 또는 LDAP 연동을 따로 평가한다. 사용자명과 기존 프로젝트·역할·이슈 이력을 매칭한다. 단순 Nginx 게이트 추가는 자체 로그인을 남겨 이중 로그인이 된다.
  • 검증: 관리자·프로젝트 권한, 기존 이슈 작성자 연결, API 키와 Git/SCM 연동, 플러그인 업데이트·복구.

5.14. YDM — 순위 14, 현재 방식에선 비권장​

  • 현재: /home/sleepzz/docker-compose/youtubedl-material/docker-compose.yaml의 17442 게시. 런타임 default.json에서 multi_user_mode=true, auth_method=internal이다.
  • 변경 가능성: 다중 사용자 모드를 끄고 Nginx Hub 게이트만 사용하면 브라우저 로그인 하나로 만들 수 있지만 사용자별 파일·역할·권한 기능을 잃는다. 다중 사용자를 유지하면 Hub 인증만 추가할 때 이중 로그인이다. 공식 설정의 LDAP 경로를 쓰려면 별도 디렉터리·계정 동기화 설계가 필요하다.
  • 권장: 현 기능이 필요한 동안 기존 로그인 유지. 단순 인증 프록시 추가는 편의 개선 목표에 맞지 않는다.

5.15. WebDAV — 순위 15, 비권장​

  • 현재: /home/sleepzz/docker-compose/webdav/docker-compose.yaml에서 201 게시, 사용자명·비밀번호 기반 인증. 여러 호스트 저장 경로를 마운트한다.
  • 판단: 파일 탐색기·동기화 앱 등 DAV 클라이언트는 일반적으로 Hub 웹 로그인 리다이렉트를 처리하지 않는다. 기존 DAV 인증을 Hub 쿠키로 대체하지 않는다.
  • 권장 변경: 기존 인증 유지, TLS·접근망·직접 포트 공개 범위와 마운트 권한 점검. 별도 웹 관리 화면이 생길 때만 Hub 진입 보호를 논의한다.

6. 단계별 실행 제안​

단계 0 — 공통 설계·우회 경로 확인​

  • 서비스별 실제 Cloudflared → Nginx → 앱 경로, LAN 직접 접근, Docker 네트워크 접근, API·RPC 클라이언트를 조사한다.
  • Hub의 외부 서비스 접근권·검증 응답·로그인 복귀 URL 정책을 확정한다. 쿠키 도메인과 서비스 로그의 JWT 노출 범위를 점검한다.
  • 기존 Nginx 스니펫을 대체할 설정을 준비하고, 모든 사용자 헤더를 프록시에서 덮어쓰도록 설계한다.
  • 변경 전에 서비스별 관리자 복구 경로와 Compose·앱 데이터 백업을 확인한다.

단계 1 — 시험 및 헤더 기반 웹 로그인 대체​

  1. Glances로 Hub 게이트·리다이렉트·직접 포트 차단을 시험한다.
  2. Linkding → Moonlight → Guacamole → CloudBeaver 순으로 사용자 헤더와 기존 계정 매칭을 적용한다.
  3. File Browser는 우회 경로 차단을 입증한 후 인증 방식을 전환한다.
  4. 각 서비스마다 비로그인·정상 로그인·권한 없음·로그아웃·Hub 장애·직접 포트 접속을 검증하고 다음 서비스로 넘어간다.

단계 2 — 웹 UI와 기계 클라이언트의 경계​

  1. Transmission RPC 클라이언트와 Apprise API 소비자를 목록화한다.
  2. 웹 UI는 Hub 한 번으로, RPC·API는 별도 자격으로 접근하게 설계한다. 경로 예외가 브라우저 내부 API까지 열지 않는지 확인한다.
  3. 검증된 경우에만 Transmission 기존 웹 인증 해제를 결정한다.

단계 3 — OIDC/OAuth​

  1. 표준 IdP 운영 방식과 Hub 사용자 원본·권한 동기화 방식을 확정한다.
  2. Komga → Portainer 순으로 적용하고 관리자 권한 매핑과 비상 계정을 검증한다.
  3. LiteLLM은 설치 이미지 업그레이드·기능·사용 조건을 확인한 뒤, Jellyfin은 플러그인 및 클라이언트 호환을 확인한 뒤 결정한다.

단계 4 — 보류 대상​

Redmine은 인증 플러그인·권한 이관 비용이 정당화될 때 재평가한다. YDM은 다중 사용자 기능을 유지하는 동안 기존 로그인을 사용한다. WebDAV는 DAV 클라이언트 자격 증명을 유지한다.

7. 완료 판정과 롤백 기준​

  • 한 번 로그인: 새 브라우저에서 서비스 URL로 접근 → Hub 로그인 → 대상 서비스 화면에 추가 비밀번호 입력 없이 진입.
  • 권한: 서비스별 허용 사용자만 진입하고, 관리 권한이 일반 사용자에게 자동 부여되지 않는다.
  • 우회 방지: 호스트 공개 포트·다른 컨테이너·Tunnel 직접 route에서 인증 없이 접근할 수 없다. 임의 사용자 헤더도 무시된다.
  • 기능: 서비스별 API·RPC·WebSocket·스트리밍·모바일 클라이언트가 정해진 인증 방식으로 동작한다.
  • 세션: Hub 로그아웃·권한 회수·만료 후 새 요청이 차단된다. 대상 서비스에 이미 만들어진 세션의 잔존 동작을 기록한다.
  • 장애: Hub 또는 프록시가 응답하지 않을 때 서비스가 인증을 우회해 열리지 않는다. 관리자 비상 접근과 이전 Compose·설정으로 되돌리는 절차가 있다.

8. 참고 자료​

JunkBox 및 현지 설정​

  • /home/sleepzz/dev/workspaces/vault/docs/junkbox/apps/guide-apps-hub-api.md
  • /home/sleepzz/dev/workspaces/vault/docs/junkbox/common/guide-jb-core.md
  • /home/sleepzz/dev/workspaces/junkbox/apps/hub-api/src/junkbox_hub_api/api/v1/auth.py
  • /home/sleepzz/dev/workspaces/junkbox/apps/hub-api/src/junkbox_hub_api/web/router.py
  • /data001/nginx/snippets/nexus_auth.conf, /data001/nginx/conf.d/guacamole.conf
  • 각 서비스의 /home/sleepzz/docker-compose/<서비스>/docker-compose.yaml

제품 공식 문서·프로젝트 원본 (2026-10-26 조회)​


후속 세션 메모: 이 문서는 설계·우선순위 검토 보고서다. 아직 Hub 소스, Vault의 docs/junkbox, Nginx, Cloudflared, Docker Compose, 서비스 내부 설정, DB를 변경하지 않았다. 단계별 구현 요청에서는 먼저 실제 Tunnel 라우팅과 직접 접근 경로를 확인하고, 서비스별 변경·검증·복구 범위를 작게 나눠 진행한다. 이 문서는 docs/junkbox 개발 가이드가 아니므로 개발 문서 벡터 캐시 동기화 대상에 자동 포함된다고 가정하지 않는다.