본문 바로가기
Circuit Eng.

Bambuddy로 Bambu Lab 3D 프린터를 내 서버에서 관리하기: 기능, 장점, Docker Compose 설치 예시

by dragom 2026. 6. 4.
반응형

Bambuddy로 Bambu Lab 3D 프린터를 내 서버에서 관리하기: 기능, 장점, Docker Compose 설치 예시

Bambuddy로 Bambu Lab 3D 프린터를 내 서버에서 관리하기: 기능, 장점, Docker Compose 설치 예시

Bambu Lab 프린터를 쓰다 보면 처음에는 Bambu Handy와 Bambu Studio만으로 충분해 보입니다. 하지만 출력 이력이 쌓이고, 실패 원인을 추적하고, 여러 대를 운용하거나, 클라우드 의존도를 낮추고 싶어지는 순간 별도의 관리 도구가 필요해집니다. 그때 가장 흥미로운 선택지 중 하나가 **Bambuddy**입니다.

Bambuddy란?

Bambuddy는 Bambu Lab 3D 프린터를 위한 오픈소스 self-hosted 관리 시스템입니다. 공식 슬로건은 “Your printers. No cloud. Your rules.”에 가깝습니다. 핵심은 단순합니다.

  • 출력 데이터와 이력을 내 서버에 저장
  • Bambu Cloud 없이 LAN/Developer Mode 기반으로 프린터 제어
  • 여러 대의 프린터를 하나의 웹 UI에서 모니터링
  • 출력 파일 아카이브, 재출력, 큐, 스케줄링, 알림, 통계까지 통합
  • Bambu Studio/OrcaSlicer에서 보이는 **Virtual Printer** 기능 지원

    • 즉 Bambuddy는 “Bambu 프린터용 개인 클라우드 + 프린트 팜 대시보드 + 출력 아카이브”에 가깝습니다.

    왜 추천할 만한가?

    1. 클라우드 의존도를 낮출 수 있다

    Bambu Lab 생태계는 편하지만, 많은 기능이 계정/클라우드/외부 서버에 묶여 있습니다. Bambuddy는 Developer Mode와 로컬 네트워크 통신을 활용해 프린터 상태, 출력 이력, 파일 관리, 카메라 스트림 등을 로컬에서 다루는 방향입니다.

    개인적으로는 이 점이 가장 큰 장점입니다. 3D 프린터 출력 파일은 단순 취미 파일이 아니라, 개인 프로젝트·제품 프로토타입·실험 데이터가 섞일 수 있습니다. 이를 외부 클라우드가 아니라 내 NAS나 홈서버에 보관할 수 있다는 점은 꽤 큽니다.

    2. 출력 이력과 실패 분석이 강하다

    Bambuddy는 출력물을 자동으로 아카이브하고, 3MF 메타데이터, 썸네일, 출력 시간, 필라멘트 사용량, 실패 사유 등을 기록할 수 있습니다. “이 모델 언제 뽑았더라?”, “이 출력 실패가 몇 번째였지?”, “PLA Matte Black 얼마나 썼지?” 같은 질문에 답하기 쉬워집니다.

    3. 여러 대를 관리할 때 가치가 급격히 커진다

    A1 한 대만 쓸 때도 편하지만, P1S/X1C/H2D 등 여러 대를 운용하면 Bambuddy의 장점이 더 선명해집니다.

  • 프린터별 상태 카드
  • 프린터 검색/필터
  • 일괄 pause/resume/stop
  • 출력 큐와 스케줄링
  • 모델 기반 “아무 X1C에 보내기” 같은 할당
  • 필라멘트 조건이 맞는 프린터에만 배정
  • 스마트 플러그로 자동 전원 on/off

    • 프린트 팜까지는 아니어도 “집에 Bambu 프린터 2~3대”만 되어도 공식 앱만으로는 관리가 번거로워집니다.

    4. Virtual Printer가 유용하다

    Bambuddy의 Virtual Printer는 Bambu Studio/OrcaSlicer에서 하나의 Bambu 프린터처럼 보이게 하는 기능입니다. 이를 통해 슬라이서에서 바로 Bambuddy 쪽으로 출력을 보내고, Bambuddy가 아카이브·검토·큐·프록시 같은 흐름을 담당할 수 있습니다.

    모드도 단순 전송뿐 아니라 Archive, Review, Queue, Proxy 등으로 나뉘며, 특히 여러 사용자가 출력물을 보내는 환경에서는 “바로 프린터로 쏘기”보다 “Bambuddy가 중간에서 기록하고 검토하고 배정”하는 구조가 훨씬 안전합니다.

    주요 기능 정리

    출력 아카이브

  • 3MF 자동 아카이브
  • 3D 모델 미리보기
  • 중복 감지와 전체 텍스트 검색
  • 사진 첨부, 실패 분석
  • 멀티 플레이트 썸네일 탐색
  • 기존 아카이브에서 재출력
  • 출력별 Print Log 기록

    • 모니터링과 제어

  • WebSocket 기반 실시간 상태
  • 라이브 카메라 스트리밍과 스냅샷
  • pause/resume/stop, 조명, 속도 제어
  • AMS 슬롯 정보와 Load/Unload
  • HMS 에러 모니터링
  • 출력 성공률, 필라멘트 사용량, 비용 분석
  • CSV/Excel 내보내기

    • 큐와 자동화

  • 드래그 앤 드롭 출력 큐
  • 날짜/시간 기반 예약 출력
  • 여러 프린터 동시 선택
  • 모델/프린터 타입 기반 자동 할당
  • 필라멘트 검증과 AMS 매핑
  • 스마트 플러그 연동
  • 출력 전 자동 전원 켜기, 출력 후 cooldown 뒤 전원 끄기

    • 파일 매니저와 라이브러리

  • 3MF, gcode, STL 업로드/정리
  • ZIP 압축 해제
  • 폴더 구조 관리
  • NAS/외부 폴더 마운트
  • STL 썸네일 생성
  • 선택적으로 서버 사이드 슬라이싱 API 연동

    • 알림과 연동

  • Telegram, Discord, WhatsApp
  • Email, Pushover, ntfy
  • Home Assistant persistent notification
  • Webhook, API Key
  • MQTT, Prometheus, Grafana 연동
  • Spoolman 필라멘트 동기화

    • 인증과 사용자 관리

  • 선택적 로그인 기능
  • 관리자/운영자/뷰어 그룹 권한
  • 세부 권한 제어
  • 사용자별 Bambu Cloud 계정
  • TOTP/Email OTP 2FA
  • OIDC/SSO 연동

    • 설치 전 준비사항

    공식 문서 기준으로 기본 전제는 다음과 같습니다.

    1. Docker / Docker Compose 설치

    2. Bambu Lab 프린터에서 Developer Mode 활성화

    3. Bambu Studio 또는 OrcaSlicer에서 Store sent files on external storage 활성화

    4. Bambuddy 서버와 프린터가 같은 로컬 네트워크에 존재

    5. Linux라면 가능하면 network_mode: host 사용

    Docker Desktop을 쓰는 macOS/Windows에서는 host network가 제대로 지원되지 않으므로 ports 매핑 방식으로 설치하고, 프린터는 자동 탐색 대신 IP로 직접 추가하는 편이 현실적입니다.

    가장 간단한 설치 방법

    mkdir bambuddy
