trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bc56c5c101d84a42a91749f589d6f5fe7d334b6f
portfolio-hub/docs/sdlc/sdlc-002_20260423_service-token-user-based/7_operation.md
T
genichin d383c7086f 작업 내용 저장
2026-04-23 09:56:08 +00:00

7.9 KiB
Raw Blame History

0. 문서 상태

이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

  • 상태: confirmed
  • 문서 ID: sdlc-002_20260423_service-token-user-based
  • 이슈명: service-token user-based 소유권
  • 참조 Release: docs/sdlc/sdlc-002_20260423_service-token-user-based/6_release.md
  • 작성 시각(KST): 2026-04-23
  • 마지막 갱신 시각(KST): 2026-04-23

1. Release 인계 요약

Release에서 완료된 핵심 내용을 요약한다. 원본은 6_release.md를 참조하며, 이 섹션은 Operations 작업의 입력 기준선이 된다.

이슈 목적

bot_principals / auth_audit_logs 테이블을 제거하고, service token을 auth_tokens 단일 엔티티로 직접 발급하도록 재구현한다. CLI pfhub service-token issue <name> --user <username> 명령으로 사용자 기반 소유권을 명확히 한다.

배포 결과 요약

  • 배포 환경: production (Linux/Ubuntu, systemd + uvicorn + Caddy)
  • 배포 완료 시각(KST): {{OPS_DEPLOYED_AT:TBD}}
  • 스모크 테스트 결과: 미완료

이월된 오픈 질문 / 리스크

Release에서 이월된 항목:

  • VC-8~VC-10 (이월): 로컬 Docker Compose 환경 기동 후 Justin이 alembic upgrade/downgrade 및 FK 정합성 쿼리 수동 검증 필요. 배포 전 완료 목표.
  • R-1 (이월, High): 운영 DB bot_principals.owner_user_id IS NULL 행 존재 시 마이그레이션 FK 위반 가능 — 배포 전 사전 쿼리 확인으로 차단.

2. 운영 모니터링

배포 후 지속적으로 모니터링해야 하는 항목과 기준을 정의한다.

모니터링 항목

항목 확인 방법 임계값 / 이상 기준 대응 방안
서비스 오류 로그 journalctl -u portfoliohub --since "1 hour ago" | grep -E "ERROR|CRITICAL" ERROR/CRITICAL 로그 1건 이상 발생 스택 트레이스 확인 후 장애 대응 절차 진입
헬스 체크 응답 curl -s http://localhost:8000/health HTTP 200 외 응답 또는 응답 없음 systemd 서비스 상태 확인 (systemctl status portfoliohub) 후 재기동 또는 롤백
인증 API 정상 응답 curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/auth/login -X POST -d '{}' 5분 내 비정상 응답(4xx 외 500+) 3회 이상 오류 로그 확인 후 롤백 판단
DB 마이그레이션 상태 alembic current 최신 리비전(20260423_0013) 외 값 표시 마이그레이션 재실행 또는 롤백 판단
bot_principals 테이블 미존재 유지 psql -c "\dt bot_principals" 테이블이 재생성된 경우 마이그레이션 상태 확인 후 이상 여부 조사

모니터링 담당자

  • Justin

3. 운영 절차 (런북)

이 변경 사항과 관련된 운영 중 발생할 수 있는 상황별 대응 절차를 정의한다.

정상 운영 확인 절차

배포 후 일정 주기로 정상 동작을 확인하는 절차를 기술한다.

  1. 일 1회 — journalctl -u portfoliohub --since "24 hours ago" | grep -E "ERROR|CRITICAL" 실행. 결과 없음 확인.
  2. 일 1회 — curl -s http://localhost:8000/health 실행. {"status":"ok"} 응답 확인.
  3. 주 1회 — alembic current 실행. 최신 리비전(20260423_0013) 적용 상태 확인.
  4. 배포 후 첫 1주 — pfhub service-token issue --help 실행. NAME, --user 정상 노출 확인.

장애 대응 절차

이 변경과 관련된 장애가 발생했을 때의 초기 대응 절차를 기술한다.

  1. 오류 확인: journalctl -u portfoliohub -n 100 --no-pager 실행. 스택 트레이스 및 오류 메시지 수집.
  2. 헬스 체크: curl -s http://localhost:8000/health 실행. 응답 여부 확인.
  3. 서비스 재기동 시도: sudo systemctl restart portfoliohub. 재기동 후 헬스 체크 재실행.
  4. 롤백 판단: 재기동 후에도 오류 지속 시 6_release.md # 3 롤백 조건 충족 여부 확인.
  5. 롤백 실행 (조건 충족 시):
    • sudo systemctl stop portfoliohub
    • alembic downgrade -1
    • git checkout <이전 커밋 해시>
    • sudo systemctl start portfoliohub
    • curl -s http://localhost:8000/health 확인
  6. 에스컬레이션: 롤백 후에도 복구 안 되면 에스컬레이션 경로 진입.

