문제 해결
사용자가 로그인할 수 없습니다
섹션 제목: “사용자가 로그인할 수 없습니다”LabPod 비밀번호는 Linux 비밀번호와 별개입니다. LabPod 자격 증명을 확인하세요:
sudo labpod admin --db /var/lib/labpod/labpod.db list-users # confirm the account existssudo labpod admin --db /var/lib/labpod/labpod.db set-password alice# Run these as rootlabpod admin --db /var/lib/labpod/labpod.db list-users # confirm the account existslabpod admin --db /var/lib/labpod/labpod.db set-password alicejournald에서 로그인 실패 기록을 확인하세요:
sudo journalctl -u labpod --since "5 minutes ago" | grep login_failed# Run these as rootjournalctl -u labpod --since "5 minutes ago" | grep login_failed워크스페이스가 starting 상태에서 멈춰 있습니다
섹션 제목: “워크스페이스가 starting 상태에서 멈춰 있습니다”LabPod는 podman run -d가 완료될 때까지 최대 LABPOD_WORKSPACE_START_TIMEOUT(기본값 15분)을 기다립니다. 타임아웃이 지나면 워크스페이스는 failed 상태가 됩니다. 아직 시작 중인 동안 조사하려면:
sudo runuser -u <owner> -- podman ps -a --filter name=labpod-ws-<id>sudo runuser -u <owner> -- podman inspect labpod-ws-<id>sudo runuser -u <owner> -- podman logs labpod-ws-<id># Run these as rootrunuser -u <owner> -- podman ps -a --filter name=labpod-ws-<id>runuser -u <owner> -- podman inspect labpod-ws-<id>runuser -u <owner> -- podman logs labpod-ws-<id>일반적인 원인:
- 이미지가 없음: 템플릿을 선택하고 레지스트리 이미지에는 확인을 거친 Pull을 사용하세요. 관리자 빌드 이미지는 Pull하면 공유 원본에서 사용자 저장소로 복사합니다. 아직 준비되지 않았다면 관리자에게 build를 요청하세요. Dockerfile 기반 개인 템플릿에는 Build가 필요합니다.
- 디스크 부족:
/home사용량을 확인하세요. 리소스 페이지에 디스크 압박 상태가 표시됩니다. - 포트 충돌: 드뭅니다. LabPod는 관리되는 풀(기본값 10000~19999)에서 포트를 할당합니다.
/work 컨테이너 라벨 때문에 워크스페이스 시작이 실패합니다
섹션 제목: “/work 컨테이너 라벨 때문에 워크스페이스 시작이 실패합니다”사용자에게 다음과 같은 메시지가 표시될 수 있습니다:
Couldn’t start the workspace because LabPod couldn’t apply the container label to
/work/<path>. In Files, download it first if needed, then delete it from/work; or move it outside~/workfrom your host account.
SELinux 호스트에서 LabPod는 각 사용자의 ~/work 디렉터리를 컨테이너의 /work로 마운트하고
공유 컨테이너 라벨을 적용합니다. 루트리스 Podman은 워크스페이스 소유자 권한으로 이 라벨을
적용합니다. ~/work 안에 root 소유 파일이나 보호된 파일이 있으면 Podman이 라벨을 다시 붙일 수
없어 컨테이너가 시작되기 전에 워크스페이스가 실패합니다.
사용자에게 오류에 표시된 경로를 확인하도록 안내하세요. 호스트 계정에서 해당 항목을 ~/work
밖으로 옮길 수 있습니다:
mkdir -p ~/labpod-unmountedmv ~/work/<path> ~/labpod-unmounted/해당 항목이 필요 없다면 LabPod의 파일 페이지에서 삭제해도 됩니다. ~/work 안에서 사용자가
소유하지 않은 다른 파일을 찾으려면:
find ~/work -not -user "$USER" -ls파일을 ~/work에 유지해야 한다면 소유권을 수정하세요:
sudo chown -R <user>:<user> /home/<user>/work/<path># Run these as rootchown -R <user>:<user> /home/<user>/work/<path>워크스페이스 마운트의 SELinux 라벨링을 끄지 마세요. 끄면 LabPod가 사용자 소유 bind mount로 유지하는 격리가 약해집니다.
Jupyter에 사용자 이름이 jovyan으로 표시됩니다
섹션 제목: “Jupyter에 사용자 이름이 jovyan으로 표시됩니다”일부 Jupyter 기반 이미지는 LabPod 사용자 이름이 다른 경우에도 터미널, 파일 경로, 프롬프트,
노트북 UI에 jovyan을 표시합니다.
LabPod 기본 템플릿(PyTorch, TensorFlow, Data Science, PyTorch Demo)은 jovyan 계정이 없는
LabPod 빌드 ghcr.io/labpod/* 이미지를 사용하므로 이 현상이 나타나지 않습니다. upstream
Jupyter Docker Stacks 이미지(quay.io/jupyter/*-notebook)를 가리키는 템플릿에서는 여전히
나타날 수 있는데, 이 경우 jovyan 계정이 이미지 안에 미리 포함되어 있고 LabPod는 시작 시
이미지 사용자 이름을 바꾸지 않습니다. LabPod는 --userns=keep-id로 컨테이너를 실행하므로
컨테이너 내부의 숫자 UID/GID가 호스트의 LabPod Linux 사용자와 일치합니다.
사용자는 표시되는 이름을 무시해도 됩니다. /work 아래에 생성한 파일은 이미지의 표시 사용자
이름이 아니라 UID를 기준으로 소유권이 정해지므로, 호스트의 LabPod 계정 소유로 남습니다. 다만
템플릿 이미지가 워크스페이스 소유자의 숫자 UID를 이미 예약했다면 영속 홈이 아닌 경로를 쓰게 될
수 있으므로 시작 전에 거부합니다. 템플릿 작성자는 해당 UID를 비워 두어야 합니다.
워크스페이스 안에서 확인하려면:
idtouch /work/labpod-uid-check.txtls -ln /work/labpod-uid-check.txt호스트에서 같은 파일을 보면 LabPod 사용자의 UID가 표시되어야 합니다:
ls -ln /home/<user>/work/labpod-uid-check.txt임시 해결책으로 이미지 계정 이름을 바꾸지 마세요. 템플릿에서 다른 표시 사용자 이름이 필요하다면 해당 계정을 일관되게 생성하는 커스텀 이미지를 빌드하세요.
관리자 리소스 페이지에 추적되지 않은 GPU 사용량이 표시됩니다
섹션 제목: “관리자 리소스 페이지에 추적되지 않은 GPU 사용량이 표시됩니다”nvidia-smi가 LabPod 워크스페이스 cgroup에 속하지 않는 GPU 프로세스를 감지하면 이 표시가 켜집니다. 일반적인 원인:
- 사용자가 컨테이너 밖 호스트에서 직접 학습을 실행 중입니다.
- 워크스페이스가 삭제되었지만 GPU 프로세스가 남아 있습니다.
프로세스를 찾아 해제하세요:
nvidia-smi --query-compute-apps=pid,process_name,used_memory,gpu_uuid --format=csvsudo kill -TERM <pid># After 30 seconds if still alive:sudo kill -KILL <pid># Run these as rootnvidia-smi --query-compute-apps=pid,process_name,used_memory,gpu_uuid --format=csvkill -TERM <pid># After 30 seconds if still alive:kill -KILL <pid>labpod admin doctor가 문제를 보고합니다
섹션 제목: “labpod admin doctor가 문제를 보고합니다”메시지를 읽고 그에 따라 수정하세요. doctor가 확인하는 항목:
| 확인 항목 | 수정 방법 |
|---|---|
| 필수 명령 바이너리 | 누락된 패키지를 설치하거나, LabPod 관리 파일을 복원하려면 공개 설치 스크립트를 다시 실행 |
| cgroup 모드 | cgroup v2로 업그레이드하거나 저하된 CPU/MEM 적용 수락 |
| 분할 GPU 라이브러리 | LABPOD_GPU_SHARING_LIB_PATH가 올바른 파일을 가리키는지 확인 |
워크스페이스 헬퍼 파일(/opt/labpod/inject) | 공개 설치 스크립트를 다시 실행하여 헬퍼 파일 복원 |
| GPU 프로세스 검사기 | nvidia-smi를 설치하거나 LABPOD_GPU_PROCESS_INSPECTOR=none 설정 |
| 포트 가드 | nft가 설치되어 있고 서비스가 root로 실행 중인지 확인 |
| TLS 인증서 | LABPOD_TLS_CERT/LABPOD_TLS_KEY 경로 또는 LABPOD_TLS_SELF_SIGNED 확인 |
업그레이드 후 서비스가 시작되지 않습니다
섹션 제목: “업그레이드 후 서비스가 시작되지 않습니다”먼저 저널을 확인하세요:
sudo journalctl -u labpod -n 200 --no-pagersudo labpod admin doctor# Run these as rootjournalctl -u labpod -n 200 --no-pagerlabpod admin doctor마이그레이션이 실패하는 경우:
sudo labpod admin --db /var/lib/labpod/labpod.db migrate # idempotent; safe to retry# Run these as rootlabpod admin --db /var/lib/labpod/labpod.db migrate # idempotent; safe to retry마이그레이션 자체가 손상된 경우, 업그레이드 중 설치 스크립트가 생성한 pre-upgrade-*.db 스냅샷을 복원하세요:
sudo systemctl stop labpodsudo labpod admin --db /var/lib/labpod/labpod.db restore \ /var/lib/labpod/backups/pre-upgrade-<stamp>.dbsudo systemctl start labpod# Run these as rootsystemctl stop labpodlabpod admin --db /var/lib/labpod/labpod.db restore \ /var/lib/labpod/backups/pre-upgrade-<stamp>.dbsystemctl start labpod설치 프로그램이 설정 오류를 알리면서 중단됐다면 해당 설정을 고친 뒤 다시 실행하세요. 사전 점검은
데이터베이스, 이미지 저장소, TLS 자료, GPU 공유 라이브러리, inject 트리, 시작 불가 boolean 값을
바이너리를 교체하거나 API를 중지하기 전에 확인합니다. install.sh --check를 사용하면 설정 문제를
한 번에 모두 확인할 수 있습니다.
디스크 압박
섹션 제목: “디스크 압박”공간을 차지하는 항목을 확인하세요:
du -sh /var/lib/labpod/ # database + backups (usually small, <100 MB)du -sh /var/lib/labpod/backups/ # backup rotation directorysudo podman system df # root's image layerssudo -u <user> podman system df # per-user image layers# Run these as rootdu -sh /var/lib/labpod/ # database + backups (usually small, <100 MB)du -sh /var/lib/labpod/backups/ # backup rotation directorypodman system df # root's image layersrunuser -u <user> -- podman system df # per-user image layers가장 많은 공간을 차지하는 항목:
~/.local/share/containers/의 사용자별 컨테이너 이미지~/work/.hf-cache/의 Hugging Face 캐시
사용자의 미사용 이미지 레이어를 회수하려면:
sudo -u <user> podman image prune -f# Run these as rootrunuser -u <user> -- podman image prune -f또는 LabPod의 관리자 이미지 페이지를 사용해 미사용 레이어를 한 번에 모두 정리하세요.
버전 불일치
섹션 제목: “버전 불일치”curl http://127.0.0.1:24680/api/version이 labpod --version과 다른 SHA를 반환하면, 바이너리는 교체됐지만 서비스가 재시작되지 않은 상태입니다:
sudo systemctl restart labpod# Run these as rootsystemctl restart labpod