콘텐츠로 이동
ZERO-ONE Wiki

운영 런북

서버 구성

Nginx가 도메인을 라우팅하고, 백엔드·프론트엔드가 각각 Docker 컨테이너로 실행됩니다.

  • api.zeroone.it.kr / test-api.zeroone.it.kr → 백엔드
  • zeroone.it.kr / test.zeroone.it.kr → 프론트엔드
  • 운영/SSH 등 관리 포트는 인프라 담당자 외 접속 제한, 기본 포트(3000·8080·22 등) 사용 회피.
  • 인프라는 AWS Lightsail 기반(+ On-Premise 구성도 보유).

배포

운영 반영은 항상 백엔드 → 프론트엔드 순서입니다. 프론트가 새 API/데이터 형태를 기대하므로 백엔드가 먼저 운영에서 정상 동작해야 합니다.

백엔드 (Jenkins → GitHub Actions 이관 중)

  1. PR에 release:patch / release:minor / release:major 중 정확히 하나의 라벨을 붙입니다.
  2. Jenkins(또는 이관된 Actions)에서 운영 배포 실행 → migration 검증 → 이미지 빌드 → 운영 반영.
  3. 배포 성공 확인 (이 단계만으로 FE 릴리스 기록이 생기지는 않음).

프론트엔드

  1. develop → main PR에 release 라벨 하나를 붙이고 CI 통과 확인 후 머지.
  2. GitHub Actions(deploy-prod.yml)가 라벨 확인 → 버전 계산 → Docker 이미지 빌드 → 운영 배포 → health/smoke check.
  3. 성공 시 releases/prod-YYYYMMDD-HHmm.yaml에 **최종 운영 조합(Frontend + Backend + DB + Rollback target)**을 기록.

릴리스 기록 / 버전 규칙

  • release intent는 PR에서 계산: patch v1.0.0→1.0.1, minor→1.1.0, major→2.0.0. hotfix 라벨은 쓰지 않습니다.
  • 이미지 태그는 불변·날짜 미포함: zeroone-frontend:vMAJOR.MINOR.PATCH-shortCommit.
  • prod / latest-prod는 움직이는 pointer 태그 — 배포 식별·롤백 대상으로 절대 사용 금지.
  • 운영 배포 순서: db_migration → backend → backend_health_check → frontend → e2e_check.

QA · 카나리

  • QA 원칙은 Shift-Left(기획 단계부터 품질 개입)와 Shift-Right(실제와 같은 환경 검증)를 함께 따릅니다.
  • 카나리 릴리스: 전체가 아닌 일부(1%)에 먼저 노출해 검증. QA 실배포 시에도 운영 컨테이너는 건드리지 않고 임시 포트·격리 DB 카나리로 먼저 검증 후 적용합니다.
  • 배포 시 기능 점검에 그치지 않고 “내가 유저라면” 관점으로 직접 사용해 본 뒤 배포합니다.

모니터링

  • 에러 모니터링은 Glitchtip(Sentry 호환) 사용 예정. 현재 외부 키(Sentry/Glitchtip·Slack·Notion·Claude)는 미등록 상태로 키가 없으면 skip 처리됩니다.
  • 배포 알림은 Slack(Jenkins CI 연동, PR 알림 채널)으로 전달됩니다.

롤백

releases/에 기록된 고정 이미지 태그 기준으로 롤백합니다.

  1. 실패 직전의 최신 성공 릴리스 YAML을 엽니다.
  2. rollback.app_rollback_target의 고정 frontend/backend 이미지 태그를 복사.
  3. 해당 고정 이미지를 배포 → 백엔드 health check → 프론트 smoke/E2E check.
  4. 결과를 새 releases/prod-*.yaml로 기록.

규칙:

  • prod/latest-prod로 롤백하지 않습니다 (고정 태그만).
  • 근거가 없으면 frontend/backend를 호환 조합으로 함께 롤백.
  • 파괴적 DB 롤백은 자동 실행하지 않으며, migration 호환성이 불확실하면 앱 이미지 교체 전 멈추고 확인.

장애 대응 시작점

  1. 최신 releases/prod-*.yaml을 열어 현재 운영 backend/frontend 이미지 확인.
  2. DB migration 상태 확인.
  3. rollback.app_rollback_target 고정 태그 확인 (pointer 태그 사용 금지).
  4. 상세 절차는 docs/ops/version-management.md 롤백 가이드 참조.

장애 후에는 근본 원인 분석·재발 방지·지식 공유를 위해 Incident Review를 문서로 남깁니다 (예: AWS malware 감염, 운영 서버 이전 중 이미지 삭제, 브랜치 미분리로 선택 배포 불가 등 사례 축적).

원문: