n8n 웹환경 모니터링 시스템 구축

n8n Queue Mode 환경에 Weave Scope 모니터링 시스템 구축하기

Docker 기반의 n8n Queue Mode 환경을 운영하다 보면, 여러 컨테이너가 복잡하게 얽혀 있어서 전체 시스템의 상태를 파악하기 어려울 때가 있습니다. 이번 글에서는 Weave Scope를 활용하여 Docker 컨테이너 환경을 실시간으로 시각화하고 모니터링하는 방법을 상세히 알아보겠습니다. Weave Scope는 별도의 복잡한 설정 없이도 컨테이너 간의 관계를 직관적인 그래프로 표현해주어, 개발자와 운영자 모두에게 유용한 도구입니다.

---

1. Weave Scope란 무엇인가요?

Weave Scope는 Weaveworks에서 개발한 오픈소스 컨테이너 모니터링 및 시각화 도구입니다.

Docker와 Kubernetes 환경에서 실행 중인 컨테이너, 프로세스, 호스트의 상태를 실시간으로 파악할 수 있도록 도와줍니다. 특히 마이크로서비스 아키텍처에서 여러 서비스 간의 연결 관계를 한눈에 파악할 수 있어, 문제 발생 시 원인 분석에 큰 도움이 됩니다. 설치와 설정이 매우 간단하여 "제로 컨피그(Zero-Config)" 도구로 불리며, Docker Socket에 연결하는 것만으로 자동으로 모든 컨테이너를 탐지하고 시각화합니다.

 

Weave Scope가 제공하는 핵심 기능들을 살펴보면, 먼저 실시간 토폴로지 맵을 통해 컨테이너 간의 네트워크 연결을 직관적인 그래프로 표현합니다. 또한 각 컨테이너의 CPU와 메모리 사용량을 실시간으로 모니터링하여 리소스 병목 현상을 빠르게 파악할 수 있습니다. 웹 UI를 통해 컨테이너를 직접 시작, 중지, 재시작할 수 있으며, 컨테이너 내부에 쉘로 접속하는 것도 가능합니다. 이러한 기능들은 복잡한 마이크로서비스 환경에서 운영 효율성을 크게 높여줍니다.

weavescope 컨테이너를 활용한 Docker기반 n8n 고가용성 서비스에 대한 웹모니터링 초기 화면

---

2. 프로젝트 구조 이해하기

이번 글에서는 기존의 n8n Queue Mode 프로젝트에 monitoring-stack을 추가하는 방식으로 진행합니다. 전체 프로젝트 구조는 아래와 같이 구성되어 있으며, 각 스택이 독립적으로 관리되면서도 공유 네트워크를 통해 서로 연결됩니다. 이러한 멀티 스택 아키텍처는 각 서비스의 독립적인 배포와 확장을 가능하게 하며, 유지보수 측면에서도 큰 장점을 제공합니다.

n8n-queue-project/
├── database-stack/           # PostgreSQL, Redis (공유 서비스)
│   ├── docker-compose.yml
│   └── .env
│
├── n8n-queue-stack/          # n8n Main, Worker, Webhook, Nginx
│   ├── docker-compose.yml
│   ├── .env
│   └── nginx/
│
├── monitoring-stack/         # Weave Scope (NEW!)
│   ├── docker-compose.yml
│   └── .env
│
└── scripts/
    ├── start-all.sh
    ├── stop-all.sh
    ├── status.sh
    └── monitoring.sh         # 모니터링 전용 스크립트 (NEW!)

 

이 프로젝트에서 각 스택은 독립적인 Docker Compose 프로젝트로 관리됩니다. database-stack은 PostgreSQL과 Redis를 제공하여 n8n의 데이터 저장소 역할을 담당하고, n8n-queue-stack은 실제 워크플로우 자동화 서비스를 실행합니다. 새로 추가되는 monitoring-stack은 이 모든 컨테이너들의 상태를 모니터링하고 시각화합니다. 모든 스택은 n8n-shared라는 공유 네트워크를 통해 서로 통신하며, 이를 통해 Weave Scope가 다른 스택의 컨테이너까지 모니터링할 수 있게 됩니다.

