문제 해결
이 가이드는 PCS를 사용하면서 가장 흔히 발생하는 문제와 해결 방법을 다룹니다.
앱이 시작되지 않음
증상: 관리자 패널에서 앱이 "Down"으로 표시되거나, URL 접속 시 오류가 나타남.
진단 방법:
- 관리자 패널 → 앱에서 해당 앱에 문제가 있는지 확인합니다.
- 관리자 패널 → 터미널에서 연결을 클릭하고 다음을 실행합니다:
이 명령으로 컨테이너가 종료되었는지와 종료 코드를 확인할 수 있습니다.docker ps -a | grep <앱-이름>
- 앱의 로그를 확인합니다:
docker logs <컨테이너-이름> --tail 100
일반적인 원인과 해결 방법:
| 원인 | 해결 방법 |
|---|---|
| 포트 충돌 | 다른 컨테이너가 같은 포트를 사용 중. 충돌하는 컨테이너를 중지하거나 포트를 변경하세요. |
| 메모리 부족 | 리소스 → CPU 탭에서 메모리 사용량을 확인. 사용하지 않는 앱을 중지하여 RAM을 확보하세요. |
| 데이터 손상 | 앱 페이지에서 백업을 복원하거나, 앱을 삭제 후 재설치하세요. |
| Docker 이미지 다운로드 실패 | 인터넷 연결을 확인. 터미널에서 docker pull <이미지>를 수동으로 실행하세요. |
도메인에 접속할 수 없음
증상: yourdomain.nsl.sh 접속 시 연결 오류 또는 타임아웃이 발생함.
진단 방법:
- sslip.io 대체 도메인(예:
169-58-42-143.sslip.io)으로 PCS에 접속 가능한지 확인합니다. - 관리자 패널 → 도메인에서 공인 IP가 실제 IP와 일치하는지 확인합니다.
- 관리자 패널 → 상태에서 지금 실행을 클릭하여 자가 점검을 실행합니다.
일반적인 원인과 해결 방법:
| 원인 | 해결 방법 |
|---|---|
| IP 주소 변경 | ISP가 새 IP를 할당함. 상태 페이지에서 자가 점검 실행 — 새 IP를 감지하고 라우팅을 업데이트합니다. |
| Caddy(웹 서버) 중단 | 터미널에서: docker ps | grep caddy. 실행 중이 아니면: sudo systemctl restart caddy 또는 자가 점검을 실행하세요. |
| ISP의 443 포트 차단 | 일부 ISP는 인바운드 HTTPS를 차단합니다. ISP에 문의하거나 Cloudflare 프록시 사용을 고려하세요(도메인 페이지 참조). |
| DNS 전파 지연 | 최근 도메인 설정을 변경했다면, DNS 전파까지 최대 24시간이 걸릴 수 있습니다. |
인증서 오류
증상: 브라우저에 "연결이 비공개가 아닙니다" 또는 인증서 경고가 표시됨.
진단 방법:
- 관리자 패널 → 인증서에서 새로고침을 클릭합니다.
- 영향을 받는 도메인이 "Let's Encrypt"인지 "Internal CA"인지 확인합니다.
일반적인 원인과 해결 방법:
| 원인 | 해결 방법 |
|---|---|
| 내부 CA 인증서 | Caddy가 Let's Encrypt 인증서를 받지 못함. 포트 443이 인터넷에서 열려 있고 접근 가능한지 확인하세요. |
| 발급 제한 초과 | Let's Encrypt에는 발급 제한이 있습니다. 몇 시간 후 인증서가 자동으로 재시도됩니다. |
| 인증서 만료 | 상태 → 지금 실행으로 자가 점검을 실행하세요. 야간 유지보수에서 갱신했어야 하지만, 수동 실행으로 강제 갱신할 수 있습니다. |
| Cloudflare 없는 커스텀 도메인 | Cloudflare 없이 직접 DNS를 사용하는 경우 인증서를 직접 구성해야 합니다. Cloudflare 사용을 권장합니다. |
팁
게이트웨이 라우트(.nsl.sh 도메인)와 .nip.io 라우트는 의도적으로 Yundera의 내부 CA를 사용합니다. 이는 설계된 동작입니다. .sslip.io 도메인만 Let's Encrypt를 사용합니다.
SSO 로그인 문제
증상: 관리자 패널이나 앱에 로그인할 수 없거나, SSO 페이지에 오류가 표시됨.
진단 방법:
- CasaOS 대시보드에 직접 접속해 봅니다:
https://casaos-yourdomain.nsl.sh/ - CasaOS가 작동하면 Dex 인증 서비스에 문제가 있는 것입니다.
- 터미널에서 Dex 로그를 확인합니다:
docker logs dex --tail 50
일반적인 원인과 해결 방법:
| 원인 | 해결 방법 |
|---|---|
| 잘못된 비밀번호 | 시스템 정보 → 기본 사용자에 표시된 자격증명을 사용하세요. |
| Dex 서비스 중단 | 상태 → 지금 실행으로 자가 점검을 실행하여 모든 시스템 서비스를 재시작하세요. |
| 브라우저 쿠키 | .nsl.sh 도메인의 브라우저 쿠키를 삭제하고 다시 시도하세요. |
| 시간 오차 | PCS의 시계가 크게 어긋나면 SSO 토큰이 거부될 수 있습니다. 시스템 정보 → 호스트 재부팅으로 재부팅하세요. |
성능 저하
증상: 앱 응답이 느리거나, 페이지 로딩에 시간이 오래 걸림.
진단 방법:
- 관리자 패널 → 리소스로 이동합니다.
- CPU 탭 확인: 로드 평균이 코어 수를 초과하나요?
- 메모리 확인: 스왑이 많이 사용되고 있나요?
- 디스크 탭 확인: 루트 파일시스템이 90%를 초과하나요?
일반적인 원인과 해결 방법:
| 원인 | 해결 방법 |
|---|---|
| CPU 과부하 | 상위 프로세스를 확인하세요. 앱 페이지에서 사용하지 않는 앱을 중지하세요. |
| RAM 부족 | 스왑 사용은 RAM 부족을 나타냅니다. 메모리를 많이 사용하는 앱을 중지하거나 RAM이 더 많은 PCS로 업그레이드하세요. |
| 디스크 가득 참 | 앱 페이지에서 오래된 백업을 정리하거나, 사용하지 않는 앱 데이터를 삭제하세요. 터미널에서: docker system prune으로 사용하지 않는 Docker 리소스를 정리하세요. |
| 네트워크 병목 | 리소스 → 네트워크 탭에서 속도 테스트를 실행하여 대역폭을 확인하세요. |
| 디스크 I/O 느림 | 리소스 → 디스크 탭에서 디스크 벤치마크를 실행하세요. 결과가 예상보다 크게 낮으면 디스크에 문제가 있을 수 있습니다. |
앱 데이터 분실
증상: 앱의 데이터가 사라지거나 손상됨.
진단 방법:
- 관리자 패널 → 앱에서 해당 앱의 백업이 있는지 확인합니다.
- 터미널에서 데이터 디렉토리가 존재하는지 확인합니다:
ls -la /DATA/AppData/<앱-이름>/
복구 방법:
- 백업에서 복원 — 백업이 있다면, 앱 페이지의 복원 버튼을 사용하세요.
- Docker 볼륨 확인 — 일부 데이터는
/DATA/AppData대신 Docker 볼륨에 있을 수 있습니다. - 앱 재설치 — 데이터가 정말로 손실되고 백업도 없다면, CasaOS를 통해 재설치하세요.
팁
변경 작업 전에 항상 앱 페이지에서 정기적으로 백업을 생성하세요. 예방이 최선의 치료입니다.
자가 점검 / 업데이트 실패
증상: 야간 유지보수에서 상태 로그에 오류가 표시됨.
진단 방법:
- 관리자 패널 → 상태에서 로그 끝부분을 확인합니다.
- 빨간색 또는 "ERROR", "FAILED"가 포함된 오류 메시지를 찾습니다.
일반적인 원인과 해결 방법:
| 원인 | 해결 방법 |
|---|---|
| 인터넷 연결 없음 | 터미널에서 네트워크 연결을 확인: ping 8.8.8.8. |
| Docker 레지스트리 이용 불가 | 컨테이너 레지스트리의 일시적인 문제. 다음 야간 실행에서 재시도됩니다. |
| 디스크 가득 참 | Docker가 새 이미지를 받을 수 없음. 먼저 디스크 공간을 확보하세요. |
| 잘못된 업데이트 채널 | 비안정 채널로 변경한 경우, 상태 페이지에서 Stable로 다시 전환하세요. |
도움이 더 필요하신가요?
위의 해결 방법으로도 문제가 해결되지 않으면:
- 관리자 패널 → 지원으로 이동합니다.
- yundera.log 첨부와 SSH 접근 권한 부여를 활성화합니다.
- 문제를 자세히 설명하고 지원팀에 보내기를 클릭합니다.
Yundera 지원팀이 PCS에서 직접 문제를 진단할 수 있습니다.