콘텐츠로 이동

인수 체크리스트

인수받은 팀이 Day 0(접근 검증)부터 Week 4(운영 능력 검증)까지 따라가는 단계별 체크리스트. 각 항목은 실제 명령 + 기대 결과를 포함한다 — [ ] 항목을 검토하면서 위키 본문(특히 운영 런북)을 cross-reference하면 시스템에 익숙해지는 효과를 함께 노릴 수 있다.

0. 사전 합의 (인수 전)

항목 비고
[ ] 모든 외부 시스템 owner 변경 합의 접근 권한 목록 표
[ ] 시크릿 회전 일정 합의 access-list §6 Priority 표
[ ] 인수 후 Bootalk 측 지원 기간 합의 연락처
[ ] Cloudflare 계정 양도 vs 신규 발급 결정 dev 도메인은 bootalk.co.kr zone에 있어 옮길지 결정 필요
[ ] Lightsail SSH key 양도 vs 새 key pair 발급 결정 새 key pair 발급이 보안상 안전
[ ] Hard cutover (legacy 폐기) 진행 여부 / 시점 결정 현재 무기한 연기 — known-issues D4

1. Day 0 — 접근 검증

1.1 AWS

# SSO 로그인 (브라우저 한 번 인증 필요)
aws sso login --profile ob

# 계정 확인 — 023888247019 (semugpt) 인지 확인
aws --profile ob sts get-caller-identity

# 주요 리소스 조회
aws --profile ob lightsail get-instance --instance-name semugpt-backend --query 'instance.state'
aws --profile ob rds describe-db-instances --db-instance-identifier tax-gpt --query 'DBInstances[0].DBInstanceStatus'
aws --profile ob route53 list-hosted-zones-by-name --dns-name semugpt.co.kr
항목 기대 결과
[ ] AWS Console 로그인 (ob profile via SSO) aws sts get-caller-identity → account 023888247019
[ ] Lightsail instance 조회 running
[ ] RDS instance 조회 available
[ ] Route 53 hosted zone 조회 semugpt.co.kr. zone ID Z0917222THSORQW5ECCW
[ ] bootalk-prod 프로파일 잘못 들어가지 않았는지 확인 account 296797354236이면 다른 회사 — 절대 작업 금지

1.2 Lightsail SSH

ssh semugpt-aws 'hostname && df -h /'
항목 기대 결과
[ ] SSH 접속 성공 hostname 출력 + 디스크 사용률 정상 (< 80%)
[ ] 본인 사무실 IP에서 접근 가능 firewall에 본인 사무실 IP 추가 (access-list §5.2)
[ ] ~/.ssh/aws-semugpt 또는 새 key pair 보유 private key 안전 보관

1.3 GitHub

항목 기대 결과
[ ] uitiorg/semugpt-2026 repo write 권한 clone + push 가능
[ ] GitHub Actions secrets 접근 (Settings → Secrets) CLOUDFLARE_API_TOKEN 등 enumerated
[ ] Branch protection rule 확인 main / develop 보호 정책 검토

1.4 Cloudflare

항목 기대 결과
[ ] Cloudflare 대시보드 접근 bootalk.co.kr zone + semugpt-frontend-dev Worker 보임
[ ] Cloudflare Pages 프로젝트 확인 ⚠️ semugpt-2026 프로젝트 + wiki.semugpt.co.kr 도메인 (검증 필요 — access-list §3.3)
[ ] Cloudflare Tunnel semugpt-backend 활성 상태 tunnel ID 078d8083-eba8-4df2-8026-ebafcb53666b

1.5 Slack 알림

# webhook 정상 동작 확인 (Slack 채널에 테스트 메시지 도착해야 함)
ssh semugpt-aws 'sudo /usr/local/bin/disk-alarm.sh; sudo /usr/local/bin/health-monitor.sh'
항목 기대 결과
[ ] Slack 채널에 알림 도착 가능 확인 본인이 Slack 채널 멤버
[ ] mention prefix가 인수 받는 팀 담당자로 변경 /etc/semugpt/slack-mention.txt 갱신

2. Day 1-3 — 시스템 동작 검증

2.1 외부 URL 헬스 체크