---

3. Weave Scope Docker Compose 구성

이제 monitoring-stack의 핵심인 docker-compose.yml 파일을 살펴보겠습니다. 이 설정 파일은 macOS Docker Desktop 환경에 최적화되어 있으며, Linux 서버 환경에서 사용할 때 필요한 설정 변경 사항도 함께 안내해 드리겠습니다. 각 설정 항목에 대한 상세한 설명을 통해 Weave Scope의 동작 방식을 이해하실 수 있습니다.

# =============================================================================
# Monitoring Stack - Weave Scope 컨테이너 모니터링 시스템
# =============================================================================
# 이 스택은 Docker 컨테이너 환경을 실시간으로 시각화하고 모니터링합니다.
# Weave Scope는 컨테이너 간의 연결 관계, 리소스 사용량, 프로세스 정보를
# 직관적인 웹 대시보드로 제공하여 인프라 관리를 용이하게 합니다.
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # Weave Scope - 컨테이너 모니터링 및 시각화 도구
  # ---------------------------------------------------------------------------
  weave-scope:
    image: weaveworks/scope:${SCOPE_VERSION:-1.13.2}
    container_name: weave-scope
    hostname: weave-scope
    restart: unless-stopped
    
    # macOS/Windows Docker Desktop 환경용 포트 매핑
    ports:
      - "${SCOPE_PORT:-4040}:4040"
    
    # 호스트의 프로세스 정보에 접근하기 위한 PID 네임스페이스 공유
    pid: "host"
    
    # 시스템 정보 수집을 위한 특권 모드
    privileged: true
    
    # Weave 생태계 레이블
    labels:
      - "works.weave.role=system"
      - "com.docker.compose.project=monitoring-stack"
    
    # Docker Socket 마운트 - 컨테이너 정보 수집에 필수
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:rw"
    
    # 프로브 설정
    command:
      - "--probe.docker=true"
      - "--weave=false"
    
    # 네트워크 연결
    networks:
      - n8n-shared-network
      - monitoring-internal
    
    # 서비스 상태 확인
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:4040/api"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    
    # 로그 관리
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    
    # 환경 변수
    environment:
      - CHECKPOINT_DISABLE=true
      - TZ=${TZ:-Asia/Seoul}

# =============================================================================
# 네트워크 정의
# =============================================================================
networks:
  # database-stack에서 생성된 공유 네트워크
  n8n-shared-network:
    external: true
    name: n8n-shared-network
  
  # 모니터링 스택 내부 통신용 네트워크
  monitoring-internal:
    driver: bridge
    name: monitoring-internal

---

4. 주요 설정 상세 설명

위의 docker-compose.yml 파일에서 각 설정 항목이 어떤 역할을 하는지 자세히 살펴보겠습니다. Docker Compose에 익숙하지 않은 분들도 각 설정의 의미를 이해하실 수 있도록 설명해 드리겠습니다.

이미지 버전 설정

Weave Scope의 이미지 버전은 환경 변수를 통해 유연하게 관리할 수 있습니다. 기본값으로 1.13.2를 사용하고 있으며, 이는 2021년에 릴리스된 마지막 안정 버전입니다. Weaveworks가 2023년에 사업을 종료했지만, 오픈소스로 공개된 Weave Scope는 여전히 Docker 모니터링 용도로 충분히 활용할 수 있습니다. 최신 기능이 필요한 경우 latest 태그를 사용할 수 있지만, 프로덕션 환경에서는 명시적인 버전 지정을 권장합니다.

PID 네임스페이스와 특권 모드

pid: "host" 설정은 Weave Scope 컨테이너가 호스트의 프로세스 정보에 접근할 수 있도록 합니다. 이를 통해 각 컨테이너 내부에서 실행 중인 프로세스 목록을 조회하고 모니터링할 수 있습니다. privileged: true 설정은 컨테이너에 확장된 권한을 부여하여 eBPF 추적, 네트워크 연결 정보 수집 등 시스템 수준의 정보를 수집할 수 있게 합니다. 이러한 설정들은 보안 측면에서 주의가 필요하므로, 신뢰할 수 있는 환경에서만 사용해야 합니다.

