Project Nexus

Project Nexus는 Docker Compose 같은 컨테이너 환경에서 함께 실행되며, 같은 Docker network에 있는 컨테이너의 상태, Docker healthcheck, DNS/TCP 연결성, 인증 실패 로그 패턴을 주기적으로 감시하는 경량 모니터링 데몬입니다.

수집 결과와 이상 징후는 표준 출력 로그로 남고, 내장 GUI 대시보드에서도 바로 확인할 수 있습니다.

배포 모델

Project Nexus의 기본 배포 방식은 Docker 컨테이너입니다.

• Project Nexus 컨테이너를 감시 대상 컨테이너들과 같은 Docker network에 함께 띄웁니다.
• 애플리케이션 옵션으로 network 이름을 넘기지 않아도 됩니다.
• 컨테이너 내부에서 자기 자신이 붙어 있는 Docker network를 자동 감지하고, 그 network의 컨테이너들을 감시합니다.
• 호스트 Docker socket을 mount해 같은 Docker daemon의 컨테이너와 네트워크를 조회합니다.

Docker socket mount는 호스트 Docker daemon 제어 권한을 제공하므로 신뢰할 수 있는 환경에서만 사용해야 합니다.

이미지 빌드

로컬에서 이미지를 빌드하려면 다음 명령을 사용합니다.

docker build -t project-nexus:latest .

이미지는 .NET ASP.NET runtime 기반으로 빌드됩니다. 네이티브 툴체인을 요구하지 않으므로 빌드 환경 의존성이 적고, Docker가 지원하는 플랫폼에서는 일반적인 멀티 아키텍처 빌드 흐름을 사용할 수 있습니다.

docker buildx build --platform linux/amd64,linux/arm64 -t project-nexus:latest .

빠른 실행

이미 app-net에 여러 컨테이너가 떠 있다면 Project Nexus 컨테이너를 같은 Docker network에 붙이면 됩니다.

여기서 --network app-net은 Docker가 Project Nexus 컨테이너를 붙일 네트워크를 정하는 옵션입니다. Project Nexus 애플리케이션 옵션이 아닙니다.

docker run -d \
  --name project-nexus \
  --restart unless-stopped \
  --network app-net \
  -p 127.0.0.1:8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  project-nexus:latest

Project Nexus는 자신이 붙은 app-net을 자동 감지해 같은 network의 컨테이너를 모니터링합니다. 브라우저에서는 http://localhost:8080으로 컨테이너 상태 대시보드를 확인할 수 있습니다.

Docker Compose

Compose에서 가장 자연스러운 방식은 Project Nexus를 다른 서비스들과 같은 compose 파일에 추가하는 것입니다.

별도 network 이름을 넘기지 않으면 Compose 기본 network에 모든 서비스가 함께 붙고, Project Nexus가 그 network를 자동 감지합니다.

services:
  app:
    image: example/app:latest

  project-nexus:
    image: project-nexus:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

이 저장소의 예시 compose 파일은 Project Nexus만 단독으로 띄웁니다.

docker compose -f deploy/docker/compose.yml up -d --build

실행 후 http://localhost:8080에서 대시보드를 열 수 있습니다. 호스트 포트를 바꾸려면 NEXUS_WEB_PORT 환경 변수를 지정합니다.

NEXUS_WEB_PORT=18080 docker compose -f deploy/docker/compose.yml up -d --build

네트워크 자동 감지

기본값은 --network auto입니다. 일반적인 Docker Compose 배포에서는 직접 지정할 필요가 없습니다.

• 컨테이너 안에서 실행 중이면 Project Nexus 자신의 Docker network를 inspect해 감시 대상으로 사용합니다.
• 컨테이너가 하나의 user-defined network에만 붙어 있으면 그 network를 자동 선택합니다.
• 컨테이너가 여러 user-defined network에 붙어 있어도, 다른 컨테이너가 가장 많이 붙어 있는 network가 하나로 좁혀지면 자동 선택합니다.
• 그래도 동률이면 어떤 network를 감시할지 모호하므로 명시 지정이 필요합니다.
• 컨테이너 밖에서 개발 실행 중이면 bridge로 fallback합니다.