cd bambuddy
curl -O https://raw.githubusercontent.com/maziggy/bambuddy/main/docker-compose.yml
docker compose up -d

    접속:

    http://서버IP:8000

    로컬에서 실행했다면:

    http://localhost:8000

    로그 확인:

    docker compose logs -f

    업데이트:

    docker compose pull
docker compose up -d

    중지:

    docker compose down

    Docker Compose 예시: Linux 권장 구성

    아래 예시는 Linux 홈서버/NAS/미니PC에서 쓰기 좋은 형태입니다. 자동 프린터 탐색과 카메라/Virtual Printer 호환성을 위해 network_mode: host를 사용합니다.

    services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    restart: unless-stopped

    # Linux에서는 자동 프린터 탐색, 카메라 스트리밍, Virtual Printer를 위해 host 네트워크 권장
    network_mode: host

    # FTPS/RTSP 등 일부 Virtual Printer 포트가 1024 미만 privileged port를 사용하므로 필요
    cap_add:
      - NET_BIND_SERVICE

    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
      # 선택: 백업을 NAS/외장 디스크로 분리하고 싶을 때
      # - /mnt/nas/bambuddy-backups:/app/data/backups
      # 선택: 외부 라이브러리 폴더. BAMBUDDY_EXTERNAL_ROOTS와 함께 사용
      # - /mnt/nas/3d-prints:/external/nas:ro
      # 선택: Tailscale 인증서 연동
      # - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
      # 선택: 내부 CA/자가서명 인증서를 신뢰해야 할 때
      # - ./certs:/usr/local/share/ca-certificates:ro

    environment:
      TZ: Asia/Seoul
      PUID: "1000"
      PGID: "1000"
      PORT: "8000"
      # DEBUG: "false"
      # LOG_LEVEL: INFO

      # Docker Desktop의 bridge/ports 모드에서 Virtual Printer FTP passive mode가 필요하면
      # Docker 호스트의 LAN IP를 지정
      # VIRTUAL_PRINTER_PASV_ADDRESS: "192.168.0.10"

      # SQLite 기본값 대신 외부 PostgreSQL을 쓰고 싶을 때
      # DATABASE_URL: "postgresql+asyncpg://bambuddy:changeme@postgres:5432/bambuddy"

      # 서버 사이드 슬라이싱 sidecar를 연결할 때
      # SLICER_API_URL: "http://127.0.0.1:3003"

      # 외부 폴더 등록 기능 허용. 비워두면 비활성화됨
      # BAMBUDDY_EXTERNAL_ROOTS: "/external/nas"

      # Home Assistant 등 로컬 인증서 신뢰가 필요할 때
      # USE_SYSTEM_TRUST_STORE: "true"

