본문 바로가기
WIKI 기술 지식 베이스

문제 해결 전략

원문 보기 위키 갱신

문제 해결 전략 (Troubleshooting Strategies)

출처: Caddy 공식 문서

본문

이 페이지는 Caddy를 사용할 때 겪을 수 있는 대부분의 문제를 AI의 도움 없이 스스로 해결하기 위한 일반적이고 체계적인 프레임워크를 제시해요. 우리 포럼에서 도움을 요청할 때도 비슷한 절차를 권장해요. 많은 경우 몇 가지 비판적 사고를 적용하면 스스로 질문에 답하거나 문제를 해결할 수 있어요.

무엇을 알고 있나요?

문제가 무엇인지, 무엇이 원인인지, 어떻게 고칠지 모를 수 있어요. 그래서 확실히 아는 몇 가지 기본적인 것부터 시작해 봐요:

기대하는 것

크게 소리 내어, 머릿속으로, 또는 쓰거나 타이핑해서 말해 보세요. 모호함이 없도록 명확하고 구체적으로 말해요. 왜 그걸 기대하는지 스스로에게 설명해 볼 수도 있어요.

"동작해야 한다"는 좋은 기대가 아니에요.

"이 URI에 요청을 하면 301 리다이렉트가 발생할 것으로 기대한다"가 훨씬 좋아요.

현재 동작

무슨 일이 일어나는지 관찰해요. 정확히 무슨 일이 일어나고 있고, 기대와 어떻게 대조되나요? 아는 것을 종합해 보세요.

"동작하지 않는다"는 비생산적이고 게을러요. 이미 자세히 문서화된 특정 동작에 대한 단축 설명으로 쓰는 경우를 제외하고는 이 표현을 피하세요.

"301 응답 대신 200 응답을 받고 있지만, Server: Caddy 헤더는 보인다"가 훨씬 좋아요. 아는 것과 기대하는 것을 비교·대조하고 다른 알려진 정보를 종합해서, 요청이 적어도 어떤 Caddy 인스턴스에는 도달하고 있다는 것을 알려주니까요.

로그

Caddy 로그에 뭐가 있나요? 기본적으로 이 로그는 프로세스를 시작한 터미널에 기록돼요. 시스템 서비스처럼 "분리(detached)"되어 실행된다면 다른 곳에서 로그를 가져와야 할 수도 있어요.

HTTP 요청 로그("액세스 로그")는 프로세스 로그와 다르며, 설정에서 명시적으로 활성화해야 한다는 점을 유의하세요.

아직 하지 않았다면 DEBUG 레벨 로깅을 활성화하고 싶을 수도 있어요.

어쨌든 가장 먼저 해야 할 일 중 하나는 로그를 보는 거예요. 전부 다요. 메시지 컨텍스트가 중요하므로, 고립된 단일 로그 줄은 거의 쓸모가 없어요. 필요하다고 생각하는 것보다 더 많이 수집하고 문제 해결 과정을 통해 보존해요.

로그에 어떤 힌트가 있나요?

가정을 인식하고 의심하기

더 나아가기 전에, 여러분이 가정하는 것을 비판하는 것이 얼마나 중요한지 강조해야 해요. 우리 모두 익숙한 것과 기대하는 것에 기반해 가정을 만들어요. "가정을 경계하라, 그러면 큰 힘을 얻으리라." (—요다, 뭐 그런 느낌.)

예를 들어, 흔한 가정은 Caddy를 재컴파일한 후 caddy를 실행하면 새 코드가 실행될 거라는 것이에요. 이는 여러분의 컴파일된 바이너리가 $PATH에 있는 것을 대체했을 때만 사실이에요. 대신 ./caddy가 보통 올바른 호출이에요.

배포나 설정이 더 복잡해짐에 따라 가정이 쌓여요. 예를 들어 Docker로 배포하면 이미지를 다시 빌드하고 실행하는 것이 포함되어, 만들 수 있는 가정이 늘어나요.

많은 질문과 버그 리포트는 결국 Caddy 자체가 아니라 외부 시스템과 네트워크 설정의 문제로 드러나요. 예를 들어 Caddy 인스턴스에 연결할 수 없지만 Caddy가 분명히 실행 중이라면, DNS가 아닐 거라고 가정할 수 있어요. 힌트: 거의 항상 DNS예요.

설정을 리로드했다고 가정했는데 실제로는 안 한 것도 흔한 실수예요. 여러분의 과정에 대해 엄격하게 임하세요. 모든 수준에서 검증하세요.

흔한 원인 확인하기