curl -s -o /dev/null -w "DEV BACKEND   %{http_code} (%{time_total}s)\n" --max-time 10 https://semu-gpt-dev.bootalk.co.kr/actuator/health
curl -s -o /dev/null -w "DEV FRONTEND  %{http_code} (%{time_total}s)\n" --max-time 10 https://semu-chat-dev.bootalk.co.kr/
curl -s -o /dev/null -w "PROD BACKEND  %{http_code} (%{time_total}s)\n" --max-time 10 https://api.semugpt.co.kr/actuator/health
curl -s -o /dev/null -w "WIKI          %{http_code} (%{time_total}s)\n" --max-time 10 https://wiki.semugpt.co.kr/
항목 기대 결과
[ ] Dev backend health 200
[ ] Dev frontend 200
[ ] Prod backend (legacy) health 200
[ ] Wiki 200 ⚠️ (도메인 검증 필요 — access-list §3.3)

2.2 DB / ES 접속 검증

# RDS MySQL (현재 0.0.0.0/0 개방, 본인 IP 어디서든 접속 가능)
MYSQL_PWD='selim3400!!' mysql -h tax-gpt.cl2zydns6yrm.ap-northeast-2.rds.amazonaws.com -u admin -e 'SHOW DATABASES;'

# Dev ES (printf 방식 — `!` 문자 shell parsing 회피)
AUTH=$(printf 'elastic:uiti0701!' | base64)
ssh semugpt-aws "curl -s -H 'Authorization: Basic ${AUTH}' http://localhost:9200/_cluster/health"
항목 기대 결과
[ ] RDS 접속 + 4개 database 확인 (tax_gpt, tax_gpt_v2, tax-gpt-v3, semugpt_2026) 모두 표시
[ ] Dev ES cluster health green 또는 yellow
[ ] ES password ! 문자 shell parsing 이해 printf + %21 URL encode 패턴

2.3 OpenAPI 자동 갱신 워크플로 검증

항목 기대 결과
[ ] OpenAPI auto-update 워크플로 1회 수동 trigger (GH Actions) ⚠️ 워크플로 이름/위치 검증 필요
[ ] 워크플로 성공 시 docs/wiki/04-api-reference/openapi.yaml 자동 갱신 PR 생성 PR 검토 + 머지

3. Day 1-7 — 코드 변경 sanity test

작은 PR을 직접 만들어 CI → 머지 → 배포 → 외부 URL 반영까지의 전 사이클을 검증한다.

3.1 Backend sanity test

# 1. 작은 변경 (예: README 한 줄 수정 또는 health endpoint custom message)
git checkout -b feat/handover-sanity-test
# ... edit ...
git commit -am "test: handover sanity check"
gh pr create --base develop

# 2. CI 통과 후 머지
gh pr merge --squash

# 3. dev 반영 (현재는 수동)
ssh semugpt-aws 'cd /opt/semugpt-2026 && git fetch && git checkout develop && git pull && sudo systemctl restart semugpt-backend'
sleep 90
curl -s https://semu-gpt-dev.bootalk.co.kr/actuator/health
항목 기대 결과
[ ] PR 생성 + CI 통과 green
[ ] develop 머지 성공
[ ] dev URL 반영 health 200, 변경사항 visible

3.2 Frontend sanity test

항목 기대 결과
[ ] 작은 frontend PR (예: 푸터 텍스트) preview Workers 배포 자동 생성
[ ] preview URL 접속 변경사항 visible
[ ] develop 머지 → deploy-frontend-dev.yml action 실행 Cloudflare Workers semugpt-frontend-dev 갱신

3.3 Wiki sanity test

항목 기대 결과
[ ] 작은 wiki PR (예: 본 페이지 typo) Cloudflare Pages preview deploy 자동 생성
[ ] mkdocs --strict build 0 warnings local에서 .venv-docs/bin/mkdocs build --strict 통과

⚠️ Cloudflare Pages PR preview는 Cloudflare Pages 프로젝트 생성 후에 만들어진 PR만 preview 가능 — 인수 시점에 검증 필요 (known-issues I4)

4. Week 2-4 — 운영 능력 검증

장애·운영 시나리오를 직접 따라가 봄으로써 운영 런북에 익숙해진다.

4.1 장애 대응 시뮬레이션

# 의도적 장애 — backend systemd 정지 → Slack 알림 발생 확인
ssh semugpt-aws 'sudo systemctl stop semugpt-backend'

# 5분 대기 (health-monitor cron 주기)

