자동 발견 (Auto-Discovery)¶

Backend.AI GO는 mDNS(Multicast DNS)를 사용해 로컬 네트워크에서 인스턴스를 공지하고 발견하는데, macOS에서는 Bonjour라고 부르는 방식입니다. 승인 없이 연결 허용 (같은 네트워크)을 활성화한 컴퓨터는 자신을 공지하고, 같은 네트워크의 다른 인스턴스는 IP 주소나 연결 키 없이 해당 컴퓨터를 찾아 연결할 수 있습니다.

mDNS 발견 작동 방식¶

mDNS는 중앙 DNS 서버 없이 멀티캐스트 주소(224.0.0.251 IPv4, ff02::fb IPv6)를 사용하여 UDP 포트 5353으로 동작하는 제로 구성 프로토콜입니다. 노드는 멀티캐스트 그룹으로 공지를 보내고, 동일 서브넷의 모든 다른 노드가 이를 수신합니다.

Backend.AI GO는 _aigo._tcp.local. 서비스 유형으로 등록됩니다. 네트워크에서 이 유형을 검색하는 모든 인스턴스가 공지를 확인할 수 있습니다.

광고 및 발견 흐름¶

노드 A (광고자)                      노드 B (발견자)
        |                                    |
        |--- mDNS 공지 ----------------->    |  (UDP 5353 멀티캐스트)
        |    _aigo._tcp.local.               |
        |    TXT: name, version,             |
        |         fingerprint, port,         |
        |         engines, models,           |
        |         accelerator                |
        |                                    |
        |                  [노드 B가 A 발견] |
        |                                    |
        |<-- 약 20-30초마다 재공지 ----------| (데몬이 활성 상태 유지)
        |                                    |
        |--- 정상 종료 공지 --------------->  | (ServiceRemoved 이벤트)
        |    (종료 시)                        |

각 인스턴스는 발견 리스너도 실행하므로, 동일한 노드가 광고와 피어 발견을 동시에 수행할 수 있습니다.

TXT 레코드 형식¶

광고 시 Backend.AI GO는 mDNS TXT 레코드에 다음 데이터를 포함합니다:

설치된 엔진이 없거나 엔진 관리자를 사용할 수 없는 경우 engines 및 models 필드는 생략됩니다. 가속기가 감지되지 않으면 accelerator 필드도 생략됩니다.

기능 데이터는 다음 경우에 자동으로 업데이트됩니다:

• 엔진 설치 또는 제거 시 (engines-changed 이벤트 발생).
• 모델 라이브러리 변경 시 (models-updated 이벤트 발생).

mDNS 광고 설정¶

이 컴퓨터에서 광고 활성화¶

1. Backend.AI GO에서 설정을 열고 노드 탭을 선택합니다.
2. 이 컴퓨터 공유하기를 열어 다른 컴퓨터와 공유를 활성화합니다.
3. 이 컴퓨터에서 이름을 입력합니다. 광고에는 이름이 필요하고, 다른 컴퓨터의 목록에도 입력한 이름이 표시됩니다.
4. 연결 방법에서 승인 없이 연결 허용 (같은 네트워크)을 활성화합니다.

활성화하면 이 인스턴스는 20~30초마다 자신을 공지하고, 같은 서브넷의 다른 Backend.AI GO 인스턴스는 발견 목록에서 이 컴퓨터를 확인할 수 있습니다. 연결 방법은 다른 컴퓨터와 공유가 활성화된 동안에만 표시되는데, 공유를 비활성화하면 스위치 설정은 그대로 둔 채 공지만 멈추고 공유를 다시 활성화하면 공지도 다시 시작됩니다.

네트워크에서 컴퓨터 발견¶

1. 설정 > 노드 > 다른 컴퓨터 연결하기를 엽니다. 화면이 열려 있는 동안 검색이 실행되고, 화면을 벗어나면 멈춥니다.
2. 노드 추가 아래의 네트워크에 있는 컴퓨터에 지금까지 발견된 컴퓨터가 표시되며, 컴퓨터가 나타나거나 사라질 때마다 목록이 갱신됩니다.
3. 목록에서 추가할 컴퓨터의 노드 추가를 클릭합니다. 승인 없는 연결을 허용한 컴퓨터만 목록에 나타나므로, 연결 키 없이 바로 추가됩니다.

