Meshyface

Meshyface는 단일 Python 서비스로 실행되며 HTTP를 통해 단일 페이지 웹 UI를 제공하는 채팅 우선 Meshtastic 대시보드입니다.

현재 앱 구성

현재 UI는 다음을 제공합니다:

• 채팅 및 직접 피어 대화
• 지도, 개요, 링크, 경로, 센서, Top 10 순위, 노드 세부 정보 및 요청 시 기록을 위한 네트워크 워크스페이스
• 실시간 패킷/로그 출력을 위한 콘솔 워크스페이스
• 파일 전송이 활성화된 경우 Games 및 Files 탭이 있는 앱 워크스페이스
• 라디오, 장치, 연결, 위치, 채널, 티커, 목록, 모양 및 정보 창이 있는 설정 워크스페이스
• SQLite 기반 기록, 검색, 롤업, 테마 영속화 및 사용자 지정 원격 측정 규칙 영속화

콘솔 워크스페이스

콘솔 워크스페이스는 패킷 트래픽, 기록 검색 및 메시 유틸리티 명령을 위한 터미널 스타일 제어 인터페이스입니다.

• 명령 이름을 입력하면 자동 완성 제안이 열립니다. Tab 또는 Enter를 사용하여 수락하고, ArrowRight를 사용하여 고스트 접미사를 수락하며, ArrowUp / ArrowDown을 사용하여 팝업을 탐색합니다.
• 노드 대상을 사용하는 명령은 이름, ID, 이모지, 태그, 상태, 홉, GPS, 마지막 수신 상태, 포트 및 노드 번호가 포함된 풍부한 노드 제안을 표시합니다. 일반 텍스트는 노드 이름과 태그로 좁히고 !는 노드 ID로 좁힙니다.
• live는 Ctrl+C 또는 q를 누를 때까지 패킷 트래픽을 스트리밍합니다. live grep <text>, live rg <text>, live filter=<text> 또는 단독 live <text>를 사용하여 일치하는 실시간 패킷 그룹만 스트리밍합니다. 레이어 및 상세 수준 필터는 계속 적용됩니다. 예: live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> 및 rg <text>는 컨텍스트 창, 제한, 패킷/채팅 소스 필터 및 요약/패킷 범위 필터를 사용하여 보존된 패킷/채팅 기록을 검색합니다.
• /search <text>는 보존된 기록 검색을 시작하지 않고 프롬프트에서 표시 중인 콘솔 출력을 필터링합니다.

스크린샷

실시간 네트워크 지도

노드 위치, 링크, 공통 경로, 클러스터 및 신호 히트맵이 포함된 지도 보기입니다.

네트워크 개요

노드 수, 온라인 상태, 새 노드 및 위치 보고서를 위한 기록 보기입니다.

링크 토폴로지

선택한 루트 노드에서 관찰된 링크를 표시하는 토폴로지 보기입니다.

경로 추적

소스, 대상, 인접 링크 및 홉별 패킷 세부 정보를 위한 추적 보기입니다.

센서 기록

여러 노드의 센서 기록을 비교하는 원격 측정 차트입니다.

상태 카드

라디오 활동, 노드 수, 패킷, 링크, 배터리 및 채널 사용량을 위한 상단 카드입니다.

테마 사용자 지정

테마는 사용자 지정 색상, 그라데이션, 투명도, 블러, 글꼴, 파티클 또는 라이브 지도 배경으로 전체 대시보드를 재구성할 수 있습니다. 이 예제 팔레트는 사용자 지정 테마입니다. 미리 보기를 선택하면 전체 해상도 스크린샷이 열립니다.

Signal Green	Neon Magenta	Aurora Relay

공유 노드 모양

Meshyface 노드는 노드 테마 레시피와 선택적 고스트 또는 워터마크가 포함된 컴팩트한 모양 패킷을 공유할 수 있습니다. Settings > Appearance > Node Appearance에서 노드를 구성하고 미리 본 다음, Share node appearance를 활성화하고 Broadcast appearance를 사용하여 게시하십시오.