사람들이 Caddy로 겪는 대부분의 문제는 주변 시스템이나 네트워크에 있는 것으로 드러나요. 더 깊이 파기 전에 이런 흔한 용의자를 확인해 보세요:

  • DNS: 여러분 도메인의 DNS 레코드(A 및/또는 AAAA)가 Caddy를 실행하는 머신의 공용 IP 주소를 가리켜야 해요. 낡은 레코드, 특히 Caddy에 도달하지 않는 IPv6 주소의 AAAA 레코드를 제거하세요.

  • Split-horizon DNS: 로컬 네트워크가 여러분의 도메인을 나머지 세상과 다르게 해석한다면, Caddy와 ACME CA가 도메인이 어디를 가리키는지에 대해 의견이 다를 수 있어요. 자동 HTTPS는 공용 DNS에 의존해요.

  • 포트: HTTP 및 TLS-ALPN 챌린지를 위해 포트 80과 443이 인터넷에서 도달 가능해야 해요. 라우터의 포트 포워딩, 방화벽, 클라우드 제공업체의 보안 그룹을 확인하세요. HTTP/3를 위해 443/udp도 기억하세요.

  • 다른 서버: Caddy가 필요로 하는 포트에서 이미 다른 프로그램(Apache, nginx, 또는 다른 앱 서버)이 리슨하고 있지 않은지 확인하세요.

  • 권한: Caddy가 실행되는 사용자가 포트에 바인딩하고, 설정 파일과 사이트 파일을 읽고 데이터 디렉터리에 쓰는 권한이 있어야 해요. 파일과 그 위의 모든 디렉터리의 소유권과 권한을 확인하세요.

  • SELinux: SELinux가 활성화된 시스템에서는 Caddy가 필요한 일을 할 수 있도록 Caddy를 허용하도록 구성해야 해요.

  • 올바른 설정: Caddy가 여러분이 생각하는 설정으로 실행 중인지 확인하세요. 예를 들어 서비스로 실행할 때 Caddyfile은 보통 /etc/caddy/Caddyfile에 있고, 변경 사항은 리로드 후에만 적용돼요.

동작 재현하기

문제가 스스로 해결되게 하는 중요한 단계예요: 문제를 다시 발생시키는 거예요.

구체적으로, 가장 최소한의 방식으로 다시 발생시켜 보세요. 문제가 사라질 때까지 불필요한 설정, 배포 단계, 환경 요인 등을 제거하세요.

흔한 전략은 한 번에 하나씩만 제거하고 문제가 사라질 때까지 다시 시도하는 거예요. 그러면 제거한 것이 원인일 가능성이 높아요. 또는—가정을 의심하기 좋은 지점이에요—마지막으로 제거한 것과 그 전에 제거한 것의 조합이 원인일 수 있어요. 처음에 제거했던 것들을 다시 추가해 검증하고 범위를 좁혀 나가세요.

또 다른 아이디어는 반복마다 전체의 대략 절반씩 제거하고, 문제가 사라지면 그 절반의 절반만 제거하는 방식이에요. 이진 탐색과 비슷해서 더 빠를 수 있어요.

또는 제거하는 대신 이 전략을 뒤집어서, 문제가 나타날 때까지 설정이나 시나리오를 처음부터 단계적으로 쌓아 올리면서 매번 다시 시도할 수도 있어요.

종종 이 과정만으로도 문제를 식별하고 해결책이 명확해지기도 해요. 아니라면 적어도 문제를 재현하는 최소 단계를 적어 둘 수 있어요.

동작 탐구하기

문제를 재현하는 단계를 알면 원인을 진단하기 좋은 위치에 있어요. 이는 이것저것 실험해 보고, 능숙하다면 코드를 읽어 보는 것을 포함해요.

문제가 왜 발생하는지 설명할 수 없다면 동작을 바꿔 보세요. 작은 변경을 하고 다시 시도해요. 예를 들어 관련 설정에 정규 표현식이 포함되어 있다면 표현식을 바꾸거나 단순화하거나—완전히 제거해서—찾는 동작을 얻기 위해 무언가를 해 보세요. 원하는 게 아니어도 적어도 정규 표현식이나 설정에 문제가 있다는 건 알게 돼요.

탐구하면서 잘 되는 것과 안 되는 것의 패턴을 주목하세요. 그러면 해결책으로 가는 길이 보일 거예요.

해결책을 찾으면 버그인지 아닌지 결정하면 돼요. 때로는 버그인지 명확하지 않을 수 있어요. 실험 내용을 담은 이슈를 올리고 어느 쪽이든 관리자 피드백을 받아도 괜찮아요.

그리고 버그가 아니라면 축하해요! 문제를 해결했고 과정에서 적어도 무언가를 배웠어요.

같은 문제를 겪을 수 있는 다른 사람들을 돕기 위해 포럼에 여러분의 경험을 올리는 것을 고려해 보세요.

더 알아보기 (Learn more)