Docker Socket 마운트

/var/run/docker.sock:/var/run/docker.sock:rw 볼륨 마운트는 Weave Scope가 Docker 데몬과 통신할 수 있게 합니다. Docker Socket을 통해 실행 중인 모든 컨테이너 정보를 조회하고, 컨테이너를 제어(시작, 중지, 재시작)할 수 있습니다. 이 마운트가 없으면 Weave Scope는 Docker 컨테이너를 인식하지 못하므로 반드시 필요한 설정입니다. 보안을 위해 필요한 경우 읽기 전용(:ro)으로 마운트할 수 있지만, 이 경우 컨테이너 제어 기능은 사용할 수 없습니다.

네트워크 구성

monitoring-stack은 두 개의 네트워크에 연결됩니다. n8n-shared-network는 database-stack에서 생성된 외부 네트워크로, 이 네트워크에 연결된 모든 컨테이너를 모니터링할 수 있게 합니다. monitoring-internal은 monitoring-stack 내부 통신을 위한 브릿지 네트워크로, 향후 Prometheus나 Grafana 같은 추가 모니터링 도구를 연결할 때 사용됩니다. 이러한 네트워크 구성을 통해 Weave Scope는 전체 인프라의 컨테이너 토폴로지를 파악할 수 있습니다.

---

5. 환경 변수 설정

monitoring-stack의 환경 변수는 .env 파일에서 관리합니다. 이 파일을 통해 Weave Scope의 버전, 포트 등을 손쉽게 변경할 수 있으며, 버전 관리 시스템에서 제외하여 환경별로 다른 설정을 적용할 수 있습니다.

# =============================================================================
# Monitoring Stack 환경 변수 설정
# =============================================================================

# Weave Scope 이미지 버전
# - 최신 안정 버전: 1.13.2
# - 최신 개발 버전: latest
SCOPE_VERSION=1.13.2

# Weave Scope 웹 UI 포트
# - 기본값: 4040
# - 포트 충돌 시 다른 포트로 변경 가능
SCOPE_PORT=4040

# 타임존 설정
TZ=Asia/Seoul

 

환경 변수를 활용하면 동일한 docker-compose.yml 파일로 여러 환경(개발, 스테이징, 프로덕션)에서 다른 설정을 적용할 수 있습니다. 예를 들어 개발 환경에서는 latest 태그를 사용하여 최신 기능을 테스트하고, 프로덕션 환경에서는 검증된 특정 버전을 사용하는 방식으로 운영할 수 있습니다.

---

6. 설치 및 실행 방법

Weave Scope를 설치하고 실행하는 방법은 매우 간단합니다. 아래의 단계별 가이드를 따라 진행하시면 몇 분 안에 모니터링 시스템을 구축하실 수 있습니다.

사전 준비 사항

먼저 기존 n8n Queue Mode 프로젝트가 실행 중이어야 합니다. database-stack이 실행되면서 n8n-shared-network 네트워크가 생성되어 있어야 Weave Scope가 해당 네트워크에 연결하여 다른 컨테이너들을 모니터링할 수 있습니다. 아직 n8n Queue Mode 환경을 구축하지 않으셨다면, 이전 글을 참고하여 먼저 환경을 설정해 주세요.

# n8n-shared-network 네트워크 존재 여부 확인
docker network ls | grep n8n-shared-network

# 네트워크가 없다면 database-stack 먼저 시작
cd n8n-queue-project/database-stack
docker compose up -d

monitoring-stack 디렉토리 생성 및 파일 배치

프로젝트 루트에 monitoring-stack 디렉토리를 생성하고, 위에서 작성한 docker-compose.yml과 .env 파일을 해당 디렉토리에 저장합니다. 파일 구조가 올바르게 구성되었는지 확인하는 것이 중요합니다.

# monitoring-stack 디렉토리 생성
cd n8n-queue-project
mkdir -p monitoring-stack

