Certbot 오류 해결 FAQ 종합 가이드

Certbot으로 SSL 인증서를 발급하거나 갱신할 때 다양한 오류가 발생할 수 있습니다. 이 문서는 실무 환경에서 자주 발생하는 문제를 중심으로 원인과 해결방법을 단계별로 정리한 가이드입니다.

도메인 입력 오류 문제

잘못된 도메인 기입으로 인한 인증 실패

Certbot 명령어의 d 옵션에 example.com 과 www.example.com 을 함께 기입하지 않거나 실제 서비스 도메인과 불일치하는 값을 입력하면 인증이 실패합니다. 웹서버의 webroot 경로와 실제 URL 접근 여부를 반드시 확인해야 합니다.

certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com

기존 인증서 충돌 문제

이전 인증서가 남아 있어 재발급이 안 되는 경우

단일 도메인으로 설치한 인증서가 남아 있는 상태에서 새로운 도메인을 추가해 발급을 시도하면 기존 인증서 이름과 충돌하는 오류가 발생합니다. 이 경우 불필요한 인증서를 삭제한 후 새로 발급해야 합니다.

certbot certificates
certbot delete --cert-name example.com

웹서버 설정 및 VirtualHost 오류

DocumentRoot 경로가 존재하지 않는 경우

Apache 또는 Nginx VirtualHost 설정은 존재하지만 실제 경로가 생성되지 않은 경우 인증 과정에서 파일을 쓰지 못해 실패합니다. 디렉토리 생성 여부와 권한을 반드시 확인해야 합니다.

mkdir -p /var/www/example/.well-known/acme-challenge
chown -R apache:apache /var/www/example

DNS 전파 지연으로 인증이 실패하는 경우

DNS 레코드 수정 후 바로 인증 시도할 때 발생

A 레코드 또는 CNAME을 수정한 직후 DNS 전파가 완료되지 않은 상태에서 Certbot을 실행하면 인증이 실패합니다. 특히 해외 DNS 서버 반영이 늦을 때 더욱 자주 발생합니다.

dig example.com A
dig www.example.com CNAME

Cloudflare Proxy 기능으로 인한 인증 실패

Proxy 활성화 상태에서는 HTTP 인증이 작동하지 않음

Cloudflare의 주황색 Proxy 기능이 활성화되어 있으면 Certbot이 필요한 HTTP 인증 파일에 접근할 수 없습니다. 이는 가장 흔한 문제 중 하나이며 반드시 DNS Only 상태로 전환해야 합니다.

포트 충돌로 인해 Certbot이 실행되지 않는 경우

웹서버 외 프로세스가 80 또는 443 포트를 점유

Certbot은 HTTP 인증을 위해 80 포트에 접근해야 합니다. Node, Python, Docker 등 다른 프로세스가 포트를 점유하고 있으면 인증이 실패합니다. 포트 현황을 확인 후 충돌되는 프로세스를 중지해야 합니다.

sudo lsof -i :80
sudo lsof -i :443

IPv6 AAAA 레코드로 인한 인증 경로 불일치

서버가 IPv6을 지원하지 않는데 DNS는 IPv6이 등록된 경우

일부 환경에서는 DNS가 IPv6 주소를 우선 조회하면서 인증 파일에 접근하지 못하는 문제가 생깁니다. IPv6을 사용하지 않는다면 AAAA 레코드를 제거하는 것이 좋습니다.

리다이렉트 규칙이 인증 파일을 가로막는 문제

HTTPS 강제 리다이렉트가 챌린지 파일을 전환시킴

웹서버의 Rewrite 규칙이 모든 HTTP 요청을 HTTPS로 강제로 전환하도록 설정되어 있다면 Certbot이 챌린지 파일에 접근하기 전에 redirect가 수행되어 인증이 실패합니다. 해당 경로는 예외 처리해야 합니다.

location ^~ /.well-known/acme-challenge/ { allow all; }

자동 갱신이 실패하는 경우

경로 변경 또는 Renewal Hook 오류

certbot renew 명령은 오류가 발생해도 조용히 실패할 때가 많습니다. 로그를 직접 확인한 후 지정된 webroot 경로가 올바른지 점검해야 합니다. 또한 dry run 테스트를 통해 사전 검증을 수행하는 것이 좋습니다.

sudo certbot renew --dry-run

결론 및 운영 팁

Certbot은 간단해 보이지만 웹서버 설정, DNS 환경, 도메인 구조, 포트 충돌 등 다양한 요소에 의해 실패할 수 있습니다.

위의 내용을 기준으로 문제 원인을 단계별로 확인하면 대부분의 오류를 빠르게 해결할 수 있습니다. 운영 중인 웹서비스의 환경을 정확히 파악하고 발급 방식과 webroot 설정을 일관되게 유지하는 것이 안정적인 SSL 운영의 핵심입니다.