volumes:
  bambuddy_data:
  bambuddy_logs:

    Docker Desktop/macOS/Windows용 ports 구성

    Docker Desktop은 Linux의 host network와 동작이 다릅니다. 이 경우 network_mode: host를 제거하고 ports를 직접 열어야 합니다. 단, SSDP 기반 자동 프린터 탐색은 제한될 수 있으므로 프린터를 IP로 수동 추가하는 것을 전제로 보는 편이 좋습니다.

    services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    restart: unless-stopped
    cap_add:
      - NET_BIND_SERVICE
    ports:
      - "8000:8000"                  # Web UI
      - "3000:3000"                  # Virtual Printer bind/detect
      - "3002:3002"                  # Virtual Printer bind/detect alt
      - "8883:8883"                  # Virtual Printer MQTT
      - "990:990"                    # Virtual Printer FTP control
      - "6000:6000"                  # File transfer tunnel
      - "322:322"                    # RTSP camera proxy
      - "2024-2026:2024-2026"        # Bambu proprietary ports
      - "50000-51000:50000-51000"    # FTP passive data
    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
    environment:
      TZ: Asia/Seoul
      PUID: "1000"
      PGID: "1000"
      PORT: "8000"
      VIRTUAL_PRINTER_PASV_ADDRESS: "192.168.0.10"  # Docker 호스트 LAN IP로 변경
volumes:
  bambuddy_data:
  bambuddy_logs:

    `.env` 파일로 관리하기

    Compose 파일에 값을 직접 쓰는 대신 .env 파일을 두면 운영이 편합니다.

    TZ=Asia/Seoul
PUID=1000
PGID=1000
PORT=8000
# VIRTUAL_PRINTER_PASV_ADDRESS=192.168.0.10
# DATABASE_URL=postgresql+asyncpg://bambuddy:changeme@postgres:5432/bambuddy
# SLICER_API_URL=http://127.0.0.1:3003
# BAMBUDDY_EXTERNAL_ROOTS=/external/nas:/external/projects
# USE_SYSTEM_TRUST_STORE=true

    실행:

    docker compose --env-file .env up -d

    ENV 변수 설명

    `TZ`

    컨테이너 시간대입니다. 한국 사용자는 Asia/Seoul을 권장합니다. 출력 로그, 예약 출력, 통계 날짜가 시간대 영향을 받습니다.

    `PUID`, `PGID`

    컨테이너 내부 프로세스가 어떤 UID/GID로 파일을 쓸지 정합니다. Linux에서 볼륨 파일 권한 문제가 생기면 호스트 사용자와 맞추는 것이 좋습니다.

    확인:

    id -u
