TIL - 20260526

juni·2026년 5월 26일

TIL

목록 보기

362/468

0526 웹 마스터 실전 (10/N): 운영 자동화와 문서화

✅ 1. 운영 자동화란 무엇인가?

운영 자동화란 사람이 반복적으로 처리하던 서버 관리, 배포, 백업, 모니터링, 알림, 로그 정리 같은 작업을 스크립트나 도구를 통해 자동으로 실행되게 만드는 것입니다.
웹사이트 운영에서는 작은 반복 작업이 계속 쌓입니다.
처음에는 사람이 직접 처리해도 괜찮아 보이지만, 서비스가 커지거나 관리해야 할 페이지와 서버가 늘어나면 수동 작업은 실수와 장애의 원인이 됩니다.

➕ 1-1. 운영 자동화가 중요한 이유

실수 감소
- 사람이 매번 명령어를 직접 입력하면 오타, 누락, 순서 실수가 발생할 수 있습니다.
- 자동화 스크립트를 사용하면 정해진 순서대로 일관되게 실행할 수 있습니다.
시간 절약
- 반복 작업을 줄이면 개발자는 신규 기능 개발, 장애 분석, 성능 개선에 더 집중할 수 있습니다.
운영 안정성 향상
- 백업, 로그 정리, 헬스체크, 알림 같은 작업이 자동으로 실행되면 문제를 더 빨리 발견하고 대응할 수 있습니다.
인수인계와 협업에 유리
- 자동화된 작업은 문서와 스크립트로 남기기 쉽습니다.
- 특정 사람만 알고 있는 수동 절차를 줄일 수 있습니다.

✅ 2. 자동화해야 할 주요 운영 업무

➕ 2-1. 배포 자동화

배포 자동화는 소스코드 변경 사항을 서버에 반영하는 과정을 자동화하는 것입니다.
수동 배포는 실수가 잦고, 장애 발생 시 어떤 단계에서 문제가 생겼는지 추적하기 어렵습니다.
수동 배포에서 자주 생기는 문제
- 최신 코드를 pull하지 않음
- 빌드 명령어 누락
- 환경변수 반영 누락
- 서버 재시작 누락
- 빌드 파일 경로 실수
- 프론트엔드와 백엔드 배포 순서 오류
자동화 예시
- GitHub Actions로 빌드 및 배포
- AWS CodeDeploy 사용
- 배포 쉘 스크립트 작성
- Docker 이미지 빌드 후 배포
- PM2 reload 자동 실행

#!/bin/bash

echo "배포 시작"

cd /home/ubuntu/app

git pull origin main

npm install

npm run build

pm2 reload app

echo "배포 완료"

위 스크립트는 단순한 예시입니다.
실무에서는 실패했을 때 배포를 중단하고, 로그를 남기고, 필요하면 롤백할 수 있도록 구성해야 합니다.

➕ 2-2. 백업 자동화

DB 백업, 업로드 파일 백업, 서버 설정 백업은 수동으로 하면 빼먹기 쉽습니다.
백업은 반드시 자동화하고, 백업 성공 여부를 확인할 수 있어야 합니다.
자동화 기준
- 정해진 시간에 백업 실행
- 백업 파일명에 날짜와 시간 포함
- 외부 저장소에 업로드
- 오래된 백업 자동 삭제
- 실패 시 관리자에게 알림

#!/bin/bash

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/db"
DB_NAME="app_db"

mkdir -p $BACKUP_DIR

mysqldump -u root -p$DB_PASSWORD $DB_NAME > $BACKUP_DIR/db_$DATE.sql

aws s3 cp $BACKUP_DIR/db_$DATE.sql s3://my-backup-bucket/db/

find $BACKUP_DIR -type f -mtime +7 -delete

주의할 점
- 비밀번호를 스크립트에 직접 적지 않는 것이 좋습니다.
- 환경변수나 별도 설정 파일을 사용해야 합니다.
- 백업 파일이 실제로 복구 가능한지도 정기적으로 확인해야 합니다.

➕ 2-3. 로그 정리 자동화

서버를 운영하면 access log, error log, application log 등이 계속 쌓입니다.
로그를 관리하지 않으면 디스크가 가득 차서 서버 장애가 발생할 수 있습니다.
자동화 대상
- 오래된 로그 압축
- 일정 기간 지난 로그 삭제
- 로그 파일 크기 제한
- 에러 로그 별도 보관
- 로그 외부 저장소 업로드

# 30일 이상 지난 로그 삭제 예시
find /var/log/myapp -type f -name "*.log" -mtime +30 -delete

리눅스 환경에서는 logrotate를 사용해 로그 파일을 주기적으로 분리하고 압축할 수 있습니다.

