JunkBox Hub와 홈서버 Docker 서비스 로그인 통합 검토
작성일: 2026-10-26 (KST)
상태: 읽기 전용 조사 결과. 구현·설정 변경 전 검토용.
대상: 다음 세션에서 Hub 인증 개선, Nginx 게이트웨이 구성, 서비스별 단계적 전환을 요청할 때 사용할 기준 문서.
1. 핵심 결론
- 브라우저에서 Hub 로그인 한 번으로 끝나는 서비스가 여러 개 있다. 프록시 사용자 헤더를 공식 지원하는 Linkding, Moonlight Web Stream, Guacamole, CloudBeaver CE, File Browser가 대표적이다. Glances처럼 현재 자체 로그인이 없는 화면은 Hub를 유일한 진입 인증으로 둘 수 있다.
- Transmission도 웹 UI는 Hub 인증으로 기존 로그인을 대체할 수 있다. 다만 웹 UI와 RPC 클라이언트가 같은 9091 포트를 사용하므로 비브라우저 클라이언트의 인증 경로를 별도로 설계해야 한다. 기존
USER/PASS를 유지하며 Hub 게이트를 더하면 로그인만 두 번 하게 된다. - 포털의 SERVICE 등록과 실제 Docker 실행 목록은 다르다. 이 문서는 2026-10-26에 실행 중인 외부 앱 15개를 기준으로 한다. 포털에 있지만 현재 컨테이너로 실행되지 않는 Vault, Home Assistant, Jenkins, ipTIME은 아래 우선순위에서 제외한다. 반대로 실행 중인 Apprise API와 WebDAV는 포함한다.
- 공통 선행 조건은 우회 경로 차단이다. 조사 대상 앱의 호스트 포트는 현재 모두
0.0.0.0에 게시되어 있다. Nginx가 인증하더라도 직접 포트로 접근할 수 있으면 통합 인증이 성립하지 않는다. 사용자 헤더를 신뢰하는 앱은 헤더 위조까지 가능해진다. - 현재 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_AUTHJWT 쿠키와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 | 조건부 권장·웹 UI | Transmission | 가능 | 기존 RPC 인증을 끌 수 있지만 RPC 클라이언트 경로 분리 필요 |
| 8 | 조건부 권장·웹 UI | Apprise 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 인증 계약
- 외부 서비스를
서비스 ID → 공개 origin/복귀 URL → 허용 사용자 또는 그룹 → 전달 가능한 사용자 필드로 등록한다. 포털의SERVICE메뉴는 링크 목록이므로 인증 권한 정의와 혼동하지 않는다. 기존HUB관리자 권한을 모든 서비스 접근권으로 재사용하지 않는 편이 좋다. - 프록시 서브요청 전용 검증 경로를 정의한다. 쿠키에서 JWT를 읽고 Hub의 영속 세션·서비스별 접근권을 검사한 뒤 2xx/401/403을 일관되게 반환한다. 사용자 식별자 헤더는 성공 시에만 반환한다. 기존
/api/auth/verify재사용 여부는 이 계약과 서비스별 권한 검증을 검토한 뒤 결정한다. - 로그인 복귀 주소는 요청의 Host를 맹신하지 않고 등록된 서비스 URL에 매칭한다. 로그아웃, Hub 세션 만료, 권한 회수와 각 서비스 자체 세션의 잔존 기간을 정의한다. Nginx가 매 요청을 검증하더라도 직접 포트가 열려 있으면 우회할 수 있다.
JUNKBOX_AUTH쿠키를 모든 외부 하위 도메인에 보내는 현재 방식의 노출 범위를 검토한다. 최소한 상위 프록시와 제품 로그에서 쿠키·JWT를 기록하지 않게 하고, 장기 목표로 Hub 전용 쿠키/게이트웨이 세션 또는 OIDC 분리를 설계한다.- OIDC/OAuth는 별도 결정이다. 검증된 IdP를 운영하고 Hub를 그 IdP의 클라이언트로 연동할지, Hub에 표준 제공자 기능을 구현할지 먼저 정한다. 후자를 택하면 클라이언트 등록, 인가 코드·PKCE, 토큰·JWKS·키 회전, discovery/userinfo, 사용자 claim, 로그아웃, 감사 기록을 포함해 설계해야 한다.
4.2. Nginx·Cloudflared·Docker 네트워크
- 서비스별 공개 주소가
Cloudflare Tunnel → Nginx → 앱을 거치는지 확인한다. Nginx를 건너뛰는 Tunnel route나 LAN 직접 포트가 있으면 인증 게이트를 적용해도 우회된다. - 예전
nexus_auth.conf를 현재 Hub 주소·경로·정책에 맞는 공통auth_request설정으로 교체한다. 401은 Hub 로그인으로 복귀시키고 403은 권한 없음으로 처리한다. 로그인 URL의redirect는 등록된 URL로 만든다.auth_request_set으로 검증 응답의 사용자 ID를 받아 프록시가 인증 헤더를 덮어쓴다. 클라이언트가 보낸 동명 헤더는 신뢰하지 않는다. - 헤더 인증 서비스와 보호 웹 UI의 호스트
ports게시를 없애거나, 구성에 맞게 루프백에 묶거나, 방화벽·네트워크 ACL로 Nginx만 접근하게 한다. Dockerserverzz-net에 붙은 다른 컨테이너에서도 우회 가능한지 확인한다. 필요하면 인증 프록시와 앱 전용 네트워크를 사용한다. - 브라우저 UI와 비브라우저 API/RPC/WebDAV를 경로와 인증 정책에 따라 나눈다. 단순히
/api/*를 전부 예외 처리하면 브라우저 UI의 API도 우회할 수 있다. 서비스별 실제 요청과 클라이언트를 먼저 조사한다. - 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 — 시험 및 헤더 기반 웹 로그인 대체
- Glances로 Hub 게이트·리다이렉트·직접 포트 차단을 시험한다.
- Linkding → Moonlight → Guacamole → CloudBeaver 순으로 사용자 헤더와 기존 계정 매칭을 적용한다.
- File Browser는 우회 경로 차단을 입증한 후 인증 방식을 전환한다.
- 각 서비스마다 비로그인·정상 로그인·권한 없음·로그아웃·Hub 장애·직접 포트 접속을 검증하고 다음 서비스로 넘어간다.
단계 2 — 웹 UI와 기계 클라이언트의 경계
- Transmission RPC 클라이언트와 Apprise API 소비자를 목록화한다.
- 웹 UI는 Hub 한 번으로, RPC·API는 별도 자격으로 접근하게 설계한다. 경로 예외가 브라우저 내부 API까지 열지 않는지 확인한다.
- 검증된 경우에만 Transmission 기존 웹 인증 해제를 결정한다.
단계 3 — OIDC/OAuth
- 표준 IdP 운영 방식과 Hub 사용자 원본·권한 동기화 방식을 확정한다.
- Komga → Portainer 순으로 적용하고 관리자 권한 매핑과 비상 계정을 검증한다.
- 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 조회)
- Nginx
auth_request - Glances 웹/API 인증
- Linkding 인증 프록시와 OIDC
- Moonlight Web Stream 프록시 인증
- Guacamole HTTP 헤더 인증
- CloudBeaver CE 프록시 헤더 인증
- File Browser 인증 방식
- Transmission 컨테이너 설정
- Apprise API 인증
- Komga 소셜 로그인/OIDC
- Portainer OAuth
- LiteLLM SSO 제공 범위
- Jellyfin 플러그인, SSO 플러그인 원본
- Redmine 사용자 인증
- YDM 구성
- uGeek WebDAV 이미지
후속 세션 메모: 이 문서는 설계·우선순위 검토 보고서다. 아직 Hub 소스, Vault의 docs/junkbox, Nginx, Cloudflared, Docker Compose, 서비스 내부 설정, DB를 변경하지 않았다. 단계별 구현 요청에서는 먼저 실제 Tunnel 라우팅과 직접 접근 경로를 확인하고, 서비스별 변경·검증·복구 범위를 작게 나눠 진행한다. 이 문서는 docs/junkbox 개발 가이드가 아니므로 개발 문서 벡터 캐시 동기화 대상에 자동 포함된다고 가정하지 않는다.