DuckDNS는 Docker 컨테이너 하나로 '집 IP가 바뀌어도 항상 같은 주소로 접속'되게 만들어주는 무료 DDNS입니다. 앞선 6편에서 DDNS의 개념과 내 환경 진단(공인 IP 확인)을 마쳤다면, 이번 편에서는 실제로 DuckDNS 컨테이너를 우분투 서버에 올려 자동 갱신까지 완성합니다. 이 글에는 제가 직접 설치하며 만난 KO 오류와 컨테이너 이름 충돌 에러, 그리고 그 해결 과정을 그대로 담았습니다.
이 글은 6편(DDNS 완벽 설정)의 실습 편입니다. DDNS가 왜 필요한지, 내 환경이 외부 접속 가능한지 진단하는 방법은 6편을 먼저 보세요.
DuckDNS 컨테이너 올리기
DuckDNS 자동 갱신은 linuxserver/duckdns 이미지를 컨테이너로 실행하는 것으로 끝납니다. 이 컨테이너는 주기적으로 우리 집 공인 IP를 확인해 DuckDNS에 자동 등록해주기 때문에, 한 번 올려두면 IP가 바뀌어도 신경 쓸 필요가 없습니다. 먼저 DuckDNS 사이트(duckdns.org)에서 준비를 마쳐야 합니다.
사이트에 구글 등으로 로그인하면 reCaptcha 확인('로봇이 아닙니다') 단계를 거치는데, 이걸 통과해야 대시보드가 열립니다. 대시보드에서 원하는 서브도메인 이름을 입력하고 add domain 버튼까지 눌러 실제로 생성해야 합니다. 저는 브랜드를 살려 ddlabx-home으로 만들었습니다. 그리고 화면 상단의 token 값을 복사해둡니다. 이 토큰은 IP를 갱신할 때 쓰는 열쇠이자 비밀번호와 같아서, 절대 외부에 노출하면 안 됩니다. 준비가 되면 서버(SSH 접속 상태)에서 아래 명령으로 컨테이너를 실행합니다. \로 이어진 한 덩어리이니 통째로 붙여넣으면 됩니다.
docker run -d --name duckdns \
-e SUBDOMAINS=ddlabx-home \
-e TOKEN=본인_토큰_붙여넣기 \
-e TZ=Asia/Seoul \
--restart=always \
lscr.io/linuxserver/duckdns:latest
SUBDOMAINS에는 .duckdns.org를 뺀 이름만 넣고, TOKEN에는 사이트에서 복사한 값을 정확히 넣습니다. --restart=always 옵션 덕분에 서버를 재부팅해도 컨테이너가 자동으로 다시 켜져 IP 갱신을 이어갑니다.
실전 삽질 — KO 오류와 이름 충돌 에러 해결
컨테이너를 올린 뒤 로그를 확인했더니, 처음엔 성공이 아니라 KO가 떴습니다. 로그 확인 명령은 이렇습니다.
docker logs duckdns
당시 로그에는 Detecting IPv4 via DuckDNS / Something went wrong, please check your settings / The response returned was: KO라고 나왔습니다. KO는 DuckDNS가 '보낸 서브도메인이나 토큰이 맞지 않는다'며 거절했다는 뜻입니다. 컨테이너 자체는 정상 실행됐지만 설정값이 안 맞은 것이죠. 이 오류의 흔한 원인은 세 가지입니다. 첫째, 사이트에서 서브도메인을 add domain까지 누르지 않아 실제로 만들어지지 않은 경우. 둘째, SUBDOMAINS에 .duckdns.org까지 붙인 경우(이름만 넣어야 합니다). 셋째, 토큰을 복사할 때 앞뒤 공백이 섞이거나 일부만 복사된 경우입니다.
값을 바로잡아 다시 실행하려 했더니, 이번엔 다른 에러가 나왔습니다. Conflict. The container name "/duckdns" is already in use라는 메시지였는데, 이건 실패가 아니라 먼저 만든 컨테이너가 아직 남아 있는데 같은 이름으로 또 만들려 해서 막힌 것입니다. Docker는 이름 중복을 허용하지 않기 때문이죠. 해결은 기존 컨테이너를 먼저 지우고 다시 실행하면 됩니다.
docker stop duckdns
docker rm duckdns
그다음 올바른 값으로 docker run 명령을 다시 실행하면 이름 충돌 없이 깔끔하게 올라갑니다. 이처럼 DuckDNS 설치는 KO와 이름 충돌이라는 두 관문을 거치는 경우가 많은데, 원인만 알면 몇 초 만에 해결됩니다.
성공 확인과 최종 검증
값을 바로잡고 다시 실행한 뒤 로그를 확인하니, 이번엔 성공 메시지가 떴습니다. 여기서 한 가지 알아둘 점은, linuxserver 컨테이너 버전은 순수 스크립트에서 뜨는 OK 대신 사람이 읽기 좋은 문장으로 결과를 보여준다는 것입니다. 제 로그에는 DuckDNS request at ... successful. IP(s) unchanged.라고 나왔는데, 여기서 *successful*이 성공 신호입니다. 뒤의 IP(s) unchanged는 'IP가 이전과 같아 바꿀 필요가 없었다'는 뜻으로, 이미 올바른 IP가 등록돼 있다는 확인이니 정상입니다.
마지막으로 DuckDNS 주소가 실제로 우리 집을 가리키는지 검증했습니다. 서버에서 nslookup ddlabx-home.duckdns.org를 실행하니, Name: ddlabx-home.duckdns.org / Address: 14.51.xx.xx처럼 우리 집 공인 IP가 반환됐습니다. 이 IP가 6편의 CGNAT 진단 때 curl -4 ifconfig.me로 확인한 공인 IP와 일치하면, DDNS가 완벽하게 작동한다는 최종 증거입니다. 이제 집 IP가 언제 바뀌든 ddlabx-home.duckdns.org라는 고정된 주소로 항상 우리 서버에 접근할 수 있게 됐습니다.
한 가지 보안 당부를 덧붙입니다. 토큰과 공인 IP는 모두 민감 정보이니, 블로그에 스크린샷을 올릴 때는 token 전체와 IP 뒷자리를 반드시 가리세요. 혹시 토큰이 노출됐다면 DuckDNS 사이트에서 재발급(recreate) 후 새 값으로 컨테이너를 다시 올리는 것이 안전합니다.
이것으로 '항상 같은 주소'라는 DDNS 기반이 실제로 완성됐습니다. 다음 편에서는 이 주소 하나로 여러 서비스를 포트 없이 깔끔하게 연결하는 리버스 프록시를 설치합니다. → 7편. 리버스 프록시로 도메인 하나에 여러 서비스 연결