Punkty końcowe AI API z białą etykietą: domeny niestandardowe, automatyzacja TLS i routing bezpieczny dla dzierżawców

Klient CNAME wskazujący na Twoją bramę nie tworzy markowego punktu końcowego gotowego do produkcji. Rekord DNS może zostać rozwiązany, zanim certyfikat będzie dostępny, certyfikat może zostać odnowiony tylko wtedy, gdy rekordy sprawdzania poprawności pozostaną nienaruszone, a niezaznaczony nagłówek Host może skierować żądanie do niewłaściwego kontekstu dzierżawy.

Bezpieczniejszy model polega na traktowaniu każdej markowej nazwy hosta jako trwałego zasobu płaszczyzny kontrolnej. Własność, wydanie certyfikatu, przełączenie DNS, aktywacja routingu, zawieszenie i usunięcie wymagają wyraźnego stanu. W momencie żądania nazwa hosta zawęża dozwolony kontekst dzierżawy, podczas gdy klucz API pozostaje granicą autoryzacji.

Rozdziel cykl życia domeny na niezależne kontrole

Nie przedstawiaj domeny niestandardowej za pomocą pojedynczej wartości logicznej, takiej jak verified. Śledź co najmniej cztery niezależne warunki:

• Własność: Czy klient udowodnił kontrolę nad nazwą hosta?
• Certyfikat: Czy wydano i wdrożono ważny certyfikat na brzegu sieci?
• DNS: Czy autorytatywny DNS wskazuje na oczekiwany cel bramy?
• Routing: Czy dokładna nazwa hosta jest powiązana z aktywnym dzierżawcą i profilem routingu?

To oddzielenie odzwierciedla udokumentowane zachowanie dostawcy brzegowego. Produkty zarządzane z niestandardową nazwą hosta mogą używać różnych rekordów i statusów do własności nazwy hosta i sprawdzania poprawności certyfikatu. Dlatego samo rozpoznawanie DNS nie dowodzi, że punkt końcowy jest gotowy.

Praktyczna maszyna stanu to:

requested
  -> ownership_pending
  -> certificate_pending
  -> dns_pending
  -> ready
  -> suspended
  -> draining
  -> deleted

Są to stany biznesowe, a nie bezpośrednie kopie statusów dostawców. Przechowuj surowy status dostawcy oddzielnie, a następnie uzyskaj własny stan zgodnie z udokumentowanymi niezmiennikami. Na przykład oznacz domenę ready tylko wtedy, gdy jej własność jest ważna, certyfikat jest aktywny, DNS wskazuje oczekiwany cel i włączona jest trasa brzegowa.

Zalecenie: spraw, aby przejścia były monotoniczne podczas początkowej aktywacji. Przejściowa pomyślna sonda TLS nie powinna pomijać sprawdzania poprawności własności ani sprawdzania routingu. Po aktywacji uzgadnianie może przenieść domenę z ready na suspended lub do jawnego stanu zdegradowanego, gdy te niezmienniki przestaną być utrzymywane.

Przechowuj domenę jako zasób najwyższej klasy

Rekord domeny dla działającej bramy AI API z białą etykietą powinien zawierać wystarczającą ilość informacji, aby można było odzyskać siły po niejednoznacznych API wywołaniach i dostawca drift:

{
  "domain_id": "dom_01J...",
  "hostname_ascii": "api.customer.example",
  "tenant_id": "ten_01H...",
  "brand_id": "brand_42",
  "state": "certificate_pending",
  "ownership_method": "dns_txt",
  "ownership_record": {
    "name": "_gateway-verify.api.customer.example",
    "value": "verify=..."
  },
  "certificate_status": "pending_validation",
  "expected_cname": "customers.edge.example",
  "routing_profile_id": "route_openai_compatible_v3",
  "provider_hostname_id": "edge_8f2...",
  "creation_operation_id": "op_01J...",
  "last_reconciled_at": "2026-11-02T10:00:00Z",
  "last_reconciliation_result": "certificate_pending"
}

Normalizacja nazwy hosta do małych liter ASCII przy użyciu biblioteki obsługującej IDNA przed sprawdzeniem unikalności. Usuń końcową kropkę i odrzuć literały IP, ścieżki URL, porty, symbole wieloznaczne, jeśli nie są wyraźnie obsługiwane, oraz nazwy spoza zaakceptowanych zasad dotyczących sufiksów publicznych. Zachowaj przesłany formularz wyświetlany tylko jako nieautorytatywne metadane.

