문제 해결

먼저 장비에서 이것부터 봅니다. 대부분의 답이 여기 있습니다.

geo-mlops-edge status          # 맨 위 '!!' 문장, link.state, sync.state, backlog
geo-mlops-edge queue --state failed
journalctl -u geo-mlops-edge -n 200     # 또는 docker compose logs edge

플릿에 '비정상'으로 나온다 / 오프라인#

증상: 목록에서 비정상, 마지막 하트비트가 몇 분 전. 장비의 link.state 가 offline.

하트비트가 서버 기준(기본 180초) 동안 오지 않으면 비정상 이 됩니다. 확인할 것:

1. 에이전트가 떠 있나? geo-mlops-edge status 가 no agent is listening … 이면 서비스가 멈춘 것입니다. systemctl status geo-mlops-edge 를 봅니다.

2. 주소가 맞나? geo-mlops-edge config 의 central.base_url 을 확인하고, 장비에서 직접 요청해 봅니다.

   curl -s https://mlops.example.com/api/v1/health

   응답이 없으면 DNS·방화벽·프록시 문제입니다. 사내 인증서를 쓰는 서버라면 장비에 CA 를 설치하거나(권장) central.verify_tls: false 로 시험합니다.

3. Offline 차단인가? 화면에 Offline 차단됨 배지가 있으면 운영자가 서버에서 끊어 둔 것입니다. 장비는 503 을 받고 데이터를 쌓아 두는 중이며, 차단을 풀면 스스로 회복합니다.

4. 하트비트 주기가 너무 긴가? 정책의 하트비트 주기가 180초에 가까우면 정상 장비도 비정상 과 정상을 오갑니다.

오프라인 동안에도 수집은 계속되고 데이터는 보존 한도 안에서 쌓입니다. 링크가 돌아오면 사람이 할 일은 없습니다.

401: 토큰 거절#

증상: status 맨 위에 !! Central rejected this device's token …, link.state 와 sync.state 가 auth_failed, 로그에 401 invalid or expired edge token.

토큰이 틀렸거나, 회전·회수됐거나, 만료(1년)된 것입니다. 에이전트는 이 상태에서 일부러 멈춰 있습니다. 명령 폴링도 멈추므로 중앙에서는 고칠 수 없습니다.

조치: 중앙에서 회전 으로 새 토큰을 받고, 장비의 /etc/geo-mlops/edge.env 를 고친 뒤 서비스를 재시작합니다(배포: 디바이스 토큰 교체). 토큰 앞뒤 공백·줄바꿈이 섞이지 않았는지도 봅니다.

403: 스코프 없음#

증상: status 에 !! Central refuses uploads: … The token is still valid; a scope was removed., sync.denied 에 이유.

토큰은 유효하지만 그 일의 스코프가 꺼져 있습니다(예: 파일 업로드인데 data:write 가 없음). 그 종류의 일만 멈추고 나머지는 계속됩니다.

조치: 디바이스 상세 토큰 관리 의 스코프 편집 에서 스코프를 켭니다. 장비 쪽에서 할 일은 없고 스스로 회복합니다.

413: 요청이 너무 큼#

어디서 났는지에 따라 다릅니다.

PayloadTooLargeError 는 다시 보내도 결과가 같으므로 CentralClient 도 재시도하지 않습니다.

큐가 줄지 않는다(적체)#

증상: 플릿 목록의 대기(적체 건수) 숫자가 계속 늘거나, 옆에 빨간 −N(최근 24시간 보존 한도로 버린 건수)이 보임.

status 의 sync 를 봅니다.

그 밖에:

• 보내는 속도보다 많이 모읍니다. −N 이 계속 보이면 회선이 데이터 양을 감당하지 못하는 것입니다. http 수집기의 interval_ms 를 늘리거나, watchdir 파일을 줄이거나, sync.max_bytes_per_s 가 너무 낮지 않은지 봅니다.
• 실패는 20번까지 재시도합니다. 일시적인 실패는 10초 안팎에서 시작해 간격을 두 배씩 늘리며(최대 15분) 다시 보냅니다. 20번을 넘기면 failed 로 표시해 둡니다.
• 버리는 순서는 우선순위가 낮은 것부터, 같은 우선순위에서는 오래된 것부터입니다. 잃으면 안 되는 수집기는 priority 를 올려 두세요.

그 밖의 증상#