2nd/10_Wiki/Topics/Comfyui/위키 Routes - ComfyUI 2026-05-20.md

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

id	title	category	status	verification_status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	created_at	updated_at	review_reason	merge_history	tags	raw_sources	applied_in	github_commit
routes---comfyui	Routes - ComfyUI	10_Wiki/Topics	draft	conceptual				B	1.0	2026-05-20	2026-05-20			web wikify	https://docs.comfy.org/development/comfyui-server/comms_routes

Routes - ComfyUI

🎯 한 줄 통찰 (One-line insight)

ComfyUI 서버의 Routes는 클라이언트와 서버 간의 데이터 교환, 작업 큐 관리, 실시간 상태 업데이트를 위한 HTTP 메서드 및 WebSocket 엔드포인트의 집합체이다.

🧠 핵심 개념 (Core concepts)

• Core API Routes: 서버의 기능을 수행하기 위해 정의된 다양한 GET, POST 메서드들의 모음으로, 모델 관리, 이미지 업로드, 시스템 정보 조회 등을 포함한다.
• WebSocket Communication: 클라이언트와 서버 간의 양방향 실동기화를 지원하며, 실행 진행 상황 및 노드 상태를 실시간으로 전달하는 통로이다.
• Custom Routes: 개발자가 aiohttp 프레임워크를 사용하여 서버에 새로운 경로를 추가하고 클라이언트와의 메시지 송수신 기능을 확장할 수 있는 메커니즘이다.
• Execution Queue Management: prompt 제출, 큐 상태 조회, 실행 중단 및 히스토리 관리 등 작업 흐름의 제어를 담당한다.

🧩 추출된 패턴 (Extracted patterns)

• Request/Response Pattern: 특정 경로(예: /prompt)로 데이터를 제출하면 서버가 검증 후 실행 큐에 추가하고 결과를 반환하는 구조를 가진다.
• Real-time Update Pattern: WebSocket을 통해 status, progress, executed 등 다양한 타입의 JSON 메시지를 클라이언트에 브리캐스팅한다.
• Extensibility Pattern: @routes.post와 같은 데코레이터를 활용하여 기존 서버 구조를 변경하지 않고 새로운 기능을 추가할 수 있는 확장성을 제공한다.

📖 세부 내용 (Details)

1. Core API Routes (Built-in routes)

server.py에 정의된 주요 경로들의 기능은 다음과 같다.

path	method	purpose
/	get	load the comfy webpage
/ws	websocket	WebSocket endpoint for real-time communication with the server
/embeddings	get	retrieve a list of the names of embeddings available
/extensions	get	retrieve a list of the extensions registering a WEB_DIRECTORY
/features	get	retrieve server features and capabilities
/models	get	retrieve a list of available model types
/models/{folder}	get	retrieve models in a specific folder
/workflow_templates	get	retrieve a map of custom node modules and associated template workflows
/upload/image	post	upload an image
/upload/mask	post	upload a mask
/view	get	view an image (includes various options)
/view_metadata/	get	retrieve metadata for a model
/system_stats	get	retrieve information about the system (python version, devices, vram etc)
/prompt	get	retrieve current queue status and execution information
/prompt	post	submit a prompt to the queue
/object_info	get	retrieve details of all node types
/object_info/{node_class}	get	retrieve details of one node type
/history	get	retrieve the queue history
/history/{prompt_id}	get	retrieve the queue history for a specific prompt
/history	post	clear history or delete history item
/queue	get	retrieve the current state of the execution queue
/queue	post	manage queue operations (clear pending/running)
/interrupt	post	stop the current workflow execution
/free	post	free memory by unloading specified models
/userdata	get	list user data files in a specified directory
/v2/userdata	get	enhanced version that lists files and directories in structured format
/userdata/{file}	get	retrieve a specific user data file
/userdata/{file}	post	upload or update a user data file
/userdata/{file}	delete	delete a specific user data file
/userdata/{file}/move/{dest}	post	move or rename a user data file
/users	get	get user information
/users	post	create a new user (multi-user mode only)

2. WebSocket Communication

WebSocket 엔드포인트인 /ws는 실시간 양방향 통신을 위해 사용되며, 다음과 같은 정보를 전달한다.

• 주요 용도: 실행 진행 상황 업데이트 수신, 노드 실행 상태 실시간 확인, 에러 메시지 및 디버깅 정보 수신, 큐 상태 변경 시 라이브 업데이트.
• JSON 메시지 타입:
  • status: 전체 시스템 상태 업데이트
  • execution_start: 프롬프트 실행 시작 시점
  • execution_cached: 캐시된 결과 사용 시
  • executing: 노드 실행 중 업데이트
  • progress: 장기 실행 작업의 진행률 업데이트
  • executed: 노드 실행 완료 시

3. Custom Routes Implementation

클라이언트에서 서버로 메시지를 보내기 위해 새로운 경로를 정의하는 방법이다.

• 서버 측 구현: aiohttp 프레임워크를 활용하며, @routes.post('/path') 데코레이터를 사용한다. 함수 내부에서는 request.post()를 통해 데이터를 수신할 수 있다.
• 클라이언트 측 호출: FormData 객체를 사용하여 api.fetchApi를 통해 새로운 경로에 요청을 보낼 수 있다.

⚖️ 모의 및 업데이트 (Contradictions & updates)

본문 내에서 상충되는 정보는 발견되지 않았습니다.

🛠️ 적용 사례 (Applied in summary)

• Custom Node 개발: 서버의 기능을 확장하기 위해 @routes.post를 사용하여 새로운 경로를 생성하고, FormData를 통해 데이터를 전송하는 예시가 제시됨.

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual
• 출처 신뢰도: B (Primary Source — 웹사이트 본문 직접 추출)
• 중복 검사 결과: 신규 생성 (New discovery)

🔗 관련 문서 링크 (Related document links)

• ComfyUI Server: 서버의 전반적인 구조와 역할을 이해하기 위한 핵심 개념입니다.
• WebSocket: 실시간 데이터 스트리밍 및 양방향 통신의 기술적 기반입니다.
• aiohttp: 커스텀 라우트를 구현할 때 사용하는 프레임워크입니다.
• PromptExecutor: 실행 큐를 정의하고 관리하는 클래스입니다.

📝 변경 이履歴 (Change history)

• 2026-05-20: Astra /wikify 로 https://docs.comfy.org/development/comfyui-server/comms_routes 본문에서 초안 생성.