Wymuś globalne ograniczenie unikalności znormalizowanej nazwy hosta. Dwóch dzierżawców nigdy nie może mieć możliwości ubiegania się o te same uprawnienia, nawet jeśli używają różnych wielkich liter lub reprezentacji Unicode.

Wstępna weryfikacja przed zmianą produkcyjnego DNS

Jeśli platforma brzegowa to obsługuje, wystaw i wdróż certyfikat przed poproszeniem klienta o zmianę produkcyjnego rekordu CNAME.Typowa sekwencja jest następująca:

1. Utwórz zasób domeny za pomocą klucza idempotencji.
2. Zwróć zapisy własności i weryfikacji certyfikatu.
3. Odpytuj lub odbieraj zdarzenia dostawcy do czasu powodzenia obu weryfikacji.
4. Potwierdź, że certyfikat został wdrożony dla dokładnej nazwy hosta.
5. Poproś klienta o wskazanie produkcyjnego rekordu CNAME na bramie target.
6. Rozpoznaj autorytatywny DNS z więcej niż jednej lokalizacji sieciowej.
7. Włącz trasę i wykonaj uwierzytelnione kompleksowe badanie.
8. Zaznacz domenę ready.

Fakt: dokumentacja zarządzanej platformy SaaS-edge opisuje sekwencje migracji bez przestojów, w których weryfikacja i wydanie certyfikatu mają miejsce przed zmianą produkcyjnego rekordu CNAME. Kompromis: pozwala to uniknąć widocznej luki w aktywacji TLS, ale wymaga od klienta utworzenia dodatkowych rekordów TXT, CNAME lub delegowanych rekordów walidacyjnych.

Jeśli wstępna weryfikacja jest niedostępna, wyraźnie ujawnij prawdopodobne przerwanie. Nie obiecuj zerowych przestojów, jeśli wydawanie certyfikatów rozpocznie się dopiero po przeniesieniu ruchu.

Trasuj według dokładnych uprawnień, a następnie autoryzuj klucz

Zaufany brzeg powinien utrzymywać dokładną listę dozwolonych od nazwy hosta do dozwolonego kontekstu najemcy lub marki:

api.customer.example -> {
  tenant_id: "ten_01H...",
  brand_id: "brand_42",
  state: "ready"
}

Odrzuć nieznane, nieaktywne i niejednoznaczne uprawnienia. Nigdy nie wysyłaj ich do domyślnego dzierżawcy. Dla HTTP/1.1 zatwierdź Host; dla HTTP/2 i HTTP/3 zatwierdź :authority. Jeśli protokół TLS kończy się na tej samej krawędzi, porównaj organ żądania z SNI i kontekstem certyfikatu obsługiwanym przez serwer proxy.

Nagłówki przekazywania wymagają tej samej dyscypliny. Publiczna krawędź powinna usunąć przychodzące X-Forwarded-Host, Forwarded i wszelkie wewnętrzne nagłówki dzierżawców, a następnie dodać hosta kanonicznego i rozwiązany sygnał dzierżawcy. Źródło powinno akceptować te sygnały tylko w przypadku uwierzytelnionych połączeń brzegowych.

Sekwencja autoryzacji w czasie wykonywania powinna być następująca:

1. Rozwiąż znormalizowane uprawnienia poprzez listę dozwolonych nazw aktywnych hostów.
2. Niezależnie uwierzytelnij klucz API.
3. Załaduj niezmienny identyfikator dzierżawcy dołączony do klucz.
4. Sprawdź, czy dzierżawa klucza jest dozwolona dla rozpoznanej nazwy hosta.
5. Zastosuj model, budżet, limit stawek i zasady routingu, korzystając z identyfikatorów dzierżawy i klucza.
6. Zapisuj zapisy użycia według tych niezmiennych identyfikatorów, a nie nazwy hosta.

Zachowuje to rolę partnera API automatyzacja bez przekształcania operacji zarządzania domeną w skrót autoryzacyjny.

