Integracja ACME / Let's Encrypt

Przegląd

Protokół ACME (używany przez Let's Encrypt i inne urzędy certyfikacji) obsługuje wyzwanie DNS-01 do walidacji domeny. DNS-01 to jedyny typ wyzwania obsługujący certyfikaty wildcard (*.example.com) i nie wymaga serwera HTTP na maszynie docelowej.

NexDNS zapewnia natywne integracje z trzema popularnymi klientami ACME oraz ogólny hook CLI dla dowolnego klienta obsługującego ręczne hooki DNS.

Wszystkie integracje ACME wymagają tokenu API z uprawnieniami records.read i records.write. Utwórz go na nexdns.tech/settings/api-keys.

acme.sh

acme.sh to klient ACME w czystym shellu. NexDNS jest obsługiwany jako wbudowany dostawca API DNS.

Wystawienie certyfikatu

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxx"
acme.sh --issue --dns dns_nexdns -d example.com -d '*.example.com'

Token jest zapisywany w ~/.acme.sh/account.conf po pierwszym uruchomieniu, więc nie musisz go ponownie eksportować przy odnawianiu.

Odnowienie

Odnawianie odbywa się automatycznie przez cron. Aby wymusić ręczne odnowienie:

acme.sh --renew -d example.com

lego i Traefik

lego to klient ACME oparty na Go, który również zasila automatyczne zarządzanie certyfikatami Traefik. NexDNS jest obsługiwany jako dostawca DNS.

Samodzielne użycie

NEXDNS_API_TOKEN=nxd_xxx \
lego --dns nexdns \
    --domains example.com \
    --domains '*.example.com' \
    --email admin@example.com \
    run

Konfiguracja Traefik

Dodaj resolver wyzwania DNS NexDNS do konfiguracji Traefik. Poniższy przykład docker-compose.yml przedstawia typową konfigurację:

services:
  traefik:
    image: traefik:v3
    command:
      - "--certificatesresolvers.nexdns.acme.dnschallenge=true"
      - "--certificatesresolvers.nexdns.acme.dnschallenge.provider=nexdns"
      - "--certificatesresolvers.nexdns.acme.email=admin@example.com"
      - "--certificatesresolvers.nexdns.acme.storage=/letsencrypt/acme.json"
    environment:
      NEXDNS_API_TOKEN: "nxd_xxxxxxxxxxxxxxxxxxxx"
    volumes:
      - letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "443:443"

volumes:
  letsencrypt:

Następnie użyj resolvera w etykietach usługi:

labels:
  - "traefik.http.routers.myapp.tls.certresolver=nexdns"
  - "traefik.http.routers.myapp.tls.domains[0].main=example.com"
  - "traefik.http.routers.myapp.tls.domains[0].sans=*.example.com"

Certbot (Let's Encrypt)

certbot to oficjalny klient Let's Encrypt. Użyj wtyczki uwierzytelniania DNS NexDNS do automatycznej walidacji DNS-01.

Zainstaluj wtyczkę

pip install certbot-dns-nexdns

Utwórz plik danych uwierzytelniających

Utwórz ~/.nexdns/certbot-credentials.ini z tokenem API:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxx

Ogranicz uprawnienia pliku:

chmod 600 ~/.nexdns/certbot-credentials.ini

Wystawienie certyfikatu

certbot certonly \
    --authenticator dns-nexdns \
    --dns-nexdns-credentials ~/.nexdns/certbot-credentials.ini \
    -d '*.example.com'

Użycie z Docker

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    certbot/dns-nexdns certonly \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d '*.example.com'

Hook CLI

Jeśli Twój klient ACME obsługuje ręczne hooki DNS, możesz użyć CLI NexDNS jako skryptu hooka. Działa to z dowolnym klientem obsługującym opcje --manual-auth-hook i --manual-cleanup-hook (np. certbot w trybie ręcznym).

certbot z hookiem CLI

certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "nexdns acme hook --action create" \
    --manual-cleanup-hook "nexdns acme hook --action delete" \
    -d '*.example.com'

Hook odczytuje zmienne środowiskowe CERTBOT_DOMAIN i CERTBOT_VALIDATION ustawione przez certbot i automatycznie tworzy lub usuwa rekord TXT _acme-challenge.

CLI musi być uwierzytelnione przed użyciem hooków. Uruchom nexdns auth token nxd_xxx lub ustaw zmienną środowiskową NEXDNS_TOKEN.