제공된 소스 코드와 문서에서 확인되는 웹 콘솔 터널링(Console Tunneling) 관련 주요 장애 원인과 패치 내역은 다음과 같이 5가지로 분석됩니다. 1. 에이전트(mihosrcd) 스레드 안전성 위반으로 인한 크래시 (SEGV) 원인: v8.6.0 버전의 tunnel.c 에서 터널 읽기 스레드가 libwebsockets API인 lws_callback_on_writable(g_wsi) 를 직접 호출했기 때문입니다. libwebsockets 라이브러리는 스레드 안전(thread-safe)하지 않으므로 서비스 스레드 밖에서 내부 객체( wsi )를 조작하면 자료구조가 깨지며, 이로 인해 운영 노드가 약 36초마다 세그멘테이션 폴트(SEGV)를 내며 죽는 현상이 발생했습니다. 해결 상태: v8.7.0 업데이트를 통해 읽기 스레드는 큐와 뮤텍스만 다루도록 격리되었으며, 다른 스레드에서 호출 가능한 유일한 API인 lws_cancel_service() 를 사용하여 서비스 스레드를 깨워 작업을 위임하는 방식으로 재작성되었습니다. 2. 터널 세션 고갈 및 슬롯 잠김 (최대 8개 상한 도달) 원인: tunnel.open 명령으로 티켓이 발급되어 세션이 TS_TICKETED 상태가 된 후, 웹 서버 측의 터널 개통(TUNNEL_OPEN)이 실패하면 세션이 회수되지 않고 그대로 남는 버그가 있었습니다. 동시 터널 세션 상한( TUNNEL_MAX_SESSIONS )이 8개이므로, 이러한 개통 실패가 8번 누적되면 슬롯이 전부 잠겨 더 이상 콘솔을 열 수 없게 됩니다. 해결 상태: v8.7.0에서 티켓의 유효 기간(60초, TUNNEL_TICKET_TTL )이 지나면 만료된 티켓을 우선적으로 강제 회수( sess_free_locked )하여 슬롯을 반환하는 방어 로직이 추가되었습니다. 3. 서버 설정의 인증 토큰 불일치 원인: 서버 설정 파일( config.env )에서 mihosocket을 위한 MS_RELAY_TOKEN 값과 miho_relay를 위한 MR_SERVICE_TOKEN 값이 정확히 동일하지 않으면, 웹 콘솔 터널이 릴레이 서버에 접근할 때 인증에 실패하게 됩니다. 4. HAProxy 타임아웃 설정에 의한 세션 단절 원인: 릴레이 서버 앞단에 있는 HAProxy의 기본 타임아웃 설정이 콘솔 터널의 요구사항과 맞지 않기 때문입니다. 접속 시 지연: 웹 서버가 WebSocket 업그레이드를 요청할 때 에이전트의 터널 개통 응답( tunnel.open )을 최대 15초까지 기다릴 수 있으므로, HAProxy의 timeout server 가 짧으면 연결이 성립되기 전에 끊어집니다. VNC 작업 중 끊김: VNC 세션은 장시간 유지되어야 하지만, 화면 조작 없이 조용할 때 HAProxy의 기본 timeout tunnel 인 3600초(1시간)가 지나면 세션이 예고 없이 절단됩니다. 조치 사항: haproxy-console-patch.sh 를 통해 timeout server 를 30s에서 120s로, timeout tunnel 을 1시간에서 24시간(86400s)으로 연장 적용해야 합니다. 5. PVE 호스트 IP 라우팅 불가 (ERR_ADDRESS_UNREACHABLE) 원인: Proxmox(PVE) 환경에서 에이전트가 /etc/pve/.members 에 기록된 클러스터 내부 통신용 LAN IP(예: 11.11.0.101)를 콘솔 URL 주소로 보고하는 경우가 있습니다. 브라우저가 공유기 외부에 위치할 경우 해당 내부 IP로 접근할 수 없어 라우팅 에러가 발생합니다. 해결 상태: v8.6.2부터 에이전트는 릴레이 연결에 실제 사용된 소켓의 로컬 주소(예: WireGuard 망 IP)를 getsockname() 으로 추출하여 보고하도록 수정되었습니다. 웹 UI에서도 라우팅이 불가능한 경우를 대비하여 MIHO_CONSOLE_BASE 환경 변수를 통해 콘솔 주소를 수동으로 덮어쓸 수 있는 옵션을 제공합니다.