문제 해결

장비에서 다음 항목부터 확인.

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 차단됨 배지가 있으면 운영자가 서버에서 차단한 상태. 이때 장비의 link.state 는 online 그대로이고, 로그에 503 edge device … is blocked by an operator 기록. 장비는 데이터를 누적했다가 차단이 해제되면 다시 전송. 차단이 3시간을 넘었으면 해제 후 queue --state failed 를 확인하고 재동기화 명령 전송(명령·정책·보존).

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.(하트비트면 heartbeats), sync.denied 에 거부 사유.

토큰은 유효하지만 해당 작업의 스코프가 비활성화된 상태(예: 파일 업로드인데 data:write 가 없음). 해당 종류의 작업만 중단되고 나머지는 계속. telemetry:write 를 비활성화하면 하트비트도 거부되므로 장비의 링크는 online 이지만 플릿에서는 비정상 으로 표시.

조치: 디바이스 상세 토큰 관리 의 스코프 편집 에서 스코프 활성화. 이후 새로 누적되는 데이터부터 다시 전송. 거부 시점에 전송 중(uploading) 상태였던 항목은 에이전트를 재시작해야 대기 상태로 복귀. geo-mlops-edge queue --state uploading 으로 확인하고, 재시작 명령 전송 또는 서비스 재시작(명령 폴링에는 스코프 불필요).

413: 요청이 너무 큼#

발생 위치에 따라 원인과 조치가 다름.

PayloadTooLargeError 는 재전송해도 결과가 같으므로 CentralClient 도 재시도하지 않음.

큐 적체 (항목이 줄지 않음)#

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

플릿의 대기 숫자와 backlog.count 는 failed 상태인 항목을 포함하지 않음. status 의 sync 확인.

기타:

• 전송 속도보다 수집량이 많음. −N 이 계속 표시되면 회선이 데이터 양을 감당하지 못하는 상태. http 수집기의 interval_ms 를 늘리거나, watchdir 파일 수를 줄이거나, sync.max_bytes_per_s 가 너무 낮지 않은지 확인.
• 일시적인 실패는 20번째에 재시도 중단. 10초에서 시작해 간격을 두 배씩 늘리며(최대 15분) 재전송, 20번째 실패에서 failed 로 표시. 재동기화 로 되돌려도 시도 횟수는 초기화되지 않으므로 다음 일시적 실패에서 즉시 다시 failed 로 전환.
• 삭제 순서는 우선순위가 낮은 것부터, 같은 우선순위에서는 오래된 것부터. 손실되면 안 되는 데이터의 수집기는 priority 상향 필요.

기타 증상#