호스트 소프트웨어와 프린트 팜
📍 현재 위치: 3부 · 소프트웨어 스택 — 16장 중 8장. 슬라이서가 G-code를 만들고 CAD 장에서 모델을 만들었습니다. 이제 프린터 옆에서 파일을 받고, 작업을 시작하고, 진행 상황을 알려 주는 소프트웨어를 살펴봅니다.
식당을 떠올려 보세요. 요리사(펌웨어)는 주문서에 적힌 그대로 한 번에 요리 하나만 할 줄 압니다. 호스트 소프트웨어는 웨이터이자 주문 시스템입니다. 주문(G-code 파일)을 받아 대기열에 넣고, 요리사에게 시작을 알리고, 테이블에서든 휴대폰에서든 멀리 떨어진 곳에서든 진행 상황을 볼 수 있게 해 줍니다. 프린트 팜은 요리사 스무 명과 모든 주문서를 보는 매니저 한 명이 있는 식당입니다. 그리고 웨이터는 문 앞의 누가 시키든 그대로 하기 때문에, 누구를 들여보낼지 정해야 합니다.
이 장에서 다루는 내용
두 가지 주요 오픈 호스트 스택, 즉 OctoPrint와 Klipper 계열(Moonraker와 Mainsail 또는 Fluidd 웹 인터페이스)을 다룹니다. 이들의 HTTP API가 어떻게 동작하는지를 실행 가능한 클라이언트로 보고, 여러 프린터를 관리하는 오픈 도구와 중요한 보안 규칙도 살펴봅니다. 프린터 호스트는 접속이 허용된 누구에게든 노즐을 가열하고 모터를 움직여 주기 때문입니다.
왜 호스트가 필요한가
펌웨어(펌웨어 참고)는 마이크로컨트롤러에서 G-code를 실행합니다. 그 옆의 작은 컴퓨터인 호스트(host)는 마이크로컨트롤러가 잘하지 못하는 일, 즉 웹 서버, 파일 저장, 카메라, 작업 이력, 네트워크 스택을 더해 줍니다. Klipper는 이런 분업을 명시적으로 드러냅니다. README는 "범용 컴퓨터의 힘과 하나 이상의 마이크로컨트롤러"를 결합한다고 설명합니다 [1].
OctoPrint
OctoPrint는 소비자용 3D 프린터를 제어하는 웹 인터페이스입니다. 저장소는 AGPL-3.0 라이선스이고, Python 프로젝트이며, README에서 공식 플러그인 저장소를 링크합니다 [2].
REST API
OctoPrint 문서는 API 요청을 인증하는 세 가지 방법을 보여 줍니다. X-Api-Key 헤더, Authorization: Bearer 헤더, 그리고 테스트 전용이라고 밝힌 apikey 쿼리 매개변수입니다 [3]. 예를 들어 헤더를 붙인 GET /api/version은 api, server, text 키를 가진 JSON 객체를 돌려줍니다 [4]. POST /api/job에 본문 {"command": "start"}를 보내면 선택된 작업을 시작하며, 성공하면 204, 이미 작업이 진행 중이거나 프린터가 작동 가능한 상태가 아니면 409를 돌려줍니다 [5]. 인증 문서에서 안전과 관련해 중요한 점이 두 가지 있습니다. 접근 제어가 켜져 있으면 로그인 외의 모든 엔드포인트에 대한 익명 요청은 403으로 거부되고, 접근 제어가 꺼져 있으면 익명 요청이 관리자 권한을 얻습니다 [3].
# Requires a running OctoPrint and an API key (see the Application Keys workflow in its docs)
curl -H "X-Api-Key: $OCTOPRINT_KEY" http://HOST:5000/api/version
시험해 볼 OctoPrint 인스턴스가 없었으므로, 이 명령과 응답 형태는 실행 결과가 아니라 문서에 근거합니다. 예시의 주소는 자신의 주소로 바꿔야 하는 자리표시자입니다.
Klipper 스택: Klipper, Moonraker, Mainsail, Fluidd
Klipper는 범용 컴퓨터와 하나 이상의 마이크로컨트롤러를 결합하는 GPL-3.0 펌웨어입니다 [1]. 웹 서버가 되려 하지는 않습니다. Moonraker는 Klipper용 API를 노출하는 Python 3 웹 서버(Tornado 기반, GPL-3.0)로, 사용자 인터페이스는 제공하지 않으며 Unix 도메인 소켓으로 Klippy 호스트와 통신합니다 [6]. 클라이언트는 별개의 프로젝트입니다. Mainsail(GPL-3.0, 파일 관리자와 편집기, 출력 이력, 작업 대기열, 다중 웹캠, 베드 메시 시각화) [7]과 Fluidd(GPL-3.0, 데스크톱·태블릿·휴대폰에서 사용 가능, KIAUH 도우미로 설치 가능) [8]가 있습니다. Moonraker의 README는 스택을 묶어 둔 Raspberry Pi 이미지 MainsailOS와 FluiddPi를 언급합니다 [6]. Prusa는 자체 오픈 호스트 인터페이스를 갖고 있습니다. PrusaLink Web은 Prusa 프린터용 GPL-3.0 브라우저 인터페이스이며 동작이 OpenAPI 명세로 정의되어 있습니다 [9].
두 가지 호스트 스택과 플릿 계층. UI와 팜 도구는 API 서버와 통신하고, API 서버는 펌웨어와 통신합니다.
저자가 AI의 도움을 받아 직접 제작한 그림입니다.
Moonraker의 API
Moonraker는 HTTP와 웹소켓 위의 JSON-RPC(메시지 형식)로 API를 제공합니다. 파일 전송은 HTTP 전용이고, 웹소켓은 클라이언트가 실시간 이벤트를 받는 통로입니다. 성공한 HTTP 응답은 {"result": ...} 형태로 감싸집니다 [10]. 문서화된 엔드포인트로는 GET /printer/info, {"script": "G28"} 같은 JSON 본문을 쓰는 POST /printer/gcode/script, POST /printer/print/start?filename=..., POST /printer/print/pause, POST /printer/print/cancel, POST /printer/emergency_stop이 있습니다 [11]. GET /server/info는 여러 필드 중 klippy_state를 돌려주며, 값은 disconnected, startup, ready, error, shutdown 중 하나입니다 [12]. Moonraker의 기본 HTTP 포트는 7125입니다 [13].
Klipper 자신은 모든 G-code 명령을 지원하는 것이 목표가 아니며 터미널 출력은 사람이 읽기 위한 것이라고 밝힙니다. Klipper를 제어하는 소프트웨어는 콘솔 텍스트를 파싱하지 말고 API 서버를 써야 합니다 [14].
실행해 볼 수 있는 상태 조회 클라이언트
아래 스크립트는 파이썬 표준 라이브러리만 사용합니다. /server/info를 읽고, Klipper가 ready라고 보고하면 /printer/info를 읽으며, 키를 주었을 때만 X-Api-Key 헤더를 보냅니다.
import json
import sys
import urllib.request
def get(base, path, api_key=None):
req = urllib.request.Request(base + path)
if api_key:
req.add_header("X-Api-Key", api_key)
with urllib.request.urlopen(req, timeout=5) as resp:
return json.load(resp)["result"] # successful replies are wrapped in {"result": ...}
def main():
base = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:7125"
key = sys.argv[2] if len(sys.argv) > 2 else None
server = get(base, "/server/info", key)
print("klippy_state:", server["klippy_state"], "| moonraker", server["moonraker_version"])
if server["klippy_state"] == "ready":
printer = get(base, "/printer/info", key)
print("printer state:", printer["state"], "-", printer["state_message"])
main()
실행 상태: 실제 Moonraker에 대해서는 실행하지 않았습니다. Klipper 장비가 없었습니다. Moonraker 문서에 인용된 응답 형태를 돌려주는 작은 로컬 모의(mock) HTTP 서버에 대해 실행했습니다. 모의 서버는 키가 없으면 401을 돌려주었고, 키를 주면 스크립트가 klippy_state: ready | moonraker mock과 printer state: ready - Printer is ready를 출력했습니다. 이것은 클라이언트 로직과 헤더 처리를 시험한 것이지 Moonraker의 동작을 시험한 것이 아닙니다. 기계를 움직이는 것을 시도하기 전에, 먼저 이와 같은 읽기 전용 호출로 자신의 프린터에 실행해 보세요. G28(전체 축 홈)은 기계를 움직입니다.
여러 프린터: 오픈 플릿 도구
팜에는 대기열, 모든 장비를 보는 화면, 재고 관리가 필요합니다. 확인할 수 있었던 오픈 선택지는 다음과 같습니다.
| 프로젝트 | 라이선스 | 하는 일 |
|---|---|---|
| FDM Monster | AGPL-3.0 | 프린터 그리드를 갖춘 팜 플랫폼. 백엔드는 OctoPrint, Moonraker를 통한 Klipper, PrusaLink, LAN 모드의 Bambu Lab. G-code 파일을 여러 프린터에 보낼 수 있음. 2021년 OctoFarm에서 포크됨 [15] |
| OctoFarm | AGPL-3.0 | 여러 OctoPrint 인스턴스를 통합하던 원조, FDM Monster가 여기서 포크됨 [15][16] |
| Spoolman | MIT | REST API를 갖춘 자체 호스팅 필라멘트 재고 관리. Moonraker 프런트엔드와 OctoPrint와 연동 [17] |
| Obico server | AGPL-3.0 | 딥러닝 출력 실패 감지를 갖춘 자체 호스팅 서버(Docker) [18] |
Mainsail은 기능 목록에 작업 대기열을 올려 두고 있지만 [7], 그것은 장비 한 대의 대기열입니다. FDM Monster 같은 플릿 도구는 대신 한 화면에서 파일을 프린터 한 대 또는 여러 대에 보내게 해 줍니다. 이들이 얼마나 확장되는지는 평가하지 않았으므로, 여기서 "팜"은 시험된 용량이 아니라 구조를 가리킵니다.
보안
이 서비스들은 히터와 모터를 제어하므로 기계를 원격 조종하는 장치처럼 다루어야 합니다.
- 사설 네트워크에 두세요. OctoPrint의 보안 정책은 안전한 사설 네트워크에서 실행하도록 설계되었다고 밝히며, 공용 인터넷에 노출하는 것을 심각한 설정 오류로 규정합니다 [19].
- 인증하세요. 접근 제어를 끈 OctoPrint는 익명 요청에 관리자 권한을 줍니다 [3]. Moonraker의
trusted_clients옵션은 전체 API 접근을 허용할 주소를 나열하며 기본값은 아무도 신뢰하지 않는 것입니다. 문서는 도메인 이름보다 IP 범위를 쓰라고 조언하고,cors_domains = *는 클라이언트 개발자용이지 운영용이 아니라고 설명하며,force_logins는 사용자가 한 명이라도 있으면 로그인을 요구합니다 [13]. - 원격 접속에는 리버스 프록시를 쓰세요. Moonraker 문서는 프록시 뒤에서 실행하는 것을 권장 구성이라고 부릅니다 [13]. 특정 원격 접속 제품을 권하지는 않습니다. 자신의 네트워크로 들어가는 VPN은 서비스를 노출하지 않아도 되게 해 줍니다.
- 카메라를 기억하세요. 호스트가 노출되면 웹캠 영상이 작업 공간 밖으로 나갑니다.
왜 중요한가
호스트는 "프린터가 있다"가 "네트워크에 연결된 기계가 있다"로 바뀌는 곳입니다. 또한 오픈소스 선택이 가장 크게 갈리는 계층이기도 합니다. API가 얼마나 잘 문서화되어 있는지, 접근을 어떻게 제어하는지, 한 사람이 프린터 몇 대를 돌볼 수 있는지가 달라집니다.
실제 현장에서는
프린터 한 대라면 주된 선택은 OctoPrint 대 Klipper 스택(Mainsail 또는 Fluidd)이고, 선택은 대개 고른 펌웨어를 따릅니다. 몇 대 이상이면 플릿 도구가 빠진 대기열과 재고 관리를 더해 줍니다.
핵심 용어
- 호스트(Host) — 프린터 옆에서 웹 인터페이스, 파일 저장, 작업 제어를 실행하는 작은 컴퓨터.
- REST API — URL과 HTTP 메서드(GET, POST)가 자원과 동작을 가리키는 웹 인터페이스.
- JSON-RPC — 클라이언트가 메서드 이름과 매개변수를 보내는 메시지 형식으로, 흔히 웹소켓 위에서 쓰임.
- API 키(API key) — 클라이언트가 API를 써도 된다는 것을 증명하려고 요청마다 보내는 비밀 문자열.
- Moonraker — HTTP와 웹소켓 API로 Klipper의 기능을 노출하는 Python 웹 서버.
- Mainsail / Fluidd — Moonraker와 통신하는 Klipper용 오픈 웹 인터페이스.
- 작업 대기열(Job queue) — 출력을 기다리는 파일의 순서 있는 목록.
- 프린트 팜(Print farm) — 공유 화면과 대기열로 함께 관리하는 여러 대의 프린터.
- 리버스 프록시(Reverse proxy) — 요청을 내부 서비스로 전달하며 흔히 암호화와 로그인을 더하는 앞단 웹 서버.
다음 이야기
이 장의 모든 도구는 파일을 옮깁니다. 다음 장에서는 그 파일 자체를 살펴봅니다. 파일 형식과 오픈 데이터로 이어집니다.