에스컬레이션 경로

장애 대응 중 에스컬레이션이 필요한 경우 연락 대상을 기록한다.

  • {{OPS_ESCALATION_1:TBD}}

4. 운영 중 발생한 이슈

운영 중 발견된 이슈를 기록한다. 초안 생성 시 비워 두고 운영 중 갱신한다.

  • 없음 (운영 중 발견 시 기록)

5. 리스크 및 오픈 질문

Operations 단계에서 새로 식별된 리스크와 오픈 질문을 기록한다.

리스크

  • R-1 (High, 이월): 운영 DB bot_principals.owner_user_id IS NULL 행 존재 시 마이그레이션 upgrade FK 위반
    • 완화 방안: 배포 전 체크리스트 쿼리(SELECT COUNT(*) FROM bot_principals WHERE owner_user_id IS NULL) 결과 0건 확인 후 배포. NULL 행 발견 시 수동 정리 후 진행.
  • R-2 (Medium, 이월): VC-8~10 수동 DB 검증 미완료 상태로 배포 시 검증되지 않은 DB 변경 적용 위험
    • 완화 방안: 로컬 Docker Compose 환경에서 Justin이 VC-8~10 완료 확인 후 운영 배포 진행.

오픈 질문

없음.

6. 다음 Discovery 환류

운영 중 발견된 인사이트와 개선 사항을 다음 SDLC Discovery의 입력으로 기록한다.

  • 없음 (운영 중 갱신 예정)

7. 확인 체크

Operations 문서가 완성되었는지 확인한다.

  • 모니터링 항목 및 임계값 정의 완료
    • 기준: 모니터링 항목에 임계값과 대응 방안이 명시되어야 한다 — 5개 항목 정의 완료
  • 런북(정상 운영/장애 대응 절차) 정의 완료
    • 기준: 운영 중 발생 가능한 상황에 대한 절차가 1단계 이상 있어야 한다 — 정상 4단계, 장애 6단계 정의 완료
  • 에스컬레이션 경로 정의 완료
    • 기준: 장애 시 연락할 담당자가 명시되어야 한다 — {{OPS_ESCALATION_1:TBD}} 지정 필요
  • 다음 Discovery 환류 항목 작성 (없으면 "없음" 기재)
    • 기준: 현재 "없음" 기재 — 운영 중 발견 시 갱신
  • Freeze 확정 담당자(CONFIRMED_BY) 지정
    • 기준: 문서 승인 담당자가 명시되어야 한다 — Justin 지정 완료 예정 (confirm-operation 단계에서 처리)

8. 파일 처리 결과

이 Operations 문서 생성/갱신 결과와 참조 문서를 기록한다.

  • 처리 결과: 생성
  • 생성 경로: docs/sdlc/sdlc-002_20260423_service-token-user-based/7_operation.md
  • 참조 문서:
    • docs/sdlc/sdlc-002_20260423_service-token-user-based/6_release.md
    • docs/sdlc/sdlc-002_20260423_service-token-user-based/5_verification.md
    • docs/sdlc/sdlc-002_20260423_service-token-user-based/1_discovery.md

9. 사용자 결정 필요 항목 요약

사용자나 승인자가 결정해야 하는 항목만 모아 정리한다.

DECIDE

없음.

CONFIRM

  • Freeze 확정 담당자(CONFIRMED_BY): Justin — confirm-operation 단계에서 처리

DATA

  • 모니터링 담당자(OPS_MONITOR_OWNER): Justin 또는 담당 운영자 지정 필요
  • 에스컬레이션 연락처(OPS_ESCALATION_1): 장애 시 연락할 담당자/채널 지정 필요
  • 배포 완료 시각(OPS_DEPLOYED_AT): 실제 배포 후 기입
  • 스모크 테스트 결과(OPS_SMOKE_RESULT): 배포 후 스모크 테스트 수행 결과 기입

10. Operations Freeze

이 SDLC 주기의 최종 확정 플래그를 기록한다.

섹션 참조

확정 플래그

  • Handoff Decision: 승인
  • Handoff Rationale: 모니터링 안정화 및 런북 완비 후 주기 완료
  • SDLC 주기 완료: true
  • Confirmed By: Justin
  • Confirmed At (KST): 2026-04-23
Reference in New Issue View Git Blame Copy Permalink