id -g

    `PORT`

    Bambuddy 웹 UI 포트입니다. 기본은 8000입니다. host network 모드에서는 앱이 이 포트로 뜨고, ports 모드에서는 8000:8000처럼 매핑합니다.

    `VIRTUAL_PRINTER_PASV_ADDRESS`

    Docker bridge/ports 모드에서 Virtual Printer의 FTP passive mode가 NAT 뒤에 있을 때 필요할 수 있습니다. 이 값은 컨테이너 IP가 아니라 Docker 호스트의 LAN IP로 설정해야 합니다.

    예:

    VIRTUAL_PRINTER_PASV_ADDRESS=192.168.0.10

    `DATABASE_URL`

    기본은 SQLite입니다. 개인/소규모 환경은 SQLite로 충분합니다. 여러 사용자, 많은 출력 로그, 장기 운영, 백업/복구 정책이 중요한 환경이라면 PostgreSQL을 고려할 수 있습니다.

    예:

    DATABASE_URL=postgresql+asyncpg://bambuddy:changeme@postgres:5432/bambuddy

    `SLICER_API_URL`

    Bambuddy는 기본적으로 데스크톱 슬라이서를 URI scheme으로 여는 방식으로도 동작합니다. 하지만 서버에서 직접 STL/3MF를 슬라이싱하고 싶다면 별도 slicer-api sidecar를 띄우고 이 URL을 지정합니다.

    `BAMBUDDY_EXTERNAL_ROOTS`

    NAS나 외장 디스크의 3D 모델 라이브러리를 Bambuddy에서 외부 폴더로 등록할 수 있게 해주는 allowlist입니다. 보안을 위해 기본값은 비활성화입니다. 반드시 Docker volume으로 마운트한 컨테이너 내부 경로만 지정해야 합니다.

    예:

    BAMBUDDY_EXTERNAL_ROOTS=/external/nas:/external/projects

    `USE_SYSTEM_TRUST_STORE`

    Home Assistant 등 내부 서비스가 사설 CA나 자가서명 인증서를 사용할 때, 컨테이너에 마운트한 인증서를 시스템 trust store로 쓰게 하는 옵션입니다.

    Volume 설명

    `bambuddy_data:/app/data`

    가장 중요한 볼륨입니다. Bambuddy 데이터베이스, 출력 아카이브, 설정, Virtual Printer 관련 데이터 등이 저장됩니다. 백업 대상 1순위입니다.

    `bambuddy_logs:/app/logs`

    애플리케이션 로그가 저장됩니다. 장애 분석이나 장기 로그 보관이 필요 없다면 기본 named volume으로 충분합니다.

    `/app/data/backups`

    스케줄 백업을 NAS나 외장 스토리지로 빼고 싶다면 별도 bind mount를 권장합니다.

    - /mnt/nas/bambuddy-backups:/app/data/backups

    외부 라이브러리 마운트

    읽기 전용 마운트를 권장합니다.

    - /mnt/nas/3d-prints:/external/nas:ro

    그리고 ENV에 다음을 추가합니다.

    BAMBUDDY_EXTERNAL_ROOTS=/external/nas

    선택: 서버 사이드 Slicer API 구성

    Bambuddy는 slicer-api sidecar를 통해 OrcaSlicer 또는 Bambu Studio CLI 래퍼를 사용할 수 있습니다. 이 기능을 켜면 파일 매니저의 Slice 버튼으로 서버에서 직접 슬라이싱 결과를 만들 수 있습니다.

    # Bambuddy 저장소의 slicer-api/docker-compose.yml을 별도 디렉터리에 두고 실행
# OrcaSlicer API만 실행
cd slicer-api
docker compose up -d

# Bambu Studio API까지 함께 실행
docker compose --profile bambu up -d

# 상태 확인
curl http://localhost:3003/health  # OrcaSlicer API
curl http://localhost:3001/health  # Bambu Studio API

    slicer-api/.env 예시:

    ORCA_API_PORT=3003