/var/log/myapp/*.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
}

➕ 2-4. 헬스체크 자동화

헬스체크(Health Check)는 서버나 API가 정상적으로 동작하는지 확인하는 기능입니다.
운영 중인 서비스에서는 단순히 서버가 켜져 있는지만 보는 것이 아니라, 실제 API와 DB 연결까지 정상인지 확인하는 것이 좋습니다.
헬스체크 API 예시

import { Controller, Get } from '@nestjs/common';

@Controller('health')
export class HealthController {
  @Get()
  check() {
    return {
      status: 'ok',
      timestamp: new Date().toISOString(),
    };
  }
}

확장 가능한 체크 항목
- 서버 프로세스 상태
- DB 연결 상태
- Redis 연결 상태
- 외부 API 연결 상태
- 디스크 용량
- 메모리 사용량
헬스체크 URL은 UptimeRobot, AWS Route 53 Health Check, CloudWatch 등과 연결하면 장애 알림에 활용할 수 있습니다.

✅ 3. 알림 자동화

운영자는 장애가 발생했을 때 빠르게 알아야 합니다.
사용자가 먼저 전화하거나 문의하기 전에 시스템이 먼저 알려주는 구조가 좋습니다.

➕ 3-1. 알림이 필요한 상황

사이트 접속 불가
API 500 에러 증가
서버 CPU 사용률 급증
메모리 부족
디스크 용량 부족
DB 연결 실패
SSL 인증서 만료 임박
백업 실패
결제/상담 신청 실패 증가

➕ 3-2. 알림 도구 예시

Slack
- 개발팀이나 운영자가 실시간으로 알림을 받기 좋습니다.
Email
- 중요 알림이나 정기 리포트에 적합합니다.
SMS / 카카오 알림
- 즉시 대응이 필요한 장애 알림에 적합합니다.
AWS CloudWatch Alarm
- AWS 리소스 지표 기반 알림을 구성할 수 있습니다.
Sentry Alert
- 프론트엔드/백엔드 오류 발생 시 알림을 받을 수 있습니다.

✅ 4. 운영 문서화란 무엇인가?

운영 문서화란 서버, 배포, 장애 대응, 백업, 계정, 외부 API, 도메인, SSL, 데이터베이스 등 서비스 운영에 필요한 정보를 문서로 정리하는 작업입니다.
문서화는 귀찮아 보이지만, 실무에서는 매우 중요한 역량입니다.
특히 혼자서 많은 업무를 담당하는 개발자일수록 문서화가 곧 자신의 업무 방어력이 됩니다.

➕ 4-1. 문서화가 중요한 이유

장애 대응 속도 향상
- 문제가 생겼을 때 어디를 확인해야 하는지 바로 알 수 있습니다.
인수인계 가능
- 나만 아는 운영 지식이 줄어듭니다.
- 휴가, 퇴사, 협업 상황에서도 서비스 운영이 가능해집니다.
연봉협상과 경력기술서에 활용 가능
- 운영 문서는 내가 어떤 책임을 맡고 있는지 보여주는 근거가 됩니다.
- 단순 개발자가 아니라 서비스 운영까지 책임지는 개발자라는 증거가 됩니다.
반복 질문 감소
- 자주 묻는 내용이나 반복 절차를 문서화하면 같은 설명을 반복하지 않아도 됩니다.

✅ 5. 반드시 작성해야 할 운영 문서

➕ 5-1. 서버 구성 문서

어떤 서버가 어떤 역할을 하는지 정리합니다.

## 서버 구성

### Production Server
- Provider: AWS EC2
- OS: Ubuntu
- Role: 웹 서버 + API 서버
- Web Server: Nginx
- Runtime: Node.js
- Process Manager: PM2
- Domain: www.example.com

### Database
- Type: MySQL
- Provider: AWS RDS
- Backup: 자동 백업 7일 보관

포함하면 좋은 항목
- 서버 제공업체
- 서버 역할
- 운영체제
- 사용 포트
- 도메인 연결 정보
- SSL 적용 방식
- 배포 위치
- 로그 위치

➕ 5-2. 배포 절차 문서

배포 절차는 반드시 문서화해야 합니다.
자동화가 되어 있더라도 어떤 순서로 동작하는지 알아야 장애 시 대응할 수 있습니다.

## 배포 절차

### 프론트엔드
1. main 브랜치 최신 코드 확인
2. 의존성 설치
3. 빌드 실행
4. 빌드 결과물 서버 업로드
5. Nginx 정적 파일 경로 확인
6. 메인 페이지 접속 확인

### 백엔드
1. main 브랜치 최신 코드 확인
2. 의존성 설치
3. 빌드 실행
4. 환경변수 확인
5. PM2 reload
6. API health check 확인

➕ 5-3. 장애 대응 문서

장애가 발생했을 때 확인할 순서와 명령어를 정리합니다.
장애 대응 문서가 있으면 당황하지 않고 순서대로 점검할 수 있습니다.

## 502 오류 대응

### 확인 순서
1. PM2 프로세스 상태 확인
2. 애플리케이션 로그 확인
3. Nginx error log 확인
4. 포트 Listen 상태 확인
5. 최근 배포 내역 확인

### 명령어
pm2 list
pm2 logs
sudo tail -f /var/log/nginx/error.log
sudo lsof -i :3000

➕ 5-4. 외부 API 연동 문서

외부 API는 장애와 변경 가능성이 있기 때문에 문서화가 중요합니다.
광고 추적, 본인인증, 문자 발송, 결제, 통신사 API 등은 특히 운영 영향도가 큽니다.

## 외부 API 연동 문서

### API 이름
- 서비스명: 문자 발송 API
- 용도: 상담 신청 완료 문자 발송
- 인증 방식: API Key
- 호출 위치: backend/src/sms
- 실패 시 영향: 고객에게 안내 문자 미발송

### 장애 대응
1. API 응답 코드 확인
2. 관리자 콘솔 장애 공지 확인
3. 재시도 가능 여부 확인
4. 실패 건 별도 저장 여부 확인

➕ 5-5. 계정 및 권한 문서

운영에 필요한 계정과 권한을 정리해야 합니다.
단, 비밀번호나 API 키를 문서에 그대로 적으면 안 됩니다.
문서화할 항목
- AWS 계정
- GitHub Organization
- 도메인 관리 계정
- Google Analytics
- Google Search Console
- 광고 관리자 계정
- 외부 API 관리자 계정
- 서버 접속 권한자

## 계정 및 권한 관리

### AWS
- 용도: 서버, S3, CloudFront, RDS 관리
- 접근 권한자: 관리자, 개발자
- MFA 적용 여부: 적용 필요
- 비밀번호 저장 위치: 별도 비밀번호 관리 도구

### GitHub
- 용도: 소스코드 관리
- 권한 정책: 최소 권한 부여
- 퇴사자 발생 시 권한 회수 필요

✅ 6. 실무에서 유용한 자동화 도구

➕ 6-1. GitHub Actions

GitHub 저장소와 연동해 테스트, 빌드, 배포를 자동화할 수 있습니다.
프론트엔드 빌드, 백엔드 테스트, Docker 이미지 빌드, 서버 배포 등에 활용됩니다.

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Install dependencies
        run: npm install

      - name: Build project
        run: npm run build

➕ 6-2. PM2

PM2는 Node.js 애플리케이션을 운영할 때 자주 사용하는 프로세스 매니저입니다.
서버 재시작, 로그 확인, 프로세스 상태 확인, 자동 재시작 등에 활용됩니다.

# 프로세스 목록 확인
pm2 list

# 로그 확인
pm2 logs

# 앱 재시작
pm2 restart app

# 서버 재부팅 후 자동 실행 설정
pm2 startup
pm2 save

➕ 6-3. Docker

Docker는 애플리케이션 실행 환경을 컨테이너로 관리하는 도구입니다.
개발 환경과 운영 환경 차이를 줄이고, 배포를 더 일관되게 만들 수 있습니다.
장점
- 실행 환경 표준화
- 서버 이전이 쉬움
- 의존성 충돌 감소
- 배포 자동화와 궁합이 좋음

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

RUN npm run build

CMD ["npm", "run", "start:prod"]

➕ 6-4. Notion / Wiki

운영 문서는 Notion, Confluence, GitHub Wiki, README 등으로 관리할 수 있습니다.
중요한 것은 도구보다 최신 상태를 유지하는 것입니다.
문서 관리 기준
- 문서 제목을 명확하게 작성
- 마지막 수정일 표시
- 담당자 표시
- 실제 명령어와 경로 포함
- 변경사항 발생 시 바로 수정
- 오래된 문서는 폐기 또는 업데이트

✅ 7. 자동화와 문서화 시 주의할 점

➕ 7-1. 자동화 스크립트를 맹신하지 않기

자동화는 편리하지만, 잘못 작성된 자동화는 빠르게 큰 장애를 만들 수 있습니다.
특히 배포, DB 마이그레이션, 파일 삭제, 백업 삭제 작업은 조심해야 합니다.
주의할 명령어
- rm -rf
- DB DROP, DELETE, UPDATE
- 대량 파일 이동
- 운영 서버 직접 배포
- 권한 변경 명령어

➕ 7-2. 비밀정보를 문서나 코드에 남기지 않기

API Key, DB 비밀번호, JWT Secret, AWS Secret Key 같은 정보는 절대 문서나 Git 저장소에 그대로 남기면 안 됩니다.
관리 방법
- .env 사용
- .env.example만 Git에 포함
- AWS Secrets Manager 사용
- GitHub Actions Secrets 사용
- 비밀번호 관리 도구 사용

➕ 7-3. 문서는 짧고 실제로 쓸 수 있게 작성하기

운영 문서는 길고 멋진 글보다, 장애 상황에서 바로 사용할 수 있어야 합니다.
누가 봐도 따라 할 수 있게 명령어, 경로, 확인 기준을 명확히 적는 것이 좋습니다.

✅ 8. 1인 개발자에게 특히 중요한 운영 습관

1인 개발자는 개발, 배포, 운영, 장애 대응, 문서화까지 모두 맡는 경우가 많습니다.
그래서 머릿속에만 알고 있는 정보가 많아질수록 위험합니다.

➕ 8-1. 최소한의 운영 루틴

배포 후 체크리스트 작성
장애 발생 시 기록 남기기
반복 작업은 스크립트로 만들기
서버 접속 명령어 정리
외부 API 연동 위치 정리
백업과 복구 절차 정리
관리자 페이지 기능 목록 정리
광고/SEO/분석 태그 적용 위치 정리

➕ 8-2. 경력 관리 관점에서의 의미

자동화와 문서화는 단순 잡무가 아닙니다.
회사 입장에서는 “이 사람이 없으면 운영이 흔들린다”는 느낌보다, “이 사람이 운영 체계를 만들었다”는 평가가 더 좋습니다.
특히 연봉협상이나 이직 시에는 다음과 같이 표현할 수 있습니다.

- 배포 절차를 문서화하고 반복 작업을 스크립트화하여 운영 실수를 줄임
- 서버 장애 대응 체크리스트를 정리하여 장애 원인 파악 시간을 단축
- 백업 및 복구 절차를 정리하고 자동 백업 구조를 개선
- 외부 API 연동 구조와 장애 대응 방식을 문서화하여 유지보수성을 향상

📌 요약

운영 자동화는 배포, 백업, 로그 정리, 헬스체크, 알림 같은 반복 업무를 스크립트나 도구로 자동 실행되게 만드는 작업입니다.
자동화는 실수를 줄이고, 시간을 절약하며, 서비스 운영 안정성을 높여줍니다.
운영 문서화는 서버 구성, 배포 절차, 장애 대응, 외부 API, 계정 및 권한 정보를 정리하는 작업입니다.
문서화는 장애 대응, 인수인계, 협업, 경력기술서 작성에 모두 도움이 됩니다.
GitHub Actions, PM2, Docker, cron, CloudWatch, Notion/Wiki 같은 도구를 활용하면 운영 업무를 체계화할 수 있습니다.
자동화 스크립트에는 삭제, 배포, DB 변경처럼 위험한 작업이 포함될 수 있으므로 반드시 검증과 로그를 함께 구성해야 합니다.
1인 개발자일수록 머릿속에만 있는 운영 지식을 문서와 스크립트로 남기는 습관이 중요합니다.

juni

이전 포스트

TIL - 20260525

다음 포스트

TIL - 20260526

TIL

0526 웹 마스터 실전 (10/N): 운영 자동화와 문서화

✅ 1. 운영 자동화란 무엇인가?

➕ 1-1. 운영 자동화가 중요한 이유

✅ 2. 자동화해야 할 주요 운영 업무

➕ 2-1. 배포 자동화

➕ 2-2. 백업 자동화

➕ 2-3. 로그 정리 자동화

➕ 2-4. 헬스체크 자동화

✅ 3. 알림 자동화

➕ 3-1. 알림이 필요한 상황

➕ 3-2. 알림 도구 예시

✅ 4. 운영 문서화란 무엇인가?

➕ 4-1. 문서화가 중요한 이유

✅ 5. 반드시 작성해야 할 운영 문서

➕ 5-1. 서버 구성 문서

➕ 5-2. 배포 절차 문서

➕ 5-3. 장애 대응 문서

➕ 5-4. 외부 API 연동 문서

➕ 5-5. 계정 및 권한 문서

✅ 6. 실무에서 유용한 자동화 도구

➕ 6-1. GitHub Actions

➕ 6-2. PM2

➕ 6-3. Docker

➕ 6-4. Notion / Wiki

✅ 7. 자동화와 문서화 시 주의할 점

➕ 7-1. 자동화 스크립트를 맹신하지 않기

➕ 7-2. 비밀정보를 문서나 코드에 남기지 않기

➕ 7-3. 문서는 짧고 실제로 쓸 수 있게 작성하기

✅ 8. 1인 개발자에게 특히 중요한 운영 습관

➕ 8-1. 최소한의 운영 루틴

➕ 8-2. 경력 관리 관점에서의 의미

📌 요약

TIL - 20260525

TIL - 20260527

0개의 댓글