Zwróć 421 Misdirected Request, gdy uprawnienia nie odpowiadają skonfigurowanemu pochodzeniu lub kontekstowi połączenia. Zwróć 403 Forbidden, gdy nazwa hosta jest prawidłowa, ale uwierzytelniony klucz należy do dzierżawcy, któremu nie wolno go używać. Treści błędów powinny być na tyle ogólne, aby nie ujawniały, który dzierżawca jest właścicielem nazwy hosta.

Zgodność kanonicznego i markowego punktu końcowego

Niektórzy klienci potrzebują jednego klucza do pracy zarówno na kanonicznym punkcie końcowym bramy, jak i na swoim markowym punkcie końcowym. Jest to dopuszczalne tylko wtedy, gdy obie nazwy hostów odpowiadają temu samemu kontekstowi autoryzowanej dzierżawy.Ścisłe powiązanie każdego klucza z jedną nazwą hosta ogranicza użycie różnych marek, ale komplikuje migracje i klientów przełączających się między punktami końcowymi.

Zalecenie: model dopuszczał konteksty punktów końcowych jako zasady dotyczące kluczy, zamiast porównywać ciągi znaków w kodzie aplikacji. Na przykład klucz może umożliwiać tenant:any-active-hostname, brand:brand_42 lub dokładnie domain_id.

Udostępnianie operacji cyklu życia za pośrednictwem partnera API

Minimalny API powinien obsługiwać tworzenie, sprawdzanie, ponowną weryfikację, zawieszanie, wznawianie i usuwanie:

POST   /partner/v1/custom-domains
GET    /partner/v1/custom-domains/{domain_id}
POST   /partner/v1/custom-domains/{domain_id}/revalidate
POST   /partner/v1/custom-domains/{domain_id}/suspend
POST   /partner/v1/custom-domains/{domain_id}/resume
DELETE /partner/v1/custom-domains/{domain_id}

Operacje tworzenia i usuwania powinny akceptować stabilne klucze idempotencji. Interfejsy API dostawcy, propagacja DNS i przekroczenia limitu czasu sieci mogą sprawić, że osoba dzwoniąca nie będzie pewna, czy operacja się powiodła. Utrwalaj rekord operacji przed wywołaniem dostawcy brzegowego i zwracaj tę samą domenę lub operację usuwania, gdy żądanie zostanie ponowione z tym samym kluczem i równoważnym ładunkiem.

Emituj podpisane zdarzenia cyklu życia, takie jak custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk i custom_domain.deleted. Wydarzenia są powiadomieniami, a nie jedynym źródłem prawdy; konsumenci powinni mieć możliwość odzyskania bieżącego stanu po nieudanej lub zduplikowanej dostawie.

Ciągłe uzgadnianie DNS, certyfikatów i routingu

Aktywacja to nie koniec cyklu życia. Rekordy DNS są edytowane, rekordy sprawdzające znikają, konfiguracja brzegowa ulega zmianie, a certyfikaty zbliżają się do odnowienia.

Uruchom okresowe narzędzie uzgadniające, które sprawdza:

• Autorytatywny DNS i oczekiwaną nazwę CNAME lub delegowany cel
• Nazwę hosta dostawcy i stany certyfikatów
• Nazwy certyfikatów, wygaśnięcie i odnowienie health
• Obecność wymaganych rekordów weryfikacji DNS
• Dokładna własność trasy brzegowej i stan aktywacji
• Aktualne uprawnienia dzierżawcy do obsługi ruchu

Automatyzacja certyfikatów z walidacją DNS może zależeć od tego, czy rekordy CNAME weryfikacyjne pozostaną publicznie rozpoznawalne. Ostrzegaj przed wygaśnięciem, zamiast zakładać, że automatyczne odnowienie zawsze się powiedzie.

W przypadku operacji na certyfikatach używaj ograniczonych ponownych prób z wykładniczym wycofywaniem i fluktuacją. Zachowaj konto ACME i stan zamówienia, w którym bezpośrednio prowadzisz wydawanie. Powtarzające się usuwanie i ponowne odtwarzanie może spowodować wykorzystanie limitów kolejności certyfikatów lub zarejestrowanych domen. Oczekujące rekordy nazw hostów mogą również zużywać limit dostawcy, dopóki nie zostaną jawnie usunięte.