BAMBU_API_PORT=3001
ORCA_VERSION=2.3.2
BAMBU_VERSION=02.07.01.57

    Bambuddy 설정에서 Slicer API를 켜고 URL을 다음처럼 지정합니다.

    http://서버IP:3003

    운영 팁

    1. Linux 서버에서는 host network를 우선 고려

    프린터 자동 탐색, 카메라 스트리밍, Virtual Printer는 네트워크 포트와 멀티캐스트 영향을 많이 받습니다. Linux에서는 network_mode: host가 가장 덜 귀찮습니다.

    2. Docker Desktop에서는 수동 IP 추가를 전제로 한다

    macOS/Windows Docker Desktop은 host networking 제약이 있습니다. ports 매핑으로 실행하고 프린터는 자동 발견을 기대하기보다 IP로 직접 추가하는 것이 안정적입니다.

    3. 데이터 볼륨은 반드시 백업

    bambuddy_data에는 출력 이력과 아카이브가 쌓입니다. docker compose down은 볼륨을 지우지 않지만, docker compose down -v는 볼륨을 삭제할 수 있으니 주의해야 합니다.

    백업 예:

    docker run --rm   -v bambuddy_bambuddy_data:/data:ro   -v "$PWD":/backup   alpine tar czf /backup/bambuddy-data-$(date +%F).tgz -C /data .

    4. 외부 공개는 reverse proxy와 인증을 함께

    집 밖에서 접속하려면 Cloudflare Tunnel, Tailscale, WireGuard, Nginx reverse proxy 등을 고려할 수 있습니다. 단, 프린터 제어 시스템이므로 공개 인터넷에 무방비로 열어두는 것은 추천하지 않습니다. 최소한 Bambuddy 인증, HTTPS, 접근 제어를 함께 적용하는 것이 좋습니다.

    5. 처음에는 기능을 조금씩 켜기

    처음부터 Virtual Printer, Slicer API, Smart Plug, SSO, 외부 폴더, Prometheus까지 한 번에 켜면 문제 원인 추적이 어려워집니다. 추천 순서는 다음과 같습니다.

    1. Bambuddy 기본 설치

    2. 프린터 수동/자동 추가

    3. 카메라/상태 확인

    4. 출력 아카이브 확인

    5. 알림 연동

    6. Virtual Printer

    7. Smart Plug 자동화

    8. Slicer API / 외부 라이브러리 / 고급 인증

    Bambu Cloud와 비교하면?

    Bambu Cloud는 진입 장벽이 낮고 공식 생태계라는 장점이 있습니다. 반면 Bambuddy는 직접 설치하고 관리해야 하지만, 데이터 소유권과 자동화 범위가 훨씬 넓습니다.

  • 간편함: Bambu Cloud 우세
  • 데이터 소유권: Bambuddy 우세
  • 다중 프린터 관리: Bambuddy 우세
  • 출력 이력/분석: Bambuddy 우세
  • 외부 접근 편의성: Bambu Cloud 우세
  • 커스터마이징: Bambuddy 우세
  • 유지보수 부담: Bambu Cloud 우세

    • 따라서 “한 대를 가끔 출력”하는 사용자에게는 공식 앱만으로도 충분합니다. 하지만 출력 이력을 체계적으로 남기고 싶거나, 여러 대를 관리하거나, 홈서버/NAS를 이미 운영 중이라면 Bambuddy는 충분히 설치해볼 만합니다.

    결론

    Bambuddy는 Bambu Lab 프린터를 단순히 “모니터링하는 앱”이 아니라, 출력 파일·프린터 상태·필라멘트·전력·알림·큐·권한까지 묶어주는 self-hosted 운영 도구입니다.

    특히 다음 사용자에게 추천합니다.

  • Bambu Lab 프린터를 2대 이상 운용하는 사용자
  • 출력 이력과 실패 원인을 꾸준히 관리하고 싶은 사용자
  • Bambu Cloud 의존도를 줄이고 싶은 사용자
  • NAS/홈서버/Docker 환경에 익숙한 사용자
  • Telegram, Discord, Home Assistant, MQTT, Grafana 연동을 좋아하는 사용자
  • 프린트 팜처럼 큐와 스케줄링이 필요한 사용자

    • 처음 설치는 Docker Compose 한 파일이면 충분합니다. 이후 필요에 따라 Virtual Printer, 외부 라이브러리, Slicer API, Smart Plug, 인증 기능을 하나씩 켜가면 됩니다. Bambu 프린터를 “내 클라우드”에서 운영하고 싶다면, Bambuddy는 지금 가장 먼저 살펴볼 만한 프로젝트입니다.

    참고 링크

  • Bambuddy GitHub: https://github.com/maziggy/bambuddy
  • Bambuddy 공식 사이트: https://bambuddy.cool/
  • Docker 설치 문서: https://wiki.bambuddy.cool/getting-started/docker/
  • Slicer API: https://github.com/maziggy/bambuddy/tree/main/slicer-api

    • 반응형

    'Circuit Eng.' 카테고리의 다른 글

    ZAM 메모리란 무엇인가: HBM의 TSV 한계를 넘으려는 수직 도시 전략  (0) 2026.06.27
    ZAM 메모리란 무엇인가: HBM의 TSV 한계를 넘으려는 수직 도시 전략  (0) 2026.06.27
    전례 없는 코스피 상승, 어디까지 갈까? 8천피 돌파 배경과 ‘1만피’ 전망 총정리  (1) 2026.05.29
    ST-LM317  (0) 2020.06.16

    관련글

    댓글

    티스토리툴바