# Slack에 DOWN 알림 도착 확인
# (mention 포함되어야 함)

# 복구
ssh semugpt-aws 'sudo systemctl start semugpt-backend'

# 5분 대기

# Slack에 UP 알림 도착 확인 (mention 없음 — 복구는 조용히)
항목 기대 결과
[ ] Backend stop 시 5분 내 Slack DOWN 알림 + mention 알림 도착
[ ] Backend restart 시 5분 내 Slack UP 알림 (mention 없음) 알림 도착
[ ] 복구 절차 따라 복구 진행 health 200

4.2 디스크 모니터링 시뮬레이션

# disk-alarm threshold 일시적 낮춤 (실제 작업 시는 조심스럽게)
ssh semugpt-aws 'sudo vi /usr/local/bin/disk-alarm.sh'
# THRESHOLD=80 → THRESHOLD=10 (현재 사용률보다 낮게)
# cron 실행 (또는 수동 실행)
ssh semugpt-aws 'sudo /usr/local/bin/disk-alarm.sh'
# Slack 알림 확인 후 THRESHOLD 원복
항목 기대 결과
[ ] THRESHOLD 변경 후 Slack DISK_ALARM 알림 도착 알림 + mention
[ ] THRESHOLD 원복 후 RECOVERED 알림 도착 알림 (mention 없음)
[ ] 디스크 정리 runbook 읽고 절차 이해 —

4.3 코드 변경 → 자동화 검증

항목 기대 결과
[ ] 새 backend 컨트롤러 추가 PR OpenAPI auto-update 워크플로가 wiki 페이지 자동 갱신 ⚠️
[ ] wiki PR에서 mkdocs build --strict 0 warnings 유지 CI 통과
[ ] 새 데이터 소스 1개 collector 추가 시도 data-pipeline CLAUDE.md 8단계 체크리스트 따라가기

4.4 인수 받은 팀 내부 인계

항목 기대 결과
[ ] 인수 받은 팀 내 2명 이상이 위 검증 항목 통과 bus factor ≥ 2
[ ] 위키 본문에 사용된 1차 출처(CLAUDE.md, spec) 읽음 코드 변경 시 위키 drift 인지

5. 인수 완료 기준

위 모든 항목 ✅ + 다음 조건 충족:

항목 비고
[ ] 알려진 이슈 모두 인지 보안 우려 / 백엔드 코드 이슈 / 인프라 한계 / 결정 미정
[ ] 시크릿 회전 완료 (P0 + P1) access-list §6
[ ] Bootalk 측 시스템 권한 회수 AWS IAM / GitHub org / Cloudflare / Slack
[ ] Toss live keys 수령 및 prod env 주입 known-issues I3
[ ] Toss webhook URL prod 등록 known-issues D6
[ ] RDS SG 0.0.0.0/0:3306 잠금 검토 known-issues S1

6. 시각 흐름

flowchart TD
    A["Day 0
접근 검증"] --> B["Day 1-3
시스템 동작 검증"]
    B --> C["Day 1-7
코드 변경 sanity test"]
    C --> D["Week 2-4
운영 능력 검증"]
    D --> E{"모든 항목 ✅?"}
    E -->|"yes"| F["시크릿 회전 + 권한 회수
→ 인수 완료"]
    E -->|"no"| G["Bootalk 지원 채널로
escalate"]
    G --> D

알려진 한계 / 개선 예정

  • 인수 시점의 일부 항목은 외부 dashboard 확인 필요: Cloudflare Pages 프로젝트 이름, GitHub Actions secrets 전체 목록은 본 페이지에서 모두 enumerate 못 함 — 인수 시점에 직접 검증.
  • OpenAPI auto-update 워크플로 이름/경로 검증 필요 ⚠️ — wiki에 명시 안 됨.
  • CI/CD 자동화 부재: develop push가 dev URL에 자동 반영되지 않음 — 현재 ssh + git pull 수동. 인수받을 팀이 CI/CD 도입 검토 권장.

관련 문서

  • 접근 권한 목록 — Day 0 검증의 자격증명 위치
  • 연락처 — escalation path
  • 운영 런북 — 모든 실 운영 절차의 1차 참조점
  • 알려진 이슈 — 인수 시점에 인지해야 할 한계
  • 1차 출처: 레포 루트 CLAUDE.md의 "Dev Environment 운영" + "Production Infrastructure" 섹션