목록의 각 컴퓨터에는 다음 정보가 표시됩니다.

• 노드 이름 및 IP 주소
• 소프트웨어 버전
• 설치된 추론 엔진 (예: llama-cpp, mlx)
• 로컬에서 사용 가능한 모델 수
• 하드웨어 가속기 유형 (예: metal, cuda, rocm, cpu)

승인과 연결 키¶

다른 컴퓨터가 연결할 때 이 컴퓨터에서 무엇이 필요한지는 승인 없이 연결 허용 (같은 네트워크) 스위치가 정합니다. 스위치가 활성화되어 있으면 같은 네트워크의 어떤 컴퓨터든 발견 엔드포인트에서 연결 키를 받아 등록할 수 있고, 이 컴퓨터에는 연결을 승인하라는 요청이 나타나지 않습니다. 엔드포인트는 키를 내주는 횟수만 제한하고 다른 확인은 하지 않으므로, 집이나 사무실처럼 신뢰할 수 있는 네트워크에서만 활성화하는 것을 권장합니다.

스위치는 다른 컴퓨터와 공유가 활성화된 동안에만 적용됩니다. 공유가 비활성화되어 있으면 스위치 설정과 관계없이 이 컴퓨터는 자신을 공지하지 않고 연결 키도 내주지 않습니다.

스위치가 비활성화되어 있어도 다른 컴퓨터가 연결할 수는 있지만, 연결 방법 > 연결 키로 연결에서 만든 연결 키가 있어야 합니다(수동 등록 참고). 키는 한 번만 사용되고 유효 기간에서 정한 시간(5분~1시간)이 지나면 만료됩니다. 어느 방법으로든 연결한 컴퓨터는 이 컴퓨터를 사용하는 컴퓨터에 표시되어 여기서 제거할 수 있는데, 제거된 컴퓨터가 이 컴퓨터를 다시 사용하려면 다시 등록해야 합니다.

자기 노드 필터링¶

각 노드는 첫 실행 시 고유한 핑거프린트를 생성합니다. 발견 서비스는 이 핑거프린트를 사용하여 자신의 mDNS 공지를 필터링합니다. 광고 중이더라도 자신의 노드는 발견된 노드 목록에 나타나지 않습니다.

오래된 노드 감지¶

노드가 종료 공지 없이 갑자기 종료되면, 발견 서비스는 해당 노드를 오래된 것으로 표시하고 자동으로 제거합니다.

• 오래된 노드 임계값: 90초 이내에 재공지되지 않은 노드는 오래된 것으로 간주됩니다. mDNS 데몬은 일반적으로 20~30초마다 재공지하므로, 90초는 노드를 오프라인으로 판단하기 전에 세 번의 공지를 허용합니다.
• 주기적 정리: 30초마다 발견 서비스는 노드 레지스트리에서 오래된 항목을 제거합니다.
• 읽기 시점 필터링: get_discovered_nodes()는 매 호출 시 오래된 노드를 필터링하여, 예약된 정리 실행 사이에도 추가적인 안전 장치를 제공합니다.

노드가 다시 온라인 상태가 되면 재공지하며 즉시 피어 목록에 다시 나타납니다.

발견 문제 해결¶

노드가 나타나지 않는 경우¶

