운영·보안

Astro 사이트를 바로 덮어쓰지 않고 새 릴리스로 교체하는 이유

목차 보기

Astro 사이트의 배포 결과물은 HTML, CSS, JavaScript와 이미지로 이루어진 파일 묶음입니다. 그래서 가장 단순하게 생각하면 Nginx가 읽는 공개 폴더에 새 dist 파일을 그대로 복사하면 될 것 같았습니다.

하지만 파일은 한꺼번에 도착하지 않습니다. 수십 개의 HTML과 이미지가 차례로 복사되는 동안 홈페이지는 새 버전인데 연결된 파일은 아직 이전 버전이거나, 새 글의 HTML은 생겼지만 대표 이미지는 도착하지 않은 순간이 생길 수 있습니다. 업로드가 중간에 실패하면 그 혼합 상태가 더 오래 남습니다.

minml은 공개 폴더를 직접 덮어쓰는 대신 새 릴리스 디렉터리에 완성본을 전부 올리고 검사한 뒤, Nginx가 따라가는 current 심볼릭 링크만 새 릴리스로 교체합니다. 문제가 확인되면 같은 방식으로 직전 릴리스를 다시 가리키고, 공개 검사를 통과한 뒤에는 최신 릴리스 5개만 남깁니다.

덮어쓰기 배포의 중간 상태

정적 사이트라고 해서 파일 하나만 교체되는 것은 아닙니다. 글 한 편을 추가해도 해당 글의 HTML, 목록 페이지, 사이트맵, RSS와 대표 이미지 등이 함께 바뀔 수 있습니다. CSS나 JavaScript 파일 이름에 내용 해시가 들어간다면 새 HTML이 참조하는 새 파일도 같은 배포에 포함됩니다.

공개 폴더에 직접 복사할 때는 첫 파일이 도착한 순간부터 마지막 파일이 도착할 때까지 사이트 상태가 계속 달라집니다.

복사 중인 시점 방문자가 볼 수 있는 상태
새 HTML만 먼저 도착 HTML이 아직 없는 새 이미지나 자산을 요청할 수 있음
새 자산만 먼저 도착 화면은 이전 HTML이지만 서버에는 두 버전의 파일이 섞여 있음
전송이 중간에 실패 어느 파일까지 바뀌었는지 따로 조사해야 함
일부 파일을 삭제하는 변경 이전 버전의 불필요한 파일이 공개 폴더에 남을 수 있음

파일 수가 적고 전송이 빠르면 이 구간이 짧을 수는 있습니다. 하지만 실패했을 때 이전 상태로 돌아가려면 어떤 파일이 덮어써졌고 어떤 파일이 남았는지 다시 계산해야 합니다.

릴리스 방식은 공개 여부를 두 상태로 나눕니다. 새 파일 묶음을 준비하는 동안 방문자는 계속 기존 릴리스를 보고, 준비와 검사가 끝난 뒤에만 공개 대상이 새 릴리스로 바뀝니다.

릴리스 구조와 배포 순서

원리를 단순화하면 서버 구조는 다음과 같습니다.

<site-root>/
├─ releases/
│  ├─ <previous-release>/
│  └─ <new-release>/
└─ current -> releases/<previous-release>/

Nginx는 타임스탬프가 붙은 개별 릴리스 경로를 직접 바라보지 않고 current 아래의 파일을 제공합니다. 새 배포를 시작해도 current는 그대로이므로 새 릴리스에 파일을 복사하는 작업이 공개 사이트에 바로 드러나지 않습니다.

minml의 배포 스크립트는 다음 순서로 실행됩니다.

  1. Git 작업 폴더에 커밋하지 않은 변경이 있으면 배포를 거부합니다.
  2. 로컬에서 Astro를 빌드하고 내부 링크, 이미지, 초안과 사이트맵을 검사합니다.
  3. 빌드 결과에 index.html, 404.html, sitemap-index.xml이 있는지 확인합니다.
  4. 현재 current가 가리키는 직전 릴리스를 기록합니다.
  5. 새 릴리스 디렉터리를 만들고 dist 전체를 업로드합니다.
  6. 새 릴리스의 권한을 정규화하고 필수 파일을 다시 확인합니다.
  7. 임시 심볼릭 링크를 만든 뒤 그 링크를 current 자리에 옮깁니다.
  8. Nginx 상태와 공개 주소를 검사하고, 실패하면 직전 릴리스로 되돌립니다.
  9. 모두 통과하면 최신 릴리스 5개만 남기고 오래된 릴리스를 정리합니다.

