"Web3 USDT Monitor with Kubernetes & Docker

preencoded.png
Docker + Kubernetes 기반
Web3 USDT 트랜잭션모니터링 시스템
– Ethereum 메인넷 기반 실시간 이벤트 수집 시스템 구축 사례
Docker와 Kubernetes를 활용한 Web3 USDT 트랜잭션 모니터링 시스템 구축 과정을 소개합니다.
생성자: 이서우

preencoded.png
목차
프로젝트개요
프로젝트 목표와 기술 스택 소개
시스템구성 및 기술 환경 요약
구성 요소별 기술 요약, 인프라 환경 및 개발 환경
프로젝트디렉토리구조
구성 파일 역할 및 로컬 테스트
Mini 버전 구성
시스템 구성도와 실행 흐름
Full 버전 확장
추가 기능과 배포 결과

preencoded.png
프로젝트 개요
소개:
Docker와 Kubernetes를 활용하여 Ethereum 메인넷 상에서 발생하는 USDT 전송(Transfer) 이벤트를 실시간으로 수집·
저장하는 모
니터링 시스템
목표:
Web3 환경에서 발생하는 USDT Transfer 이벤트 실시간 추적
Redis + MongoDB를 활용한 비동기 데이터 파이프라인 구성
Docker 이미지 생성 및 Kubernetes 클러스터 기반 확장형 배포
데이터 흐름 구조:
이벤트 감지 → listener가 Redis로 전달 → Worker가 MongoDB 저장

preencoded.png
구성 요소별 기술 요약
구성 요소 사용 기술 역할 설명
Web3 Listener ethers.js, Node.js Ethereum 메인넷에서 USDT Transfer 이벤트 감지
Queue Redis Listener → Worker 간 이벤트 큐 전달 (Pub/Sub)
Worker Node.js, MongoDB Driver Redis에서 이벤트 수신 후 MongoDB 저장
저장소 MongoDB 트랜잭션 로그 저장 (TTL 설정 가능)
컨테이너 관리 Docker 애플리케이션 이미지 빌드 및 배포
오케스트레이션 Kubernetes Pod, ReplicaSet, Service, HPA 등 관리
네트워크 NodePort 외부 접속 허용 (추후 Ingress로 확장 가능)
health check Express / 엔드포인트로 상태 확인 (curl 등으로 확인)