• 동일 서브넷 필요: mDNS 멀티캐스트는 라우터 경계를 넘지 않습니다. 두 노드 모두 동일한 Layer 2 네트워크 세그먼트에 있어야 합니다. VLAN이나 라우팅된 서브넷은 발견을 차단합니다.
• 방화벽 규칙: 참여하는 모든 컴퓨터에서 멀티캐스트 트래픽에 대해 UDP 포트 5353이 열려 있는지 확인하세요. 많은 운영 체제 방화벽이 신뢰할 수 없는 네트워크 프로필에서 기본적으로 멀티캐스트를 차단합니다.
• mDNS 광고가 비활성화된 경우: 발견하려는 컴퓨터의 설정 > 노드 > 이 컴퓨터 공유하기에서 다른 컴퓨터와 공유와 승인 없이 연결 허용 (같은 네트워크)이 모두 활성화되어 있는지 확인하세요.
• 이름이 설정되지 않은 경우: 이 컴퓨터에 이름이 없으면 승인 없이 연결 허용 (같은 네트워크) 스위치를 활성화할 수 없습니다.
• 로컬 네트워크 권한이 꺼진 경우 (macOS): 찾는 컴퓨터나 찾으려는 컴퓨터가 Backend.AI GO의 로컬 네트워크 접근을 허용하지 않은 경우입니다. macOS의 로컬 네트워크 권한을 참고하세요.

macOS의 로컬 네트워크 권한¶

macOS 15부터는 앱이 같은 네트워크의 다른 컴퓨터에 접근하기 전에 사용자의 허락을 받아야 합니다. Backend.AI GO는 설정 > 노드를 열거나, 발견을 시작하거나, 공유를 켜거나, 컴퓨터를 추가할 때 이 권한을 확인하는데, 아직 정하지 않았다면 이때 macOS가 허용 여부를 묻는 창을 띄웁니다. 권한이 꺼져 있으면 노드 설정 맨 위에 로컬 네트워크 권한이 꺼져 있습니다 안내가 나타나고, 다른 컴퓨터로의 연결은 주소에 도달할 수 없음으로 실패하죠.

안내의 시스템 설정 열기를 누르거나 시스템 설정 > 개인정보 보호 및 보안 > 로컬 네트워크를 직접 열어 Backend.AI GO를 켜면 되고, 앱으로 돌아오면 안내가 사라집니다. macOS는 한 번 거절한 결정을 업데이트한 뒤에도 유지하고 다시 묻지 않으므로, 이 스위치가 권한을 바꾸는 유일한 방법입니다. 목록에 Backend.AI GO가 없다면 앱을 종료했다가 다시 실행해 보세요. 앱은 실행될 때 macOS에 자신을 다시 등록하므로, 다음에 네트워크에 접근할 때 허용 창이나 목록 항목이 나타납니다. 터미널에서 실행한 프로그램은 항상 허용되기 때문에 개발 빌드에서는 이 창을 볼 수 없습니다.

노드가 예상치 않게 사라지는 경우¶

• mDNS 공지가 90초 이내에 수신되지 않으면 노드가 피어 목록에서 사라집니다. 이는 다음과 같은 경우에 발생할 수 있습니다:
• 광고하는 노드의 방화벽이 멀티캐스트 발신 패킷을 차단하는 경우.
• 노드의 네트워크 인터페이스가 변경되는 경우 (예: Wi-Fi에서 이더넷으로 전환).
• 시스템이 절전 모드로 전환되어 mDNS 데몬이 일시정지되는 경우.

플랫폼별 참고 사항¶

연결 후 네트워크 노드 모델 발견¶

두 노드가 연결되면 Backend.AI GO는 카탈로그 교환을 수행합니다:

1. 핸드셰이크: 연결 시 네트워크 노드가 활성 백엔드(실행 중인 모델 및 서비스) 목록을 전송합니다.
2. 동적 업데이트: 네트워크 노드에서 모델이 실행되거나 중지되면 로컬 인스턴스가 다음 새로고침 시 알림을 받습니다.
3. 모델 선택기: 네트워크 노드의 모델은 채팅 인터페이스의 모델 선택기에서 노드 이름별로 그룹화되어 나타납니다.

로컬 모델 발견¶

로컬 컴퓨터에서 Backend.AI GO는 파일 시스템과 활성 프로세스도 모니터링합니다:

• 폴더 모니터링: models/ 디렉토리에 모델을 다운로드하면 Backend.AI GO가 파일 유형(GGUF, safetensors)을 감지하고 적절한 실행기(llama.cpp, MLX)를 결정합니다.
• 프로세스 바인딩: 모델이 실행되면 로컬 라우터에 등록되며, 라우터는 해당 기능을 프론트엔드 UI에 노출합니다.