스테이징에서 라이브까지 안전하게 동기화하는 체크리스트

요약

AI와 함께 개발하고 운영하면 글 작성, 코드 수정, 빌드, 배포까지 이어지는 속도가 매우 빨라집니다. 하지만 속도가 빨라질수록 더 중요해지는 것은 “어디까지가 작업본이고, 어디부터가 독자가 보는 라이브인가”를 명확히 구분하는 일입니다. Futory는 Next.js 기반 Markdown 블로그이고, 새 글은 스테이징 경로의 content/posts/*.md에 먼저 추가됩니다. 그다음 테마 검증, 콘텐츠 검증, 빌드 검증을 통과해야 호스트 라이브 경로로 동기화되고 PM2 재시작까지 이어집니다.

이 과정에서 가장 위험한 실수는 새 글 하나만 배포한다고 생각하다가 라이브에만 남아 있던 기능을 삭제하거나, 빌드가 깨진 상태로 PM2를 재시작하는 것입니다. 특히 Futory에는 다크/라이트 모드 토글, app/theme-init.tsx, CSS의 data-theme 변수처럼 글 작성과 직접 관련 없어 보이지만 반드시 유지해야 하는 사용자 경험이 있습니다. 콘텐츠 운영 자동화는 글을 잘 쓰는 것만으로 끝나지 않고, 기존 기능을 보존하면서 새 글을 안전하게 반영하는 절차까지 포함해야 합니다.

이 글은 Futory 운영 맥락에서 스테이징에서 라이브까지 동기화할 때 확인해야 할 기준을 정리한 체크리스트입니다.

스테이징과 라이브를 분리해야 하는 이유

스테이징은 실험과 검증을 위한 공간입니다. AI에게 새 글을 쓰게 하거나, Markdown frontmatter를 조정하거나, 콘텐츠 구조를 바꾸는 작업은 먼저 스테이징에서 이루어져야 합니다. 이 단계에서는 실패해도 독자에게 영향을 주지 않습니다. 반대로 라이브는 이미 공개된 블로그입니다. 라이브 경로의 파일은 독자가 보는 페이지와 연결되어 있고, PM2와 Nginx 뒤에서 실제 요청을 처리합니다.

Futory 같은 Markdown 블로그에서는 글 파일 하나가 곧 페이지 하나가 됩니다. 그래서 content/posts에 새 파일이 추가되는 작업은 단순한 문서 저장이 아니라 공개 페이지 생성으로 이어집니다. 제목, 날짜, 카테고리, 태그, 본문 구조가 잘못되면 목록 페이지나 상세 페이지 품질에 바로 영향을 줍니다. 또한 Next.js 빌드 과정에서 예상하지 못한 오류가 생기면 새 글뿐 아니라 전체 사이트 배포가 막힐 수 있습니다.

스테이징과 라이브를 분리하면 이런 문제를 배포 전에 잡을 수 있습니다. AI가 생성한 글이 중복 주제인지, 오늘 날짜가 맞는지, 바이브코딩 카테고리 안에서 기존 연재 흐름과 이어지는지 확인할 수 있습니다. 라이브 반영은 그다음 단계입니다.

새 글을 추가하기 전에 보는 것들

자동 게시에서 첫 번째 기준은 시간입니다. Futory는 한국 시간 기준으로 하루 한 번만 글을 게시합니다. 서버 cron이 UTC 기준으로 실행되더라도 운영 판단은 KST 날짜와 시간으로 해야 합니다. 오늘 선택된 게시 시간이 아니라면 아무 작업도 하지 않는 것이 맞고, 이미 오늘 날짜의 글이 있다면 중복 게시를 막아야 합니다.

두 번째 기준은 기존 글과의 관계입니다. 이미 Futory에는 AI 코딩 도구 비교, 프롬프트를 요구사항으로 바꾸는 방법, Next.js와 PM2 배포 흐름, Git 롤백 전략, 자동 게시 실패 신호 같은 글이 쌓여 있습니다. 새 글은 이 목록을 읽고 빈자리를 찾아야 합니다. 여러 카테고리로 넓히기보다 바이브코딩 카테고리 안에서 AI 개발, 자동화, 배포, 운영이라는 하나의 축을 깊게 쌓는 것이 현재 전략입니다.

세 번째 기준은 파일명과 frontmatter입니다. slug는 영문 소문자 kebab-case로 만들고, 날짜는 오늘 KST 날짜로 넣어야 합니다. category는 반드시 바이브코딩이어야 하며, tags는 글의 검색 의도와 운영 맥락을 함께 담아야 합니다. 이런 작은 규칙은 나중에 목록 정렬, sitemap, 검색 노출, 내부 링크 설계의 기반이 됩니다.

동기화에서 가장 조심해야 할 부분

스테이징에서 검증이 끝나면 라이브 경로로 파일을 동기화합니다. 이때 rsync --delete 같은 방식은 편리하지만 조심해야 합니다. 스테이징에 없는 파일이 라이브에서 삭제될 수 있기 때문입니다. Futory 운영에서는 .git, node_modules, .next, .env를 제외하고 동기화해야 하며, 특히 .env는 라이브 서버의 실제 환경 값을 담고 있으므로 덮어쓰면 안 됩니다.

또 하나 중요한 점은 글과 무관해 보이는 기능 보존입니다. 다크/라이트 모드 토글은 콘텐츠 파일이 아니지만, 블로그 사용 경험에 직접 영향을 줍니다. 과거에 스테이징 기준으로 전체 동기화를 하면서 라이브에만 있던 테마 관련 파일이 사라질 위험이 있었기 때문에, 지금은 npm run test:theme가 필수 검증 단계입니다. 이 테스트는 components/ThemeToggle.tsx, app/theme-init.tsx, CSS의 data-theme 변수 같은 핵심 요소가 유지되는지 확인하는 안전장치입니다.

즉, 동기화의 목표는 “스테이징을 그대로 라이브에 덮어쓰기”가 아닙니다. 목표는 검증된 변경만 반영하면서 라이브 운영에 필요한 설정과 기존 기능을 보존하는 것입니다. 자동화가 이 기준을 지키지 못하면 빠른 배포가 아니라 빠른 장애가 됩니다.

배포 전 검증 순서

Futory의 기본 검증 순서는 npm run test:theme, npm run test:content, npm run build입니다. 이 순서는 각각 다른 위험을 막습니다.

테마 검증

테마 검증은 기존 UI 기능이 사라지지 않았는지 확인합니다. 콘텐츠 자동화에서는 글 파일만 보고 싶어지지만, 실제 배포는 전체 앱을 대상으로 합니다. 따라서 테마 토글, 초기 테마 스크립트, CSS 변수처럼 사이트 경험을 구성하는 파일도 함께 확인해야 합니다.

콘텐츠 검증

콘텐츠 검증은 Markdown 글의 기본 품질을 확인합니다. frontmatter에 title, description, date, category, tags가 있는지, 날짜 형식이 올바른지, FAQ와 결론이 포함되어 있는지, 글의 분량이 충분한지 확인합니다. AI가 쓴 글은 자연스러워 보여도 규칙 하나를 빠뜨릴 수 있기 때문에 자동 검증이 필요합니다.

빌드 검증

빌드 검증은 Next.js 앱이 실제 배포 가능한 상태인지 확인합니다. 새 글의 Markdown 문법, import 오류, 정적 생성 과정의 문제는 이 단계에서 드러납니다. 빌드가 실패하면 라이브 동기화와 PM2 재시작은 중단해야 합니다. 기존 서비스가 정상이라면 실패한 새 배포를 밀어 넣지 않는 것이 더 안전합니다.

PM2와 Nginx까지 포함해 확인하기

호스트에서 파일 동기화가 끝났다고 배포가 끝난 것은 아닙니다. 라이브 경로에서 의존성을 설치하고, 다시 테마 검증과 콘텐츠 검증, 빌드를 통과한 뒤 PM2 프로세스를 재시작해야 합니다. Futory의 PM2 프로세스는 futory-wordblog이고 내부 포트는 127.0.0.1:8042입니다. PM2 재시작 후에는 프로세스가 실제로 살아 있는지 확인해야 합니다.

Nginx는 공개 도메인과 내부 앱을 연결합니다. 내부 포트가 정상이어도 Nginx 설정이나 프록시 문제로 공개 URL에서 실패할 수 있습니다. 그래서 마지막 검증은 항상 공개 도메인에서 해야 합니다. https://futory.oig.kr/posts가 200으로 응답하고, 새 글의 /posts/<slug> URL도 200으로 열리며, 오늘 날짜가 페이지에 노출되어야 합니다.

이 단계는 운영 보고의 기준이 됩니다. “빌드가 성공했다”와 “독자가 새 글을 볼 수 있다”는 다른 말입니다. 자동화가 공개 확인까지 마쳤을 때만 게시 성공이라고 말할 수 있습니다.

운영 리포트에 남길 내용

자동 배포 후 보고는 짧아도 충분하지만, 핵심 정보는 빠지면 안 됩니다. 새 글 제목, 날짜, URL, 스테이징 검증 결과, 호스트 검증 결과, 공개 URL 확인 결과를 남기면 나중에 문제가 생겼을 때 추적하기 쉽습니다. 반대로 선택된 시간이 아니라서 건너뛴 경우에는 SKIP: not selected hour, 이미 오늘 글이 있는 경우에는 SKIP: already published today처럼 한 줄로 충분합니다.

좋은 리포트는 자동화의 신뢰를 높입니다. 매일 같은 시간대에 실행되는 작업이라도 어떤 날은 스킵되고, 어떤 날은 게시되고, 어떤 날은 검증 실패로 멈출 수 있습니다. 상태를 명확히 구분하면 운영자는 불필요하게 서버에 접속하지 않아도 되고, 실제로 봐야 할 실패에만 집중할 수 있습니다.

자주 묻는 질문

스테이징 검증을 통과했으면 호스트 검증은 생략해도 되나요?

생략하지 않는 것이 좋습니다. 스테이징과 호스트는 경로, 설치된 의존성, 환경 변수, PM2 실행 상태가 다를 수 있습니다. 스테이징 검증은 배포 전 안전장치이고, 호스트 검증은 실제 서비스 환경에서의 안전장치입니다.

글 하나만 추가했는데 빌드까지 해야 하나요?

해야 합니다. Markdown 글 하나도 Next.js 정적 생성 과정에 영향을 줄 수 있습니다. frontmatter 오류나 본문 문법 문제로 빌드가 실패할 수 있기 때문에, 글 추가 역시 전체 앱 빌드 기준으로 확인해야 합니다.

동기화할 때 .env를 제외하는 이유는 무엇인가요?

.env는 라이브 서버의 실제 환경 설정을 담고 있을 가능성이 높습니다. 스테이징 값으로 덮어쓰면 데이터베이스, API 키, 포트, 분석 설정 등이 바뀔 수 있습니다. 자동 배포에서는 기존 .env를 보존하는 것이 기본입니다.

공개 URL 확인이 실패하면 어떻게 해야 하나요?

먼저 PM2 프로세스와 내부 포트가 정상인지 확인하고, 그다음 Nginx 프록시와 도메인 응답을 나누어 봐야 합니다. 내부는 정상인데 공개 도메인만 실패한다면 Nginx, 인증서, 방화벽, 프록시 설정을 확인하는 순서가 좋습니다.

결론

스테이징에서 라이브까지의 동기화는 단순한 파일 복사가 아닙니다. AI가 만든 결과를 운영 가능한 상태로 바꾸는 마지막 과정입니다. Futory에서는 새 글 작성, 중복 방지, frontmatter 규칙, 테마 검증, 콘텐츠 검증, Next.js 빌드, 호스트 동기화, PM2 재시작, 공개 URL 확인이 하나의 배포 체인으로 이어집니다.

이 체인이 안정적으로 작동하려면 자동화가 빠르게 움직이면서도 멈출 지점을 알아야 합니다. 선택 시간이 아니면 건너뛰고, 오늘 글이 있으면 중복을 막고, 검증이 실패하면 배포하지 않고, 공개 URL이 확인되어야만 성공으로 보고해야 합니다. 이런 기준이 쌓일수록 Futory는 단순한 블로그가 아니라 AI와 함께 만들고, 자동화하고, 운영하는 과정을 신뢰할 수 있게 기록하는 실험장이 됩니다.