문제 해결

이 문서는 증상별로 문제 해결 절차를 설명합니다. 기본 원칙은 먼저 읽기 전용 조회로 근거를 수집한 후 변경 작업을 수행하는 것입니다. 각 단계에서 관찰한 현상, 실행한 명령과 종료 코드, 예상 결과와 실제 결과의 차이를 기록하세요.

장치 접속 불가(SSH 연결 불가)

여러 계층의 문제를 한꺼번에 판단하지 말고 계층별로 원인을 찾습니다.

장치 대장의 주소와 대조합니다(비슷한 주소를 서로 바꿔 사용할 수 없음).
주소 확인, 라우팅, SSH 포트 연결 및 인증 방식을 차례로 확인합니다.
이전에 접속되던 장치가 갑자기 연결되지 않으면 최근 업데이트 또는 다시 시작 시간과 연관성을 확인하고, 필요하면 현장에 시리얼 포트나 물리적 상태 점검을 요청합니다.

부팅 출력, 이전 부팅 로그(journalctl -b -1), 워치독 리셋 원인 및 파일 시스템 오류를 수집합니다.
문제가 발생한 단계를 구분합니다. 부트로더, 커널, 시스템 전환, 서비스 시작, 워치독 리셋 또는 애플리케이션의 트리거 여부를 확인합니다.
부팅 횟수(bootcount)를 확인합니다. 연속 부팅 실패는 자동 복구 정책을 트리거하며, 임계값에 도달하면 복구 모드와 파티션 롤백으로 차례로 진입합니다(A/B 이중 시스템 및 전환 참조).
jelina-info와 jelina-auto-recovery --state로 현재 복구 상태를 확인합니다.

원인을 확인하기 전에 파티션을 수동으로 전환하거나 롤백하지 마세요. 자동 복구 절차가 손상될 수 있습니다.

systemctl is-system-running
systemctl --failed --no-pager

실패한 서비스를 하나씩 점검한 다음 핵심 서비스를 확인합니다. 선택적 플랫폼 관련 서비스의 실패가 시스템 이상을 의미하지는 않습니다. 일회성 서비스가 실행을 마친 후 비활성 상태가 되는 것도 정상입니다.

업데이트 상태와 진행률을 확인합니다(jelina-info --get ota_status --json, jelina-local-ota -s).
확인 대기 중인 업데이트가 있는지 확인합니다(로컬 확인 메커니즘에서 확인 대기는 정책에 따른 상태이며 멈춘 상태가 아님).
장치 에이전트 서비스와 로그를 확인합니다.
디스크 공간, 업데이트 설치 프로그램 상태 및 프로세스를 확인합니다.
업데이트 패키지에 대한 접근 가능 여부, 시스템 시계, 도메인 이름 확인 및 인증서를 확인합니다.
실제로는 설치가 완료되어 다시 시작하거나 다시 마운트하여 적용되기를 기다리는 상태인지 판단합니다.

진단 중에는 업데이트를 반복 제출하거나 확인하지 말고, 다시 시작 대기 상태의 마커를 삭제하지 마세요.

목표 상태, 이미지 다운로드, 컨테이너 생성, 프로세스 상태, 포트 및 방화벽, 애플리케이션 자체 상태를 각각 점검합니다. 자주 사용하는 명령은 다음과 같습니다.

docker ps                # 컨테이너 상태
docker logs <컨테이너_이름>      # 컨테이너 로그

현장 근거를 저장하기 전에 시스템이 관리하는 컨테이너나 서비스를 수동으로 다시 생성하지 마세요.

루트 파티션과 데이터 파티션의 공간 및 파일 수 사용량을 비교합니다(df -hT, df -i).
임시 루트 모드에 진입했는지 확인합니다(jelina-enter-tmpfs-root --status, 저장 공간 및 데이터 파티션 참조).
원래 시스템 파티션이 읽기 전용인 경우(정상 설계), 데이터 파티션 장애 및 오버레이 계층이 정상적으로 마운트되지 않은 경우를 구분합니다.

알 수 없는 시스템 디렉터리나 패키지 디렉터리는 삭제하지 마세요. 임시 루트 모드에서는 업무 작업을 수행하지 마세요.

서비스 시작 조건, 프로그램 파일 존재 여부와 권한, 스크립트 인터프리터 및 필요한 마운트의 준비 상태를 차례로 확인합니다.

시간 오류는 흔히 인증서 검증이나 클라우드 인증 실패로 나타납니다. 시스템 시간, 하드웨어 시계 및 시간 동기화 서비스 로그를 비교합니다.
도메인 이름 확인 오류가 발생하면 이름 확인 서비스 상태와 네트워크 연결 설정을 점검합니다. 시스템에서 생성한 이름 확인 설정 파일을 수동으로 덮어쓰지 마세요.

SSH로 로그인한 터미널에는 일반적으로 데스크톱 세션 환경이 없으므로, 디스플레이 변수가 비어 있어도 GUI 장애를 의미하지는 않습니다.

일부 장치에서는 성능 이력 보관 및 영구 로그가 활성화되어 있어 다시 시작 전 시스템 상태를 추적할 수 있습니다.

journalctl --list-boots              # 부팅 목록
journalctl -b -1 -p warning..alert   # 이전 부팅의 경고 로그
ls -1t /var/log/atop | head          # 과거 성능 기록

예기치 않은 다시 시작의 원인을 파악하려면 부팅 목록, 이전 부팅 로그, 워치독 리셋 원인, 가동 시간 및 업데이트/파티션 전환 이력을 연계하여 확인해야 합니다.