Przewidywanie operacyjne: bez uzgadniania najczęstsze awarie pojawią się po pomyślnym wprowadzeniu, podczas edycji DNS, odnowienia certyfikatu, zmiany dostawcy lub odejścia klienta. Jest to oczekiwanie architektoniczne, a nie zmierzony wskaźnik awaryjności.

Wyłączenie w dwóch fazach

Usunięcie najpierw wiersza bazy danych jest niebezpieczne, ponieważ mapowania brzegowe, certyfikaty lub DNS mogą to przetrwać.Użyj kontrolowanego dwufazowego przepływu pracy:

1. Przenieś domenę do draining i przestań ogłaszać ją w celu uzyskania nowych integracji.
2. Zdecyduj, czy istniejące żądania otrzymają krótki okres karencji czy natychmiastowe odrzucenie.
3. Wyłącz trasę brzegową, aby nazwa hosta nie mogła zostać rozpoznana jako dzierżawca domyślny.
4. Usuń niestandardową nazwę hosta i powiązanie certyfikatu z dostawca.
5. Poproś klienta o usunięcie lub zastąpienie rekordu DNS.
6. Sprawdź, czy DNS nie wskazuje już Twojej usługi.
7. Oznacz zasób deleted, zachowując identyfikatory i zapis audytu.

Wiszący rekord CNAME, którego celem jest wyrejestrowana usługa, może stworzyć ryzyko przejęcia subdomeny. I odwrotnie, pozostawienie aktywnego nieaktualnego mapowania może w dalszym ciągu przesyłać ruch byłego klienta przez Twoją krawędź. Połącz czyszczenie dostawcy i weryfikację DNS z tą samą operacją usuwania, ale zapisuj każdy wynik niezależnie.

Przetestuj granicę, a nie tylko bezpieczną ścieżkę

Przed włączeniem domen klientów zautomatyzuj testy zgodności dla:

• fałszywego nagłówka Host lub X-Forwarded-Host
• konfliktowego SNI i HTTP wartości uprawnień
• Nieznana nazwa hosta i znana, ale zawieszona nazwa hosta
• Prawidłowy klucz od dzierżawcy A używany w nazwie hosta dzierżawcy B
• Zduplikowane żądania tworzenia i usuwania za pomocą tego samego klucza idempotencji
• Ta sama nazwa hosta przesłana z wielkością liter, kropką na końcu lub kodem Unicode odmiany
• DNS zmienił się od oczekiwanego docelowego po aktywacji
• Usunięto rekord sprawdzania poprawności certyfikatu przed odnowieniem
• Usuwanie zostało przerwane po usunięciu mapowania brzegowego, ale przed zmianami DNS

Sprawdź także, czy dzienniki, rozliczenia, przypisanie użycia, limity stawek i decyzje dotyczące zasad korzystają z identyfikatorów dzierżaw i kluczy. Nazwy hostów to modyfikowalne dane wejściowe dotyczące prezentacji i routingu; nie powinny stać się tożsamościami finansowymi ani zabezpieczającymi.

Lista kontrolna wdrożenia

• Normalizuj nazwy hostów i wymuszaj globalną unikalność.
• Oddzielnie śledź własność, certyfikat, DNS i gotowość do trasy.
• Wstępna weryfikacja certyfikatów przed przełączeniem, jeśli jest to możliwe.
• Zezwalaj na listę dokładnych uprawnień pod adresem zaufana krawędź.
• Usuń niezaufane nagłówki przekazywania i utwórz uwierzytelniony sygnał pochodzenia.
• Autoryzuj klucz API w kontekście dzierżawy nazwy hosta.
• Użyj 421 w przypadku niezgodności źródła lub połączenia i 403 w przypadku użycia klucza między dzierżawcami.
• Utwórz i usuń idempotent.
• Ciągle uzgadniaj stan dostawcy, DNS, routing i stan odnawiania.
• Usuwaj jawnie mapowania brzegowe i weryfikuj DNS podczas odłączania.

Markowy punkt końcowy jest gotowy tylko wtedy, gdy stan płaszczyzny kontrolnej i zachowanie płaszczyzny danych są zgodne.Modeluj tę umowę jawnie, przetestuj ścieżki ujemne i zachowaj klucz API jako granicę autoryzacji ostatecznej dzierżawy.

Powiązane lektury

• idempotent Partner API operacje