# docker-compose.yml 파일 생성 (위의 내용 복사)
nano monitoring-stack/docker-compose.yml

# .env 파일 생성
nano monitoring-stack/.env

Weave Scope 실행

이제 Weave Scope를 실행할 준비가 완료되었습니다. Docker Compose 명령어로 서비스를 시작하면 자동으로 이미지를 다운로드하고 컨테이너를 생성합니다.

# monitoring-stack 디렉토리로 이동
cd monitoring-stack

# 서비스 시작 (백그라운드 실행)
docker compose up -d

# 컨테이너 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f

 

서비스가 정상적으로 시작되면 웹 브라우저에서 http://localhost:4040으로 접속하여 Weave Scope 대시보드를 확인할 수 있습니다. 첫 접속 시 자동으로 현재 Docker 환경의 모든 컨테이너를 탐지하고 토폴로지 맵을 생성합니다.

---

7. 관리 스크립트 활용

효율적인 운영을 위해 monitoring-stack 전용 관리 스크립트를 제공합니다. 이 스크립트를 사용하면 복잡한 Docker Compose 명령어를 기억할 필요 없이 간단한 명령어로 서비스를 제어할 수 있습니다.

#!/bin/bash
# =============================================================================
# Monitoring Stack 관리 스크립트
# =============================================================================
# 사용법: ./monitoring.sh [start|stop|restart|status|logs]
# =============================================================================

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"

# 색상 정의
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

case "$1" in
    start)
        echo -e "${GREEN}Monitoring Stack 시작 중...${NC}"
        docker compose -f "$PROJECT_ROOT/monitoring-stack/docker-compose.yml" up -d
        echo -e "${GREEN}✓ Weave Scope: http://localhost:4040${NC}"
        ;;
    stop)
        echo -e "${YELLOW}Monitoring Stack 중지 중...${NC}"
        docker compose -f "$PROJECT_ROOT/monitoring-stack/docker-compose.yml" down
        ;;
    restart)
        $0 stop && sleep 2 && $0 start
        ;;
    status)
        docker compose -f "$PROJECT_ROOT/monitoring-stack/docker-compose.yml" ps
        ;;
    logs)
        docker compose -f "$PROJECT_ROOT/monitoring-stack/docker-compose.yml" logs -f --tail=100
        ;;
    *)
        echo "사용법: $0 {start|stop|restart|status|logs}"
        ;;
esac

 

스크립트를 사용하면 아래와 같이 간편하게 서비스를 관리할 수 있습니다. 각 명령어는 직관적인 이름을 사용하여 별도의 설명 없이도 쉽게 이해할 수 있습니다.

# 스크립트 실행 권한 부여
chmod +x scripts/monitoring.sh

# 서비스 시작
./scripts/monitoring.sh start

# 상태 확인
./scripts/monitoring.sh status

# 로그 확인
./scripts/monitoring.sh logs

# 서비스 재시작
./scripts/monitoring.sh restart

# 서비스 중지
./scripts/monitoring.sh stop

---

8. Weave Scope 웹 UI 활용법

Weave Scope의 웹 인터페이스는 직관적이고 사용하기 쉽게 설계되어 있습니다. 처음 접속하면 현재 Docker 환경의 전체 토폴로지가 그래프 형태로 표시됩니다. 각 노드는 컨테이너를 나타내며, 노드 간의 선은 네트워크 연결을 의미합니다.

토폴로지 뷰 탐색

화면 상단의 드롭다운 메뉴를 통해 다양한 뷰를 선택할 수 있습니다. "Containers" 뷰는 모든 Docker 컨테이너를 보여주고, "Processes" 뷰는 컨테이너 내부의 프로세스까지 표시합니다. "Hosts" 뷰는 호스트 머신 수준의 정보를 제공하며, Docker Desktop 환경에서는 가상화된 Linux VM이 표시됩니다. 각 뷰에서 노드를 클릭하면 해당 리소스의 상세 정보를 확인할 수 있습니다.

컨테이너 상세 정보 확인