2번 검사가 왜 따로 필요한지는 깨진 링크를 넣어도 Astro 빌드가 성공한 통제 시험에 정리했습니다. 새 글을 배포할 때는 새 주소와 대표 이미지를 검사 대상으로 직접 넘깁니다.

npm run deploy -- --check-path=/new-post/ --check-path=/content/images/2026/09/new-post.webp

업로드 완료와 공개 완료는 서로 다른 사건입니다. 전송이 끝났더라도 검사를 통과하기 전까지는 새 릴리스를 공개하지 않습니다.

링크를 바꾸기 전의 파일·권한 검사

새 디렉터리가 존재한다는 사실만으로 완성된 릴리스라고 판단하지 않습니다. 업로드 직후에는 공개 전 상태에서 다음 조건을 검사합니다.

확인 항목 중단하는 경우
홈페이지 파일 index.html이 없음
오류 페이지 404.html이 없음
사이트맵 sitemap-index.xml이 없음
디렉터리 권한 755가 아님
일반 파일 권한 644가 아님
쓰기 권한 그룹 또는 기타 사용자가 쓸 수 있는 경로가 하나라도 있음

Windows에서 전송한 디렉터리 권한을 그대로 믿지 않고 새 릴리스 안에서만 디렉터리는 755, 일반 파일은 644로 맞춘 뒤 쓰기 권한이 남은 경로를 별도로 찾습니다. 이 문제를 처음 발견하고 자동화한 과정은 Astro 배포 파일 권한을 755·644로 고친 기록에 있습니다.

이 단계에서 실패하면 current는 아직 이전 릴리스를 가리키므로 공개 사이트를 되돌릴 작업도 없습니다. 불완전한 새 릴리스가 서버에 생겼을 뿐, 방문자가 보는 경로에는 연결되지 않은 상태입니다.

current를 지우지 않고 교체하는 방법

새 릴리스가 준비되면 임시 심볼릭 링크를 먼저 만들고, 그 링크를 기존 current 자리에 옮깁니다. 아래 코드는 실제 주소를 제거한 공개용 예시이며, RELEASE_ID는 배포 과정에서 생성된 값이라고 가정합니다.

base="/srv/example-site"
release="$base/releases/$RELEASE_ID"
temporary="$base/.current-$RELEASE_ID"

ln -s "$release" "$temporary"
mv -Tf "$temporary" "$base/current"

current를 먼저 삭제하고 새 링크를 만들면 두 명령 사이에 경로가 존재하지 않는 순간이 생깁니다. 대신 완성된 임시 링크를 같은 디렉터리에 만든 뒤 mv로 기존 링크를 교체하면, 같은 파일시스템에서 일반적인 이름 변경으로 처리되는 조건에서는 공개 링크가 비어 있는 중간 단계를 피할 수 있습니다.

GNU Coreutils 문서에서 ln -s는 대상 이름을 가리키는 심볼릭 링크를 만들고, 대부분의 파일 접근은 그 링크가 가리키는 대상으로 전달된다고 설명합니다. mv는 보통 이름 변경을 사용하지만 대상이 다른 파일시스템이면 복사와 삭제로 동작할 수 있습니다. 그래서 minml은 임시 링크와 current를 같은 배포 루트에 만들며, 이 교체 방식도 같은 파일시스템이라는 조건을 전제로 합니다.

-T는 목적지를 디렉터리로 취급하지 않게 하고, -f는 기존 current를 교체할 수 있게 합니다. 목적지가 디렉터리를 가리키는 심볼릭 링크일 때 해석이 달라질 수 있으므로, GNU 환경에서 mv -Tf로 링크 자체를 목적지로 명확히 지정했습니다.

공개 후 응답 검사

이 글을 처음 쓸 무렵의 배포에서 Astro는 28개 페이지를 만들었고, 별도 검증에서는 발행 글 22개, 내부 경로 32개와 로컬 이미지 23개를 확인했습니다. 그다음 새 릴리스에 파일을 올려 권한 검사를 통과한 뒤 current를 전환했습니다. 공개 후 결과는 다음과 같았습니다.

