문제 해결
이 섹션은 유용한 형태가 증상, 가능한 원인, 진단, 수정 및 예방인 알려진 오류 모드에 대한 것입니다.
더 긴 사건 설명과 아키텍처 회고는 사건 및 회고에 있습니다.
사용하는 방법
이미 알려진 실패 패턴에 들어갔고, 우선순위가 복구 또는 운영 검증일 때 이 섹션에서 시작합니다. 각 가이드는 원래 사고를 직접 처리하지 않은 엔지니어도 다음 네 가지를 빠르게 판단할 수 있어야 합니다.
- 이 실패 모드를 식별하는 정확한 증상은 무엇인가?
- 어떤 소스 파일, Kubernetes 객체, 런타임 신호가 진단을 증명하는가?
- 가장 작은 안전한 수정은 무엇인가?
- 수정이 실제로 유지되고 있음을 보여주는 증거는 무엇인가?
이 문서들 은 설계 문서를 대체하지 않습니다. 수정이 지속적인 제품 또는 플랫폼 계약을 바꾼다면 관련 참조 문서나 회고도 함께 갱신해야 합니다.
섹션
| 섹션 | 사용 |
|---|---|
| 백엔드 DB | Flyway, RLS, 마이그레이션, 트랜잭션 및 데이터베이스 런타임 오류. |
| 백엔드 런타임 | tenant context, backend-to-worker 호출, 비동기 job lifecycle, provider callback 실패. |
| 프런트엔드 런타임 | Next.js 런타임, 로컬 프록시, 이미지 최적화 및 종속성 마이그레이션 실패. |
| 워커 런타임 | FastAPI, 비동기 수명주기, 리포트 렌더링 및 워커 서비스 런타임 오류. |
| 워커 CI | 생성된 requirements 및 워커 빌드 또는 CI 드리프트 실패. |
| 인프라 스케일링 | KEDA, 자동 크기 조정, 프로브 및 워크로드 크기 조정 오류. |
| 인프라 관측성 | Tempo, Loki, Grafana, 추적, 메트릭 및 로그 파이프라인 오류. |
| 인프라 접속 | Coder, Teleport, SSO 및 WebSocket/원본 액세스 오류. |
| 인프라 인증서 | cert-manager, DNS-01 및 인증서 비밀 프로젝션 실패. |
| 인프라 메시징 | RabbitMQ, broker topology, credential 및 queue delivery 오류. |
| 인프라 네트워킹 | Traefik, 레지스트리 업로드, 수신 및 프록시 시간 초과 오류. |
| 제품 워크플로우 | 가져오기 및 대량 작업과 같은 반복 가능한 제품 워크플로 오류. |
문서 품질 기준
문제 해결 문서는 원래 사고를 처리하지 않은 사람이 읽어도 운영 맥락을 잃지 않을 만큼 구체적이어야 완성입니다. 넓은 조언보다 구체적인 소스 경로, 설정 키, 명령, 기대 출력, 하지 말아야 할 확인을 우선합니다.
주제가 허용하는 경우 각 문서에는 다음 항목을 명시합니다.
- 증상: 사용자 또는 운영자가 관찰하는 동작과 영향 범위.
- 가능한 원인 또는 근본 원인: 인접한 장애와 구분되는 가장 작은 원인 설명.
- 진단: 가설을 확인하거나 배제하는 순서 있는 점검.
- 수정: 의도한 복구 경로와 다시 도입하면 안 되는 변경.
- 검증: 복구가 실제로 끝났음을 보여주는 명령 또는 런타임 증거.
- 예방: 같은 실패가 돌아오지 않게 하는 가드레일.
긴 사고 메모에서 옮겨온 문서라면 원본을 삭제하기 전에 Docusaurus 문서 안에 사고별 세부사항을 보존합니다. 저장소만으로 라이브 상태를 증명할 수 없다면 그 사실을 명시하고 런타임 확인 명령을 적습니다.
사고 중 분류 순서
활성 사고 중에는 다음 순서로 사용합니다.
- 증상을 위 표의 가이드와 맞춥니다.
- 먼저 저장소 확인을 실행합니다. 빠르고, 클러스터 접근 전에 드리프트를 잡을 수 있습니다.
- 저장소 계약이 정상일 때만 live Kubernetes, CI, 브라우저 확인으로 넘어갑니다.
- 문서화된 계약을 복구하는 가장 작은 수정을 적용합니다.
- 검증 증거를 사고 메모나 후속 PR에 남깁니다.
증상이 겹치면 실패 경계에 가장 가까운 가이드를 우선합니다. 예를 들어 Zot blob push가 Traefik에서 끊기면 Infra Networking에 속하고, Zot가 요청을 받은 뒤 스토리지에서 실패하면 registry 참조 문서가 더 가깝습니다.