특정 컨테이너를 클릭하면 오른쪽 패널에 상세 정보가 표시됩니다. 여기서 컨테이너의 이미지 정보, 네트워크 설정, 환경 변수, 마운트된 볼륨 등을 확인할 수 있습니다. 또한 실시간 CPU 및 메모리 사용량 그래프가 표시되어 리소스 사용 현황을 한눈에 파악할 수 있습니다. 프로세스 탭에서는 컨테이너 내부에서 실행 중인 모든 프로세스 목록을 볼 수 있습니다.

컨테이너 제어 기능

Weave Scope는 단순한 모니터링을 넘어 컨테이너를 직접 제어하는 기능도 제공합니다. 상세 정보 패널에서 컨테이너를 중지, 재시작, 일시 정지할 수 있으며, "Attach" 버튼을 통해 컨테이너의 표준 출력을 실시간으로 확인할 수 있습니다. 가장 유용한 기능 중 하나는 "<>" 버튼으로 제공되는 쉘 접속 기능으로, 웹 브라우저에서 바로 컨테이너 내부에 접속하여 명령어를 실행할 수 있습니다.

Weave Scope 대시보드 - Docker 컨테이너 간의 연결 관계와 리소스 사용량을 실시간으로 시각화하여 마이크로서비스 환경의 전체 토폴로지를 한눈에 파악할 수 있습니다. ❘ ChatGPT 가상이미지

---

9. macOS vs Linux 환경 차이점

Weave Scope를 실행할 때 운영체제에 따라 일부 설정을 조정해야 합니다. macOS와 Windows에서 Docker Desktop은 가상화된 Linux VM 위에서 실행되기 때문에, 네트워크 모드 설정에 차이가 있습니다.

macOS/Windows Docker Desktop 환경

Docker Desktop 환경에서는 network_mode: "host" 설정이 호스트 머신이 아닌 가상 Linux VM에 적용됩니다. 따라서 호스트에서 직접 포트에 접근하려면 포트 매핑을 사용해야 합니다. 본 가이드의 docker-compose.yml은 이러한 환경을 고려하여 포트 매핑 방식으로 구성되어 있습니다.

# macOS/Windows Docker Desktop 환경
ports:
  - "${SCOPE_PORT:-4040}:4040"

Linux 서버 환경

Linux 서버에서는 network_mode: "host" 설정을 활성화하여 더 정확한 네트워크 토폴로지 정보를 얻을 수 있습니다. 이 모드에서는 컨테이너가 호스트의 네트워크 스택을 직접 사용하므로 포트 매핑이 필요 없습니다.

# Linux 서버 환경 (docker-compose.yml 수정)
services:
  weave-scope:
    # ... 기타 설정 ...
    network_mode: "host"  # 주석 해제
    # ports:              # 주석 처리
    #   - "4040:4040"

 

Linux 환경에서 host 네트워크 모드를 사용하면 eBPF 기반의 더 정밀한 네트워크 추적이 가능해지며, 호스트와 컨테이너 간의 네트워크 연결도 더 정확하게 표시됩니다.

---

10. 보안 고려사항

Weave Scope는 강력한 모니터링 및 제어 기능을 제공하지만, 그만큼 보안에 주의가 필요합니다. 잘못된 설정으로 외부에 노출될 경우 심각한 보안 위협이 될 수 있습니다.

포트 4040 보호

Weave Scope의 웹 UI 포트(4040)는 절대로 인터넷에 직접 노출해서는 안 됩니다.

이 포트에 접근할 수 있는 사람은 모든 컨테이너를 조회하고 제어할 수 있기 때문입니다. 반드시 방화벽을 통해 내부 네트워크에서만 접근 가능하도록 제한하거나, VPN을 통해 접근하도록 설정해야 합니다. 클라우드 환경에서는 보안 그룹을 활용하여 특정 IP에서만 접근을 허용하는 것이 좋습니다.

인증 설정 추가

기본적으로 Weave Scope는 인증 기능을 제공하지 않습니다.

프로덕션 환경에서는 Nginx나 Traefik과 같은 리버스 프록시를 앞단에 배치하여 Basic Auth나 OAuth 인증을 추가하는 것을 권장합니다. 기존 n8n-queue-stack의 Nginx를 활용하여 인증을 추가하는 방법도 고려해 볼 수 있습니다.