• 모양 패킷은 구성된 프로필 전송 채널을 사용하고 라디오의 홉 제한 설정을 상속합니다. Meshyface는 별도의 홉 제한을 부과하지 않습니다.
• 수신된 모양은 수신 대시보드의 자체 테마를 대체하지 않고 채팅, 명단, 노드 세부 정보, 지도, 그래프, 센서 및 티커에서 노드 ID를 스타일링할 수 있습니다.
• Share node appearance를 끄면 이 기능의 양쪽 모두 비활성화됩니다. 브로드캐스트가 중지되고 수신 모양 페이로드가 디코딩, 캐시 또는 저장되기 전에 프로필 수신 경로를 우회합니다. 캐시된 공유 모양은 지워지며 수신된 모양은 렌더링되지 않습니다.
• 기록이 활성화되면 수신된 프로필과 로컬 공유 기본 설정이 기록 SQLite 데이터베이스에 저장됩니다.
• 공유 모양은 외관상 메타데이터입니다. 수신된 모양은 라디오 설정, 채널 또는 대시보드의 저장된 패키지 테마를 변경하지 않습니다.

시스템 아키텍처

flowchart LR
  Browser["Browser<br/>single-page UI"]
  CDN["Vendored browser assets<br/>Leaflet + leaflet.heat + particles.js"]
  Tiles["Basemap provider<br/>OpenStreetMap tile service"]
  Server["ThreadingHTTPServer<br/>HTML shell + JSON API"]
  Assets["Python template assembly<br/>meshdash/html* + meshdash/assets/*"]
  State["State loaders<br/>live snapshot + history readers"]
  Services["Write services<br/>chat, settings, tools, games, optional files"]
  Tracker["DashboardTracker<br/>live receive path + in-memory buffers"]
  History["HistoryStore / SQLite (WAL)<br/>chat, packets, rollups, settings"]
  Radio["Meshtastic interface<br/>serial or TCP"]
  Mesh["Meshtastic radio / mesh"]
  Atlas["Bundled offline atlas<br/>reference basemap fallback"]

  Browser -->|GET /| Server
  Browser -->|GET /api/*| Server
  Browser -->|POST write APIs| Server
  Browser --> CDN
  Browser --> Tiles
  Browser -->|fallback basemap data| Atlas
  Server --> Assets
  Server --> State
  Server --> Services
  State <--> Tracker
  State <--> History
  Services <--> History
  Services <--> Radio
  Radio <--> Mesh
  Radio -->|receive callbacks| Tracker

설치

사전 요구 사항 및 종속성부터 시작한 후 설치 경로 중 하나를 선택하십시오:

• 수동 포그라운드 실행: 아무 위치에나 클론하고 대시보드를 직접 실행합니다.
• 권장 systemd 서비스: 지속적으로 GitHub에서 업데이트할 수 있는 호스트를 위해 /opt/meshyface에 클론합니다.
• Docker: 영구 상태를 위해 /data를 마운트한 컨테이너에서 동일한 앱 진입점을 실행합니다.
• 워크스테이션 푸시 배포: 로컬 체크아웃을 SSH를 통해 대상 호스트에 복사합니다.
• Proxmox 런타임 토폴로지: VM/LXC 설치를 위해 TCP 또는 USB 라디오 배치를 선택합니다.
• 오프라인 지도 팩: 에어갭 또는 저연결성 대시보드를 위한 상세한 로컬 지도 데이터를 추가합니다.

데이터 및 저장

공유 기록 데이터베이스

--history-db는 최종 온디스크 SQLite 파일 이름입니다. 대시보드는 더 이상 연결된 라디오 접미사를 추가하지 않으므로 대시보드에 연결된 모든 라디오는 동일한 저장된 패킷, 채팅, 노드 및 롤업 기록에 기여합니다.

기록 모드

• 기본 모드는 채팅, 패킷, 연결 이벤트, 노드 분석, 잘못된 형식의 텍스트 레코드, 환경 메트릭 및 요약 롤업을 SQLite에 저장합니다.
• --no-history는 영구 저장소를 비활성화하고 라이브 인메모리 버퍼만 유지합니다.
• 기록이 활성화된 경우 대시보드가 실행되는 동안 요약 롤업도 백그라운드에서 샘플링됩니다.

테마 및 로컬 설정

• 테마 사전 설정 선택은 기본적으로 mesh_dashboard_theme_settings.json에 저장되거나 --theme-settings-file로 제공된 파일에 저장됩니다.
• 사용자 지정 원격 측정 규칙은 기록 SQLite 데이터베이스에 저장됩니다.

유지 관리 명령

로컬 대시보드 데이터를 검사하거나 복구하는 운영 명령은 docs/maintenance.md에 문서화되어 있습니다.

링크 보기 의미

Links 하위 보기는 패킷 경로 재생이 아닌 토폴로지 보기입니다.

• History 모드는 SQLite에 저장된 링크 기록을 사용합니다.
• Live 모드는 현재 세션의 링크 관찰 결과만 사용합니다.
• 번호가 매겨진 링은 관찰된 링크 그래프에 대한 너비 우선 탐색을 사용하여 현재 루트로부터의 최단 그래프 거리를 표시합니다.
• 해당 링 번호는 실제 Meshtastic 전달 홉이 아니며 실시간 패킷 추적이 아닙니다.
• 패킷 홉 메타데이터는 사용 가능한 경우 노드 또는 엣지 세부 정보에 패킷 홉 값으로 별도로 계속 표시됩니다.

현재 루트는 그래프의 중심이 되는 노드입니다. 다른 노드를 선택하면 루트가 변경되고 해당 노드부터 번호가 매겨진 거리 링이 다시 계산됩니다.

구성 참조

연결 및 전송

• --mesh-host <ip-or-dns>: TCP 라디오 호스트
• --mesh-tcp-port <port>: TCP 라디오 포트, 기본값 4403
• --mesh-port <path>: 직렬 장치 경로
• --default-gateway-host <host>: --mesh-host가 제공되지 않고 직렬이 여전히 기본 경로에 있는 경우 대체 TCP 호스트
• --default-gateway-port <port>: --default-gateway-host의 대체 TCP 포트
• --no-default-gateway: --mesh-host가 명시적으로 설정되지 않은 한 직렬을 강제합니다

관련 환경 변수:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT: 기본 직렬 경로용

HTTP, UI 및 보안

• --http-host <host>: 바인드 호스트, 기본값 0.0.0.0
• --http-port <port>: 바인드 포트, 기본값 8877
• --refresh-ms <ms>: 브라우저 폴링 간격, 기본값 3000
• --packet-limit <n>: 최근 실시간 패킷 버퍼 크기, 기본값 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: 원시 JSON 패널에서 개인 키/비밀번호/PSK를 표시합니다
• --debug-mode / --no-debug-mode: 고급 네트워크 진단과 같은 디버그 전용 대시보드 기능을 노출합니다
• --private-mode / : 공개 채팅 조각을 제거하고 선택된 공개 엔드포인트를 차단합니다

관련 환경 변수:

• MESH_DASH_PRIVATE_MODE
• MESH_DASH_API_TOKEN
• MESH_DASH_GAMES_ENABLE
• MESH_DASH_VERSION
• MESH_DASH_GIT_COMMIT
• MESH_DASH_PR_NUMBER

런타임 ID는 12자리 git 커밋 뒤에 선택적 풀 리퀘스트 번호가 붙는 형식입니다(예: abc123456789 · PR #43). 소프트웨어 패널은 패키지 버전 대신 이 단일 리비전을 표시합니다. GitHub 병합/스쿼시 커밋 제목은 자동으로 감지됩니다. 병합되지 않은 미리 보기 배포는 MESH_DASH_PR_NUMBER를 명시적으로 설정할 수 있습니다.

/api/revision은 표준 ID 엔드포인트입니다. 해당 revision 및 build_ref 필드는 런타임 리비전을 보고하는 반면, commit 및 pr_number는 구조화된 필드로 계속 사용할 수 있습니다. /api/version은 레거시 엔드포인트로 유지되며 해당 version 필드는 릴리스/패키지 메타데이터를 유지합니다. MESH_DASH_VERSION도 명시적 릴리스 패키징 전용으로 예약되며 대시보드에 표시되지 않습니다.

파일 전송

• --file-transfer-enable: Files 앱을 활성화합니다. --accept-file-transfer-traffic-disclaimer가 필요합니다
• --file-transfer-auto-accept: 브라우저 확인 없이 직접 수신 전송을 수락합니다
• --file-transfer-max-bytes <bytes>: 파일당 제한, 기본값 65536, 1024-524288 범위로 제한됩니다

전송은 개인 포트 258에서 베타 MF_FILE_V2 프로토콜을 사용하며 이전 텍스트 메시지 전송과 호환되지 않습니다. 대상에 사용 가능한 감지된 홉 수가 있으면 Meshyface는 해당 수에 1을 더해 사용하며, 구성된 라디오 홉 제한이 상한입니다. 1시간이 지난 홉 데이터는 구성된 제한으로 대체됩니다. Files 앱은 선택된 제한과 해당 출처를 표시합니다.

관련 환경 변수:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

기록 및 분석

• --history-db <path>: 기본 SQLite DB 경로
• --history-max-rows <n>: 기본값 200000
• --history-retention-days <days>: 기본값 30, 0을 사용하면 기간 정리를 비활성화합니다
• --history-event-max-rows <n>: 추가 전용 패킷 이벤트 상한, 기본값 200000
• --history-event-retention-days <days>: 기본값 30
• --history-rollup-retention-days <days>: 기본값 365
• --no-history: 메모리 전용 모드
• --seed-from-node-db: 연결된 라디오 NodeDB에서 라이브 트래커를 부트스트랩합니다

관련 환경 변수:

• MESH_DASH_HISTORY_DB

테마

• --theme-presets <json>: 선택적 사용자 지정 테마 사전 설정 파일
• --theme-preset <name>: 선택된 사전 설정 이름
• --theme-settings-file <json>: 저장된 런타임 테마 선택 파일

기본 제공 사전 설정:

• default(안전한 Meshyface 블루, 파티클 비활성화)
• custom(파티클 및 배경 효과가 활성화된 쇼케이스 테마)

저장된 테마 설정 파일 또는 MESH_DASH_THEME_PRESET이 다른 사전 설정을 선택하지 않는 한, 새 설치의 기본값은 default입니다.

관련 환경 변수:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

보안

• 이 대시보드는 신뢰할 수 있는 LAN/VPN 환경을 대상으로 합니다.
• 리버스 프록시 및 액세스 제어 없이 공개 인터넷에 직접 노출하지 마십시오.
• 더 엄격한 쓰기 경로 제어를 위해 --private-mode 및/또는 API 토큰을 사용하십시오.
• 공유 또는 다중 사용자 호스트에서는 --api-token보다 MESH_DASH_API_TOKEN을 선호하십시오. 명령줄 토큰은 프로세스 목록에 표시되고 셸 기록에 남을 수 있습니다.
• 기본 제공 Join Meshyface 채널 사전 설정은 이 소프트웨어 사용자 간의 상호 운용성을 위해 의도적으로 공개된 공유 Meshyface PSK를 사용합니다. 개인 트래픽에 해당 공개 채널을 사용하지 마십시오.
• --show-secrets는 원시 JSON 패널에서 민감한 값을 노출합니다. 공유 디스플레이에서 아무렇게나 활성화하지 마십시오.
• 원시 패킷 데이터베이스 다운로드는 메시지 및 원격 측정 내용을 노출할 수 있습니다. 공유 호스트에서는 API 토큰을 요구하고 --no-allow-tokenless-raw-packet-download를 사용하십시오.
• 파일 전송은 상당한 메시 에어타임을 소비할 수 있습니다. 해당 트레이드오프를 명시적으로 수락하지 않는 한 비활성화 상태로 유지하십시오.

테스트 및 커버리지

일반 테스트 스위트를 실행합니다:

python -m pytest

CI와 동일한 방식으로 Ruff를 실행합니다:

scripts/run_ruff_local.sh

권고 앱 커버리지 보고서를 실행합니다:

python -m pytest \
  --cov=meshdash \
  --cov=mesh_dashboard \
  --cov=mesh_connection \
  --cov-report=term

더 엄격한 85% 최소 기준으로 로컬 커버리지 게이트를 실행합니다:

scripts/run_coverage_local.sh

PR 전에 로컬 GUI 응답성 벤치마크를 실행합니다:

scripts/run_gui_responsiveness_local.sh

커버리지는 포팅된 Zork 엔진 패키지를 의도적으로 점수 산정에서 제외하지만, 독립형 Zork 및 라우팅 테스트는 계속 실행됩니다. GitHub Actions는 동일한 커버리지 보고서를 권고 PR 댓글 및 아티팩트로 게시합니다. CI는 80% 미만이면 실패합니다. 로컬 게이트는 CI보다 5% 포인트 높게 유지됩니다.