명시 지정은 예외적인 운영 환경에서만 사용합니다.

project-nexus --network app-net

Docker 연결 방식

Docker endpoint 우선순위는 다음과 같습니다.

1. CLI의 --docker-endpoint <uri>
2. 환경 변수 DOCKER_HOST
3. OS별 기본 endpoint

기본 endpoint는 다음 순서로 선택됩니다.

Windows: npipe://./pipe/docker_engine 또는 Docker Desktop named pipe
macOS:   unix:///var/run/docker.sock, ~/.docker/run/docker.sock
Linux:   unix:///var/run/docker.sock, ~/.docker/desktop/docker.sock

컨테이너 배포에서는 보통 별도 endpoint 설정 없이 socket mount만 추가하면 됩니다.

-v /var/run/docker.sock:/var/run/docker.sock

대시보드와 로그 확인

Project Nexus는 별도 저장소나 외부 전송 없이 메모리 버퍼와 표준 출력에 로그를 남깁니다.

기본 대시보드는 다음 주소에서 열립니다.

http://localhost:8080

대시보드 데이터는 /api/dashboard에서 JSON으로 제공됩니다. 원문 로그만 필요하면 /logs, 로그 JSON이 필요하면 /logs.json을 사용할 수 있습니다.

컨테이너 로그로도 같은 내용을 확인할 수 있습니다.

docker logs -f project-nexus

Compose로 실행했다면 다음 명령으로 확인합니다.

docker compose -f deploy/docker/compose.yml logs -f project-nexus

일반 수집 틱에는 현재 네트워크와 컨테이너 목록이 출력되고, healthcheck 실패, 컨테이너 종료, 연결성 probe 실패, 로그 패턴 매치 같은 이상 징후는 별도 이벤트 로그로 출력됩니다.

Kubernetes 대비

현재 구현은 Docker Engine API와 Docker socket을 기준으로 동작합니다.

Kubernetes 환경에서는 Docker socket mount를 전제로 하지 않는 방향이 더 안전하므로, 이후에는 Kubernetes API 기반 provider를 별도로 추가하는 것이 맞습니다.

이미 내부 구조는 상태 수집기, 로그 스캐너, 연결성 probe가 인터페이스로 분리되어 있어 Docker provider 외에 Kubernetes provider를 추가할 수 있습니다. Kubernetes 버전에서는 namespace, label selector, pod readiness, service endpoint를 기준으로 감시 대상을 잡는 방식이 자연스럽습니다.

개발 실행

dotnet build ProjectNexus.sln
dotnet run --project src/ProjectNexus.Daemon -- --network bridge --once
dotnet run --project src/ProjectNexus.Daemon -- --network app-net --interval 10

CLI 옵션

--network <name>          감시할 Docker 네트워크. 기본값: auto.
--docker-endpoint <uri>   Docker API endpoint. 미지정 시 자동 감지.
--interval <seconds>      실행 간격. 기본값: 1.
--once                    한 번만 수집하고 종료.
--web-url <url>           웹 대시보드 bind URL. 기본값: http://0.0.0.0:8080.
--no-web                  웹 대시보드 비활성화.
--probe-image <image>     연결성 probe 컨테이너 이미지. 기본값: busybox:1.36.
--probe-timeout <sec>     DNS/TCP probe timeout. 기본값: 3.
--probe-target <host:port>
                          명시적 연결성 검사 대상. 여러 번 지정 가능.
--no-probes               DNS/TCP 연결성 검사 비활성화.
--no-log-scan             로그 패턴 검사 비활성화.
--log-pattern <regex>     추가 로그 정규식.
-h, --help                도움말 출력.