Portainer 에서 컨테이너를 안전하게 업데이트하는 순서

이런 상황일 때

돌리는 서비스의 새 이미지가 나왔습니다. Portainer 화면에서 올리고 싶은데, Recreate 버튼을 눌러도 데이터가 무사한지 확신이 없어 미루고 있습니다.

한 줄 결론

Portainer 의 업데이트는 재생성(Recreate)입니다 — 확인 대화상자도 '보존되지 않은 데이터는 사라진다' 고 직접 경고합니다. 그래서 순서는 버튼이 아니라 마운트 확인이 먼저입니다: 데이터가 볼륨에 있는 것을 확인하고, 백업하고, 그다음 Re-pull image 를 켜고 재생성합니다.

핵심 개념

업데이트 = 삭제 후 재생성

컨테이너는 이미지의 실행본이라 '그 자리에서 판만 바꾸는' 업데이트가 없습니다. Recreate 확인 창의 실제 문구가 정확합니다 — 같은 설정으로 컨테이너를 지우고 새로 만들며, 보존(마운트)하지 않은 데이터는 사라집니다.

Re-pull image 토글이 곧 '업데이트'

Recreate 대화상자의 Re-pull image 를 켜면 새 이미지를 받아 재생성하고, 끄면 같은 이미지로 다시 만듭니다. 문제 해결용 재생성과 업데이트용 재생성이 이 토글 하나로 갈립니다.

태그가 latest 면 어느 판으로 갈지 모른다

Re-pull 은 지금 태그를 다시 받습니다. latest 태그면 그 순간의 최신으로 건너뛰므로, 판을 확인하며 올리려면 번호 태그를 쓰는 것이 안전합니다 — 태그 약속의 세기는 Docker 체크리스트 글에 있습니다.

Portainer 자신은 이 방법으로 못 올린다

실측에서 Portainer 는 자기 컨테이너의 Recreate 를 막아 두고 있었습니다. Portainer 자체의 업데이트는 서버 셸에서 공식 문서의 절차(컨테이너 교체)로 합니다.

지금 추적 중인 버전

이 표의 값은 공식 릴리스에서 가져온 것이며, 아래 마지막 검토일 기준입니다.

이런 분에게 해당됩니다

• Portainer 로 홈서버 컨테이너를 관리하는 분
• Recreate 버튼이 데이터를 지울까 불안한 분
• 업데이트 후 서비스가 빈 화면이 된 경험이 있는 분

확인해야 할 항목

• 데이터가 볼륨·바인드 마운트에 있는가 (아래 ①)
• 볼륨 백업을 했는가 (아래 ②)
• 이미지 태그가 latest 인가 번호인가
• 새 판의 릴리스 노트에 주의사항이 있는가
• 재생성 후 확인할 화면·기능을 정해 뒀는가

잘못 이해하기 쉬운 부분

안전한 행동 순서

1. 아래 ① 로 그 컨테이너의 마운트를 확인합니다. 중요한 데이터 경로가 목록에 없으면 — 업데이트를 멈추고 마운트 설계부터 고칩니다.
2. 아래 ② 로 볼륨을 백업합니다. 데이터베이스면 그 DB 의 덤프 도구를 먼저 씁니다.
3. 새 판의 릴리스 노트를 확인합니다 — 설정 변경 요구가 있는 판이 있습니다.
4. Portainer 의 컨테이너 상세에서 Recreate 를 누르고, 확인 창에서 Re-pull image 를 켠 뒤 진행합니다.
5. 재생성 후 상태가 Up 으로 유지되는지, 화면·기능이 정상인지 확인합니다.
6. 문제가 있으면 로그를 남기고(재시작 루프 글 절차), 백업으로 되돌립니다.

① 업데이트 전 — 마운트 확인 (읽기만)

docker inspect <컨테이너이름> --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}}{{println}}{{end}}'

서버 셸에서 실행합니다. Portainer 화면에서는 컨테이너 상세의 Inspect 로도 같은 것을 봅니다 · 확인: 2026-08-07 · wp3 VM (Debian, Docker Engine 29.7.1)

② 업데이트 전 — 볼륨 백업

docker run --rm -v <볼륨이름>:/from:ro -v "$PWD":/to alpine tar czf /to/backup.tgz -C /from .
tar tzf backup.tgz

볼륨을 읽기 전용으로 물려 백업만 만듭니다. 자세한 원리는 볼륨·바인드 마운트 글에 있습니다 · 확인: 2026-08-07 · wp3 VM (Debian, Docker Engine 29.7.1)

확인 체크리스트

• 마운트 목록에 데이터 경로가 있는 것을 확인했다
• 볼륨을 백업하고 목록을 확인했다
• 릴리스 노트를 읽었다
• Re-pull image 를 켜고 재생성했다
• 재생성 후 정상 동작을 확인했다

관련 도구와 버전 페이지

• Portainer 버전 추적
  이 사이트가 Portainer 릴리스를 추적합니다. 대표 페이지에서 현재 안정판과 배포일을 확인할 수 있습니다.

자주 묻는 것

Recreate 후 서비스가 빈 화면으로 시작합니다.

데이터가 컨테이너 안에만 있었을 가능성이 큽니다. 옛 컨테이너는 이미 지워졌으므로, 이제는 백업에서 복원하는 길입니다 — 이 사고를 막는 것이 ①·② 단계입니다.

Duplicate/Edit 는 언제 쓰나요?

설정(포트·마운트·환경 변수)을 바꾸며 다시 만들 때 씁니다. 같은 설정으로 판만 올리는 일반 업데이트는 Recreate + Re-pull 이 맞습니다.

Portainer 자체는 어떻게 업데이트하나요?

실측에서 자기 자신의 Recreate 는 막혀 있었습니다. 서버 셸에서 공식 문서의 절차(정지 → 제거 → 새 이미지로 재실행, 데이터 볼륨 유지)로 진행합니다.