# Nginx 설정 예시 - Basic Auth 추가
location /scope/ {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://weave-scope:4040/;
}

컨테이너 제어 기능 비활성화

보안을 더욱 강화하고 싶다면 컨테이너 제어 기능을 비활성화할 수 있습니다.

docker-compose.yml의 command 섹션에 --probe.no-controls 옵션을 추가하면 웹 UI에서 컨테이너를 제어하는 버튼들이 비활성화됩니다. 이 설정은 모니터링 목적으로만 Weave Scope를 사용할 때 유용합니다.

command:
  - "--probe.docker=true"
  - "--weave=false"
  - "--probe.no-controls"  # 컨테이너 제어 기능 비활성화

---

11. 트러블슈팅 가이드

Weave Scope 사용 중 발생할 수 있는 일반적인 문제들과 해결 방법을 안내합니다.

컨테이너가 표시되지 않는 경우

Docker Socket 마운트가 올바르게 설정되어 있는지 확인하세요. /var/run/docker.sock이 정상적으로 마운트되어 있어야 Weave Scope가 Docker 컨테이너를 인식할 수 있습니다. 또한 Docker Desktop이 실행 중인지, Docker 데몬이 정상 동작하는지 확인해 보세요.

# Docker Socket 마운트 확인
docker inspect weave-scope | grep -A 5 "Mounts"

# Docker 데몬 상태 확인
docker info

웹 UI에 접속되지 않는 경우

컨테이너가 정상적으로 실행 중인지 확인하고, 포트 매핑이 올바르게 되어 있는지 점검합니다. 특히 macOS Docker Desktop 환경에서는 network_mode: host가 아닌 포트 매핑 방식을 사용해야 합니다.

# 컨테이너 상태 및 포트 확인
docker ps | grep weave-scope

# 포트 리스닝 상태 확인
lsof -i :4040

# Weave Scope 로그 확인
docker logs weave-scope

네트워크 연결 문제

n8n-shared-network 네트워크가 존재하지 않는 경우 Weave Scope가 시작되지 않습니다. database-stack을 먼저 실행하여 네트워크를 생성하거나, 필요한 경우 수동으로 네트워크를 생성할 수 있습니다.

# 네트워크 존재 여부 확인
docker network ls | grep n8n-shared-network

# 네트워크 수동 생성 (필요한 경우)
docker network create n8n-shared-network

# Weave Scope 재시작
docker compose -f monitoring-stack/docker-compose.yml restart

---

마치며

이번 글에서는 n8n Queue Mode 환경에 Weave Scope 모니터링 시스템을 추가하는 방법을 알아보았습니다. Weave Scope는 복잡한 Docker 환경을 직관적으로 시각화하고, 실시간 모니터링을 통해 문제를 빠르게 파악할 수 있게 해줍니다. 특히 여러 스택으로 구성된 마이크로서비스 환경에서 컨테이너 간의 관계를 한눈에 파악할 수 있어 운영 효율성을 크게 높일 수 있습니다.

다음 글에서는 Prometheus와 Grafana를 활용한 더 상세한 메트릭 모니터링 환경 구축에 대해 알아보겠습니다. n8n 워크플로우의 실행 횟수, 성공/실패율, 응답 시간 등을 시계열 데이터로 수집하고 대시보드로 시각화하는 방법을 다룰 예정입니다.

---

참고 자료

아래의 공식 문서와 리소스를 통해 더 자세한 정보를 확인하실 수 있습니다. Weave Scope는 오픈소스 프로젝트로 GitHub에서 소스 코드와 이슈 트래커를 확인할 수 있으며, Docker Hub에서 다양한 버전의 이미지를 다운로드할 수 있습니다.

리소스	URL
Weave Scope GitHub	https://github.com/weaveworks/scope
Docker Hub 이미지	https://hub.docker.com/r/weaveworks/scope
설치 가이드	https://www.weave.works/docs/scope/latest/installing/
n8n 공식 문서	https://docs.n8n.io/