5. 배포/운영 (systemd, 로그, 헬스체크)

A. “인프라 포털 만들기” 시즌 1 — 5화 (마무리)

배포/운영 (systemd, 로그, 헬스체크)

포털은 “완성”보다 운영 가능성이 성패를 가른다. 운영자는 ‘멈췄을 때’보다 ‘이상할 때’가 더 무섭다. 그래서 관측 가능성이 핵심이다.

Case Study systemd Logging Health Check

시리즈 바로가기: 0화 · 1화 · 2화 · 3화 · 4화 · 5화(현재글)

개요(3줄 요약)
• 포털은 기능보다 살아있게 만드는 운영 루틴이 먼저다.
• systemd로 서비스 생명주기를 표준화하고, 로그/헬스체크로 장애를 빠르게 좁힌다.
• “죽었다”보다 “이상하다(느림/로그인 루프/부분 실패)”를 잡는 관측 설계가 핵심이었다.

목차

1. 왜 운영이 제일 어려웠나: 원인은 코드 밖에 있다
2. systemd 표준화: 관리 방식은 하나로
3. 로그 설계: “찾기 쉬운 로그”가 이긴다
4. 헬스체크/모니터링: 전체/부분 실패를 나눠 보기
5. 장애 대응 플레이북: 정해진 순서가 사람을 살린다
6. 시즌1 마무리 + 다음 시즌 예고
7. 레퍼런스/Tech Note 연결

1) 왜 운영이 제일 어려웠나: 원인은 코드 밖에 있다

개발은 “원인이 코드”인 경우가 많지만, 운영은 “원인이 환경/인증/네트워크/시간/권한”인 경우가 더 많다. 그래서 배포/운영은 기술보다 습관의 문제였다.

포털 운영에서 가장 중요하게 본 3가지

• 재시작이 쉬울 것: 서비스가 죽으면 “한 번에” 살릴 수 있어야 함
• 원인이 남을 것: 문제가 생기면 로그에 증거가 남아야 함
• 사전에 알 것: 사용자가 먼저 발견하기 전에 모니터링이 알려야 함

2) systemd 표준화: 관리 방식은 하나로

어떤 서비스는 pm2, 어떤 서비스는 nohup, 어떤 서비스는 수동 실행… 이렇게 되면 운영이 ‘사람의 기억’에 의존하게 된다. 그래서 가능한 구성 요소를 systemd로 표준화했다.

운영자 관점 결론: 서비스가 늘어날수록 “기술 스택”보다 “관리 방법의 단일화”가 더 중요해진다.

systemd로 표준화하면 좋아지는 것

• 재시작/상태 확인/로그 확인이 동일한 명령어로 통일
• 부팅 자동 시작, 장애 시 자동 재시작 같은 운영 옵션을 “코드 밖”에서 강제
• 변경/롤백 루틴이 문서화되기 쉬움(팀 운영)

# 운영자가 제일 자주 쓰는 루틴(예시) sudo systemctl restart portal-api sudo systemctl status portal-api --no-pager sudo journalctl -u portal-api -n 120 --no-pager

3) 로그 설계: “찾기 쉬운 로그”가 이긴다

운영 로그는 “많이 찍는 것”이 아니라 찾기 쉬운 것이 핵심이다. 인증/권한/프록시를 끼면, 문제의 원인이 서로를 가리기 쉽다.

로그를 “구간별로” 나눠두면 원인이 빨리 좁혀진다

• Nginx: 요청/응답/상태코드/리다이렉트/업스트림 시간
• API: 사용자/권한/파라미터/응답 시간/외부 연동 실패 원인
• 외부 연동: 타임아웃/인증 오류/쿼리 오류를 메시지로 명확히

“느림”을 잡을 때는 Nginx 로그 변수(request_time, upstream_*)가 진짜 강력하다.

4) 헬스체크/모니터링: 전체/부분 실패를 나눠 보기

포털은 “기능”보다 “가용성”이 중요하다. 한 번 안 열리면 사람들은 바로 기존 방식(각 시스템 접속)으로 돌아간다. 그래서 헬스체크를 최소 단위로 나눴다.

• 프론트: 정적 파일 서빙 여부(웹이 뜨는가)
• API: /health 같은 경량 엔드포인트(프로세스/의존성 최소)
• 외부 연동: SIEM/인텔리전스는 “별도 상태”로 표시(전체 죽음과 분리)

중요한 건 “전체가 죽었는지”만 보는 게 아니라, 어느 구간이 병목인지를 빨리 구분하는 것.

# (예시) 헬스체크 확인 루틴 curl -kI https://portal.example.com/portal/ curl -kI https://portal.example.com/api/health curl -kI https://portal.example.com/sec/health

5) 장애 대응 플레이북: 정해진 순서가 사람을 살린다

운영자는 장애가 났을 때 침착하게 “정해진 순서”대로 확인해야 한다. 그래서 포털을 만들면서 동시에 확인 순서도 문서화하기 시작했다.

내가 고정한 확인 순서(예시)

1. Nginx 상태 → 라우팅/상태코드/리다이렉트 확인
2. 인증 프록시 → 로그인 루프/세션/헤더 전달 확인
3. API 상태 → 헬스체크/로그 확인
4. 외부 연동 → 타임존/쿼리/권한/네트워크 경로 확인

포털은 팀의 도구가 되어야 한다. “나만 고칠 수 있는 서비스”는 운영에서 오래 못 간다.

6) 시즌1 마무리 + 다음 시즌 예고

시즌1은 “포털을 어떻게 시작했는가”를 기록했다. 아키텍처를 잡고, 정문(Nginx)을 세우고, 권한(RBAC)을 붙이고, 첫 화면(대시보드)을 만들고, 운영(systemd/로그/헬스체크)까지 정리했다.

다음 시즌(예고): 자동화와 데이터 파이프라인을 더 본격적으로 다룰 예정이다. 예) 일일 리포트 자동 생성, 데이터 수집/정규화, 운영 지표 표준화, 버튼 기반 실행/감사 로그 등.

7) 레퍼런스/Tech Note 연결

관련 Tech Note

• NGINX(1) — 설치/폴더 구성/운영 명령어
• NGINX(4) — auth_request로 RBAC 강제하기
• NGINX(5) — 운영 로그로 APM 만들기(느림 원인 분해)

공식 문서(레퍼런스)

• systemd.service(서비스 유닛)
• systemctl
• journalctl
• NGINX 공식 문서