preencoded.png
인프라환경 및 개발 환경
기술스택 :
Node.js, ethers.js, Redis, MongoDB, Docker, Kubernetes (kubeadm + containerd + Calico), MetalLB, Ingress, Express, Ubuntu 24.04 (ARM64)
항목 내용
개발 환경 macOS (Docker Desktop, Chrome) 사용
인프라 구성 VMware + Ubuntu 24.04 3대 (Master 1대 + Worker 2대)
K8s 구성 방식 kubeadm, containerd, Calico CNI, 3-node 클러스터 구성 완료
네트워크 설정 Host-only + Bridged 혼합 (VM 간 통신 + 외부 curl 가능)
Web3 연결 ethers.js + Ethereum 메인넷 (RPC: https://ethereum-rpc.publicnode.com)
필수 설치 항목 kubectl, docker, containerd, crictl, curl, vim 등 사전 설치 완료

preencoded.png
전체 프로젝트디렉토리 구조 및 구성 파일 역할

preencoded.png
로컬MacBook Docker Compose로 테스트
실행 목적
Listener/Worker 동작 검증, Redis → Mongo 저장 확인, Docker Hub 업로드 전 통합 점검
명령어
# 루트에서 실행
docker-compose up --build

preencoded.png
확인 명령어 (macOS)
# Redis 상태 확인
docker exec -it redis redis-cli
> LRANGE usdt-tx-list 0 -1
# Mongo 상태 확인
docker exec -it mongo mongosh
> use web3Monitor
>db.usdtTransfers.find().pretty()

preencoded.png
확인 명령어 (macOS)
docker logs listener docker logs worker

preencoded.png
로컬 MacBook에서 진행
# listener 이미지 빌드 & 푸시
cd listener
docker build -t yourid/usdt-listener:latest .
docker push yourid/usdt-listener:latest
# worker 이미지 빌드 & 푸시
cd ../worker
docker build -t yourid/usdt-worker:latest .
docker push yourid/usdt-worker:latest
docker 이미지 빌드 및 Docker Hub 업로드

preencoded.png
docker 이미지 빌드 및 Docker Hub 업로드

preencoded.png
Mini 버전 : 시스템구성도
[MacBook 사용자]
│
NodePort 접근 (32000)
↓
┌──────────────────────┐
│ usdt-listener Pod │
│ - ethers.js │
│ - express 상태 확인 │
└─────────┬────────────┘
↓ Redis Publish
┌──────────────────────┐
│ Redis Pod │
└─────────┬────────────┘
↓ Redis Subscribe
┌──────────────────────┐
│ usdt-worker Pod │
│ - Redis 구독 │
│ - MongoDB 저장 │
└─────────┬────────────┘
↓
┌──────────────────────┐
│ MongoDB Pod │
└──────────────────────┘

preencoded.png
Mini 버전: 실행 흐름도
[MacBook 터미널]
kubectl apply -f manifests/minimal/
↓ 클러스터에 배포 요청
K8s Master Node
(Scheduler 작동)
↓ 배포 대상 결정
K8s Worker Node들에서 실행
┌────────────────────────────┐
│ Pod: usdt-listener │
│ Pod: redis │
│ Pod: mongo (선택적) │
│ Pod: usdt-worker │
└────────────────────────────┘

preencoded.png
Mini 버전: 시스템구성 요소별기능 및 리소스정리
구성 요소 주요 역할 설명 리소스 종류
usdt-listener Pod ethers.js로 Ethereum 메인넷 USDT Transfer 이벤트 수신,
Express / 상태 확인
Deployment + NodePort
Service
Redis Pod Listener → Worker 간 메시지 전송 (Pub/Sub) Deployment + ClusterIP
Service
usdt-worker Pod Redis에서 메시지 수신 후 MongoDB 저장 Deployment
MongoDB Pod 트랜잭션 영속 저장소 (TTL 옵션 포함 가능) Deployment + ClusterIP
Service
NodePort Service 외부 접근 허용 (curl http://<ip>:32000) Service (NodePort)
접속 방식: NodePort (브라우저 또는 curl)

preencoded.png
Mini 버전: 구성 요소별 Service 사용 여부와 이유
구성 요소 Pod (Deployment) Service 존재 서비스 타입 이유
usdt-listener NodePort 외부에서 상태 확인 (curl) 위해 외부 노출
필요
usdt-worker 없음 다른 Pod에서 직접 접근하지 않음
redis ClusterIP listener/worker가 내부 통신 위해 접근 필요
mongo ClusterIP worker가 Mongo에 저장 위해 접근 필요
Service는 다른 Pod 또는 외부에서 해당 Pod에 접근이 필요한 경우에만 정의합니다.
Listener는 외부 접근을 위해 NodePort, Redis와 Mongo는 내부 통신을 위해 ClusterIP로 구성됩니다.
Worker는 내부 전용 실행기이므로 별도의 Service가 필요하지 않습니다.

preencoded.png
Mini 버전: YAML 구성
위치: manifests/minimal
파일명 설명
listener-deployment.yaml usdt-listener Pod 정의 (ethers.js + Express)
listener-nodeport-service.yaml listener를 외부에서 접근 가능한 NodePort로 서비스
worker-deployment.yaml usdt-worker Pod 정의 (Redis pop → Mongo 저장)
redis-deployment.yaml Redis Pod 정의
mongo-deployment.yaml MongoDB Pod 정의 (emptyDir 기반, PVC 없음)
Service 파일은 listener만 별도로 존재 (NodePort), 다른 Pod는 ClusterIP 서비스 없이 Pod로만 동작하거나, 내부 연결 전제

preencoded.png
Mini 버전: 시스템 배포 및 동작 확인 결과
Master VM에서 실행
1.서비스 배포:
kubectl apply -f manifests/minimal/

preencoded.png
2. 클러스터 내 노드들의 상세 정보(IP, OS, 아키텍처 등 포함)를 출력 :
kubectl get nodes -o wide
3. Pod의 배포 위치(Node), IP, 컨테이너 이미지 등 추가 정보를 함께 출력:
kubectl get pods -o wide

preencoded.png
4. 서비스 상태 정보 조회( kubectl get all 일부만 캡쳐):
kubectl get all
# 혹은
kubectl get svc –o wide

preencoded.png
5. NodePort를 통해 리스너 서비스에 외부에서 정상 접근됨을 확인:
curl http://192.168.0.61:32000
192.168.0.61은 worker1 노드의 브리지 IP이며, 포트 32000은 NodePort로 설정한 값입니다.
노드 Bridge IP (ens160) 내부 Pod IP (ens192)
k8s-worker1 192.168.0.61 172.16.120.11
K8s-worker2 192.168.0.62 172.16.120.12

preencoded.png
6. Redis 저장 확인:
kubectl exec -it redis-xxxxx -- redis-cli
> LRANGE usdt-tx-list 0 -1
7. Redis 로그 확인:
kubectl logs -f redis-<Pod명>

preencoded.png
Mini 버전: 시스템배포 및 동작 확인 결과
8. MongoDB 저장 확인:
kubectl exec -it mongo-xxxxx -- mongosh
> use web3Monitor
> db.usdtTransfers.find().pretty()
9. MongoDB 로그 확인:
kubectl logs -f mongo-<Pod명>

preencoded.png
10. listener 로그 확인:
kubectl logs deploy/usdt-listener

preencoded.png
11. worker 로그 확인:
kubectl logs deploy/usdt-worker

preencoded.png
Full 버전 확장 구성
항목 설명
MetalLB NodePort 대신 LoadBalancer IP 부여 (MetalLB 설치 + ConfigMap)
Ingress-NGINX 도메인 기반 접근 (listener.local) 설정
ArgoCD GitOps 방식의 배포 자동화 (YAML을 Git에 push → 자동 배포)
PVC MongoDB 데이터 영속화를 위한 Volume 설정 추가 가능
모든 구성 요소는 manifests/full 디렉토리에서 정의
접속 방식: Ingress 도메인 또는 외부 IP (listener.local, http://<LB IP>:30000 등)

preencoded.png
Full 버전: YAML 구성
위치: manifests/full/
파일명 설명
listener-deployment.yaml listener Pod 정의
listener-ingress.yaml Ingress 설정 (listener.local 등 도메인 기반 접근)
metallb-config.yaml MetalLB IP Range 정의 (LoadBalancer 사용 위해)
app.yaml 전체 구성 통합 배포 (listener, worker, redis, mongo 포함)
worker-deployment.yaml worker Pod 정의
redis-deployment.yaml redis Pod 정의
mongo-deployment.yaml mongo Pod 정의
이 구성에서는 Ingress-NGINX, MetalLB를 통한 도메인 기반 접근, 또는 LoadBalancer IP 기반 노출이 전제됨.

preencoded.png
트러블슈팅 및 참고 사항
1. NAT → Bridged 네트워크전환(ARM64 VMware 이슈)
문제 해결책
NAT 모드: ping, DNS 실패 발생 VMware → Bridged (Wi-Fi) 모드로 전환
DHCP로 IP 자동 할당 → 매번 변경됨 netplan으로 고정 IP 설정
재부팅 시 설정 초기화됨 cloud-init 비활성화 설정
최종결과
모든 VM에서 ping, ssh, 외부 접속, kubeadm join 성공
실질 구성: Host-only로 내부 통신 + Bridged로 외부 접속 → 혼합 네트워크 구성
원인 요약
Apple Silicon + Fusion 13 + ARM64 Ubuntu 조합에서는
NAT(vmnet8)가 macOS의 pfctl 방화벽 설정과 충돌 → DNS/Ping 실패

preencoded.png
트러블슈팅및 참고 사항
2. Flannel 설치 실패→ Calico로 대체
문제 해결
flannel:v0.24.2-arm64 설치 시 DaemonSet 생성 안됨 kube-flannel.yml 삭제 후 Calico 설치
subnet.env 오류 발생 (ARM 환경에서 flannel 버그) calico.yaml 적용 → calico-node 각 노드에 정상 배포 확인
kubectl get pods -n kube-system | grep calico
→ 모든 노드에 Calico DaemonSet 배포 완료, 통신 이상 없음
왜 대체했는가?
Flannel은 ARM64 호환성이 낮고,
Calico는 실무에서도 선호되는 CNI, ARM 환경에서도 안정적으로 작동

preencoded.png
프로젝트 전체 코드& 이미지보기
GitHub Repository
전체 소스코드와 Kubernetes YAML 구성은 아래 GitHub 링크에서 확인할 수 있습니다:
https://github.com/seowlee/k8s-web3-monitor
● Listener / Worker 코드
● Dockerfile
● Kubernetes manifest (minimal / full)
● README 정리 포함
DockerHub Repository
배포에 사용된 Docker 이미지들은 아래 DockerHub 링크에서 확인 가능합니다:
https://hub.docker.com/repositories/seowlee
● seowlee/usdt-listener
● seowlee/usdt-worker
● 로컬 테스트 또는 Kubernetes 배포 시 pull 가능

"Web3 USDT Monitor with Kubernetes & Docker

More Related Content

Similar to "Web3 USDT Monitor with Kubernetes & Docker

"Web3 USDT Monitor with Kubernetes & Docker