공개 후 확인 항목 기대값 결과
Nginx 서비스 실행 중 실행 중
홈페이지 200 200
새 글 200 200
새 대표 이미지 200 200
사이트맵 200 200
존재하지 않는 시험 주소 404 404
통합된 과거 글 주소 301 301
같은 서버의 별도 사이트 200 200

항목마다 확인하는 이유가 다릅니다. 새 글과 이미지는 이번 배포에 실제로 포함됐는지, 없는 주소는 모든 요청이 홈페이지로 열리는 잘못된 404 처리가 아닌지, 과거 주소는 통합한 글로 영구 이동하는지를 봅니다. 마지막 항목은 수정 대상이 아니며, 공용 Nginx 설정을 실수로 바꾸지 않았는지 확인하려고 응답만 읽습니다.

빌드 성공은 모든 공개 경로의 정상 응답을 보장하지 않습니다. 그래서 로컬 산출물 검사와 실제 공개 주소 검사를 서로 대체하지 않고 순서대로 실행합니다.

공개 검사 실패 시 롤백

배포를 시작할 때 기존 current의 실제 대상을 먼저 기록하는 이유가 여기에 있습니다. 새 릴리스로 교체한 뒤 하나라도 공개 검사가 실패하면 다음 순서로 복구합니다.

  1. 기록해둔 직전 릴리스가 실제 디렉터리인지 다시 확인합니다.
  2. 직전 릴리스를 가리키는 임시 롤백 링크를 만듭니다.
  3. 그 링크를 current 자리에 같은 방식으로 옮깁니다.
  4. current의 실제 대상이 직전 릴리스와 일치하는지 확인합니다.
  5. 배포 명령을 실패로 끝내 원인을 숨기지 않습니다.

새 릴리스는 즉시 삭제하지 않습니다. 공개 대상에서 분리된 상태로 남기면 어떤 파일이나 검사에서 실패했는지 조사할 수 있습니다. 공개 검사를 통과하지 못했으므로 오래된 릴리스를 정리하는 9번 단계도 실행하지 않습니다.

릴리스는 몇 개 남길까

릴리스 방식에서는 배포할 때마다 디렉터리가 하나씩 늘어납니다. 2026년 8월 28일 유지보수 점검에서 서버에 남은 릴리스는 23개였고, 실제 정리를 시작할 때는 배포가 한 번 더 있어 24개였습니다. 전체 크기는 약 355MB, 루트 디스크 사용률은 53%라 급한 상황은 아니었지만 보존 기준이 없었습니다. 같은 서버에 쌓인 배포본은 서버가 손상되면 함께 사라지므로 개수가 많다고 백업이 되지는 않습니다. 소스와 이미지 복구는 Astro 블로그 백업과 복구 방법에서 따로 다룹니다.

기준은 현재 공개 중인 릴리스를 포함한 최신 5개, 즉 현재 릴리스 하나와 직전 네 번의 배포 결과로 정했습니다. minml은 한 사람이 운영하는 정적 블로그이고, 원본 변경은 Git에 남으며 배포 직후 공개 주소를 자동으로 확인합니다. 이 조건이라면 일상적인 롤백에는 다섯 개로 충분하다고 판단했습니다. 배포가 잦거나 문제를 늦게 발견하는 사이트라면 더 많이 남겨야 할 수 있습니다.

삭제 전에 멈추는 조건

정리 스크립트는 삭제 후보를 계산하기 전에 다음 조건을 모두 요구하고, 하나라도 어긋나면 아무것도 지우지 않습니다.

  • 릴리스 루트 바로 아래에 디렉터리만 있는가
  • 모든 디렉터리 이름이 정해진 타임스탬프 형식인가
  • current의 실제 경로가 릴리스 루트 안에 있는가
  • 현재 릴리스가 이름순으로 가장 최신인가
  • 현재 릴리스에 홈페이지, 404와 사이트맵 파일이 있는가

처음 정리할 때는 여기에 더해 24개 모두가 필수 파일과 권한 기준을 통과하는 것도 확인했습니다.

네 번째 조건이 특히 중요했습니다. 장애 때문에 두세 단계 전 릴리스로 수동 롤백한 상태라면, 이름이 최신인 폴더부터 5개를 남기는 방식은 현재 운영 상황과 어긋납니다. 그래서 current를 링크 표시가 아니라 readlink -f로 확인한 실제 디렉터리로 비교합니다.

base="/srv/example-site"
release_root="$base/releases"
current="$(readlink -f "$base/current")"

