시놀로지 NAS Dashlit 대시보드 구축: NPM 프록시 완벽 설정

💡 정보: 본 가이드는 기술적 절차를 다루며, 사용자의 환경에 따라 설정값이 달라질 수 있습니다. 진행 전 중요 데이터는 반드시 백업하시기 바랍니다. 본 글은 정보 제공 목적이며, 설정 오류로 인한 문제 발생 시 책임지지 않습니다.

여러 개의 Docker 서비스를 운영하다 보면 각 서비스의 포트 번호를 외우기 어렵고, 브라우저 북마크는 지저분해지기 마련입니다. Dashlit은 SvelteKit 기반의 초경량 대시보드 도구로, 파편화된 서비스들을 하나의 깔끔한 랜딩 페이지로 통합하여 관리의 피로감을 덜어줍니다.

이번 가이드에서는 시놀로지 NAS 환경에서 Portainer Stack을 이용해 Dashlit을 설치하고, Nginx Proxy Manager(NPM)를 통해 안전한 외부 접속 환경을 구축하는 모든 과정을 상세히 다룹니다.

1. 시작 전 사전 준비물

본 가이드를 원활하게 따라오려면 아래 환경이 미리 준비되어 있어야 합니다.

• 시놀로지 NAS: Docker(Container Manager) 패키지가 설치된 환경
• Portainer: 설치되어 실행 중인 상태
• Nginx Proxy Manager (NPM): 설치되어 실행 중인 상태
• 개인 도메인: 외부 접속을 위해 사용할 개인 도메인 및 DDNS 설정

---

2. Dashlit이란? 주요 특징 요약

Dashlit은 ghcr.io/codewec/dashlit:latest 이미지를 사용하는 매우 가볍고 반응성이 뛰어난 북마크 및 대시보드 도구입니다. 주요 특징은 다음과 같습니다.

• 초고속 로딩: SvelteKit 기반으로 제작되어 매우 빠른 속도를 자랑합니다.
• 미니멀리즘 디자인: 복잡한 기능 없이 자주 사용하는 웹 서비스를 모아보는 '랜딩 페이지' 역할에 충실합니다.
• 간결한 설정: 복잡한 설정 파일 없이 환경 변수만으로 대부분의 설정이 가능합니다.

---

3. 문제 상황: 파편화된 서비스 관리의 어려움

시놀로지 NAS에 Docker 컨테이너가 늘어날수록 다음과 같은 불편함이 생깁니다.

• 각 서비스의 포트 번호를 일일이 기억하기 힘듦 (:4530, :8834, :6384 등)
• 브라우저 북마크가 너무 많아져 관리가 어려움
• 외부에서 접속할 때 통합된 진입점(Entry point)이 없어 번거로움

Dashlit은 이러한 문제들을 해결해 주는 가장 효과적이고 세련된 솔루션 중 하나입니다.

[!CAUTION]
보안 경고: 대시보드는 여러분의 모든 서비스 주소가 노출되는 관문입니다. 비밀번호를 매우 강력하게 설정하고, 가능하면 2단계 인증 등 추가 보안 설정을 적용하십시오.

---

4. 해결 과정: Portainer Stack으로 Dashlit 배포하기

Portainer의 [Stacks] > [Add stack] 메뉴에서 아래 docker-compose.yml 코드를 복사하여 배포합니다. NPM과의 호환성을 고려한 필수 환경 변수들이 포함되어 있습니다.

version: '3.8'

services:
  app:
    container_name: dashlit
    image: ghcr.io/codewec/dashlit:latest
    restart: unless-stopped
    ports:
      # NAS의 4530 포트를 컨테이너의 3000번 포트에 연결합니다.
      # 외부에서 NAS_IP:4530 으로 접속 가능하게 됩니다.
      - '4530:3000'
    environment:
      # --- [매우 중요] 실제 접속할 도메인 주소 (HTTPS 포함) ---
      # 예: https://dash.yourdomain.com
      - ORIGIN=https://           
      
      # --- 인증 설정 ---
      - PASSWORD=your_strong_password    # 대시보드 접속 시 사용할 강력한 비밀번호
      - SECRET_KEY=your_long_random_string # 세션 암호화에 사용될 임의의 긴 문자열
      
      # --- NPM 역방향 프록시 호환성 설정 ---
      # NPM이 전달하는 헤더 정보를 애플리케이션이 신뢰하도록 구성합니다.
      - NODE_ENV=production
      - PROTOCOL_HEADER=X-Forwarded-Proto
      - HOST_HEADER=Host
      
    volumes:
      # 데이터 영구 저장을 위한 볼륨 마운트
      # 왼쪽 경로는 실제 시놀로지 NAS의 폴더 경로로 수정하세요.
      # 예: /volume1/docker/dashlit/data:/app/data
      - /path/to/your/dashlit/data:/app/data

⚙️ 설정 핵심 포인트

• ORIGIN: 외부에서 접속할 실제 도메인 주소(예: https://dash.mydomain.com)를 정확히 입력해야 합니다. 이 값이 틀리면 무한 로그인 루프에 빠질 수 있습니다. (끝에 /는 생략)
• SECRET_KEY: 추측이 불가능한 긴 무작위 문자열을 사용해야 합니다. 터미널에서 openssl rand -base64 32 명령어를 실행하거나, 신뢰할 수 있는 온라인 비밀번호 생성기를 통해 생성하는 것을 권장합니다.
• PROTOCOL_HEADER: NPM을 거칠 때 HTTPS 프로토콜 정보를 올바르게 인식하게 하여 인증 오류를 방지하는 핵심 설정입니다.
• volumes: 컨테이너를 삭제하거나 업데이트해도 대시보드 설정이 유지되도록 데이터를 영구 저장하는 경로입니다. 왼쪽 경로(/path/to/your/dashlit/data)는 반드시 실제 NAS 경로로 수정하고, 해당 폴더를 미리 생성해두세요.

---

5. 심화: Nginx Proxy Manager(NPM) 완벽 설정 가이드

Dashlit 컨테이너 배포 후, 도메인으로 안전하게 접속하기 위해 NPM에서 프록시 호스트를 설정합니다.

Details 탭 설정

항목	설정 값	비고
Forward Hostname / IP	[시놀로지_내부_IP]	예: 192.168.0.10 또는 Docker 네트워크 내 컨테이너 이름 dashlit
Forward Port	4530	위 docker-compose.yml에서 설정한 NAS의 외부 포트
Cache Assets	On	대시보드 아이콘, 배경 등 정적 리소스 로딩 속도 향상
Block Common Exploits	On	기본적인 웹 보안 필터링 적용 권장
Websockets Support	On	대시보드 실시간 상태 업데이트 기능을 위해 활성화 권장

SSL 탭 설정

• SSL Certificate: Request a new SSL Certificate (Let's Encrypt) 선택
• Force SSL: On (HTTPS 접속 강제)
• HTTP/2 Support: On (SvelteKit의 빠른 로딩 성능 극대화)
• HSTS Enabled: On (브라우저 보안 강화)

Advanced 탭 (Custom Nginx Configuration)

대시보드 배경화면 업로드나 아이콘 수정을 위해 아래 코드를 Advanced 탭에 추가하는 것이 좋습니다.

# 대시보드 배경화면 및 아이콘 업로드를 위한 용량 제한 (필요 시 조절)
client_max_body_size 50M;

# 실제 방문자 IP 및 프로토콜 전달 (보안 및 로깅에 중요)
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# 긴 작업 시 타임아웃 방지
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

---

6. 초기 설정 및 문제 해결 팁

1. Docker 네트워크 확인: Dashlit 컨테이너를 생성할 때 NPM과 같은 Docker 네트워크(예: proxy-net)에 포함시키면, Forward Hostname에 컨테이너 이름(dashlit)을 바로 사용할 수 있어 편리합니다.
2. 초기 계정 생성: NPM 설정 완료 후 설정한 도메인(HTTPS)으로 처음 접속하여 PASSWORD 환경 변수에 설정한 비밀번호로 로그인하고 초기 세팅을 진행하세요.
3. 아이콘 로딩 문제: 만약 대시보드 내 아이콘이 깨져 보인다면, NPM의 Cache Assets 옵션을 잠시 껐다가 다시 켜보거나 브라우저 캐시(Ctrl+Shift+R)를 삭제해 보세요.
4. 주기적인 업데이트: ghcr.io 이미지는 지속적으로 업데이트됩니다. Portainer에서 Stack을 선택하고 'Re-pull image and redeploy' 버튼을 눌러 최신 기능 및 보안 패치를 적용하세요.

---

7. 자주 묻는 질문 (FAQ)

Q1: ORIGIN 환경 변수를 정확히 입력해야 하는 이유는 무엇인가요?
A1: ORIGIN은 웹 애플리케이션의 보안 정책(CORS 등)과 세션 인증에 직접적인 영향을 미칩니다. 브라우저가 접속한 주소와 ORIGIN 값이 다를 경우, 서버는 이를 신뢰할 수 없는 요청으로 판단하여 로그인을 거부하거나 무한 로그인 루프를 발생시킬 수 있습니다.

Q2: 대시보드 아이콘이 깨져서 보입니다. 어떻게 해결하나요?
A2: 가장 일반적인 원인은 캐시 문제입니다. 먼저 브라우저의 강력 새로고침(Ctrl+Shift+R)을 시도해 보세요. 그래도 해결되지 않으면 NPM 설정에서 'Cache Assets' 옵션을 비활성화했다가 다시 활성화하여 캐시를 갱신해 보는 것이 좋습니다.

Q3: NPM과 Dashlit이 서로 다른 Docker 네트워크에 있습니다. 연결할 수 없나요?
A3: 연결 가능합니다. 이 경우 Forward Hostname / IP 필드에 컨테이너 이름 대신 시놀로지 NAS의 내부 IP 주소(예: 192.168.0.10)를 직접 입력하고, Forward Port에 ports 설정에서 지정한 외부 포트(예: 4530)를 입력하면 됩니다.

---

결론

Dashlit은 시놀로지 NAS에서 여러 Docker 서비스를 운영하는 사용자에게 훌륭한 통합 관리 경험을 제공합니다. 위 가이드의 Portainer Stack 코드와 NPM 설정을 통해 복잡한 네트워크 문제없이 안정적이고 빠른 대시보드 환경을 구축해 보시기 바랍니다.