case "$current" in
  "$release_root"/*) ;;
  *) exit 1 ;;
esac

현재 릴리스의 이름이 가장 최신 릴리스와 다를 때도 같은 방식으로 중단합니다. 상태가 예상과 다르면 자동화가 판단을 이어가지 않고 사람이 먼저 이유를 확인하게 됩니다.

드라이런과 삭제 방어 옵션

정리 명령은 옵션 없이 실행하면 아무것도 삭제하지 않고 집계만 출력합니다. 실제 릴리스 이름이나 서버 주소는 출력하지 않습니다.

npm run releases:prune
mode=dry-run
before_count=24
retained_count=5
pruned_count=19
pruned_bytes=280751828
after_count=24

after_count가 여전히 24인 것은 계산만 했기 때문입니다. 삭제 대상 19개와 약 281MB가 예상과 맞는지 확인한 뒤에야 --apply를 붙였습니다.

npm run releases:prune -- --apply

적용 모드에서도 후보마다 실제 경로를 다시 계산하고, 부모가 정확히 릴리스 루트인지와 현재 릴리스가 아닌지 확인한 뒤 지웁니다.

rm -rf --one-file-system --preserve-root=all -- "$verified_release"

GNU rm 문서에 따르면 --one-file-system은 재귀 삭제 중 명령 인자와 다른 파일시스템에 있는 디렉터리를 지우지 않고, --preserve-root=all은 부모와 다른 파일시스템에 있는 인자 자체를 거부합니다(2026년 9월 26일 확인). -- 뒤에는 이미 검증한 경로 하나만 넘깁니다. 이 옵션이 잘못된 경로를 바로잡아 주지는 않으므로, 앞의 경로·이름·현재 릴리스 조건이 실제 방어선입니다.

24개에서 5개로 줄인 결과

확인 항목 정리 전 정리 후
릴리스 개수 24개 5개
릴리스 전체 크기 약 355MB 약 75MB
제거한 릴리스 - 19개
확보한 크기 - 약 281MB
루트 디스크 사용률 53% 52%
쓰기 가능한 경로 0개 0개

디스크 사용률은 1%포인트만 줄었습니다. 용량 문제를 해결한 작업이라기보다, 24개가 40개, 50개로 늘기 전에 보존 기준과 중단 조건을 만든 작업이었습니다. 정리 직후에는 current 대상의 필수 파일과 Nginx 상태, 홈페이지·사이트맵 200, 시험 주소 404, 통합 주소 301을 다시 확인했고 모두 정상이었습니다.

지금은 이 정리가 배포 마지막 9번 단계로 자동 실행됩니다. 정리 단계가 실패해도 이미 공개 검사를 통과한 새 릴리스를 되돌리지는 않고 경고만 남깁니다. 사이트 배포 실패와 오래된 파일 정리 실패는 방문자에게 주는 영향이 다르기 때문입니다. 2026년 9월 26일 서버에서 다시 확인했을 때 남은 릴리스는 5개였습니다.

링크 교체로 해결되지 않는 것

current 교체는 업로드 중인 디렉터리가 그대로 노출되는 문제와 공개 경로가 비는 구간을 줄여줍니다. 그렇다고 배포 전체가 무조건 무중단이 되거나 새 콘텐츠가 올바르다는 뜻은 아닙니다.

  • 교체 전에 이미 시작된 요청은 이전 파일을 읽을 수 있습니다.
  • HTML을 받은 뒤 자산을 요청하는 사이에 링크가 바뀔 수 있으므로, 자산 파일명 충돌을 피하는 빌드 방식도 필요합니다.
  • 브라우저나 CDN 캐시는 교체 후에도 이전 응답을 잠시 보여줄 수 있습니다.
  • 잘못된 문장이나 노출되면 안 되는 정보도 정상적인 HTML이라면 그대로 배포될 수 있습니다.
  • 서버, 저장장치 또는 Nginx 자체의 장애는 릴리스 링크만으로 복구되지 않습니다.

minml에서는 Astro 빌드가 만든 해시 이름의 CSS 자산을 사용하고, 배포 전 링크 검사와 기술 글의 개인정보·서버 정보 검토를 별도로 수행합니다. 글 작성부터 배포까지의 전체 흐름은 Astro 블로그를 작성하고 배포하는 과정에 있습니다.

참고한 공식 문서