White-Label AI API Крайни точки: персонализирани домейни, TLS автоматизация и безопасно за клиента маршрутизиране

CNAME на клиент, сочещ към вашия шлюз, не създава готова за производство брандирана крайна точка. DNS записът може да се разреши, преди да е наличен сертификат, сертификатът може да се подновява само докато записите за валидиране остават непокътнати, а неотметнато заглавие Host може да насочи заявка към грешен контекст на клиента.

По-безопасният модел е всяко брандирано име на хост да се третира като траен ресурс на контролната равнина. Собствеността, издаването на сертификат, прекъсването на DNS, активирането на маршрутизирането, спирането и изтриването изискват изрично състояние. По време на заявка името на хоста стеснява разрешения контекст на клиента, докато ключът API остава границата за оторизация.

Разделете жизнения цикъл на домейна на независими проверки

Не представяйте персонализиран домейн с едно логическо значение като verified. Проследете най-малко четири независими условия:

• Собственост: Клиентът доказал ли е контрола върху името на хоста?
• Сертификат: Издаден ли е и внедрен ли е валиден сертификат на ръба?
• DNS: Дали авторитетна DNS точка към очакваната цел на шлюза?
• Маршрутизиране: Точното име на хост свързано ли е с активен клиент и профил за маршрутизиране?

Това разделяне отразява документирано поведение на крайния доставчик. Управляваните продукти с потребителско име на хост могат да използват различни записи и състояния за собственост на име на хост и валидиране на сертификат. Поради това DNS резолюцията сама по себе си не доказва, че крайната точка е готова.

Една практическа държавна машина е:

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

Това са бизнес състояния, а не директни копия на статуси на доставчик. Съхранявайте необработения статус на доставчика отделно, след което извлечете собственото си състояние според документираните инварианти. Например, маркирайте домейн ready само когато собствеността е валидна, сертификатът е активен, DNS сочи към очакваната цел и крайният маршрут е активиран.

Препоръка: направете преходите монотонни по време на първоначалното активиране. Преходна успешна TLS сонда не трябва да пропуска проверката на собствеността или проверките за маршрутизиране. След активиране съгласуването може да премести домейн от ready в suspended или изрично влошено състояние, когато тези инварианти спрат да се поддържат.

Съхраняване на домейн като първокласен ресурс

Запис на домейн за оперативен бял етикет AI API шлюз трябва да съдържа достатъчно информация, от която да се възстанови ambiguous API calls and provider 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"
}

Нормализирайте името на хоста към ASCII с малки букви, като използвате библиотека, поддържаща IDNA, преди проверки за уникалност. Премахнете крайна точка и отхвърлете IP литерали, URL пътища, портове, заместващи знаци, освен ако не се поддържат изрично, и имена извън приетата от вас политика за публичен суфикс. Запазете изпратения формуляр за показване само като неавторитетни метаданни.

Наложете глобално ограничение за уникалност на нормализираното име на хост. Двама наематели никога не трябва да могат да претендират за едно и също правомощие, дори когато използват различно изписване с главни букви или Unicode представяния.

Потвърдете предварително, преди да промените производствения DNS

Когато крайната платформа го поддържа, издайте и внедрите сертификата, преди да поискате от клиента да промени производствения CNAME.Типична последователност е:

1. Създаване на ресурс на домейн с ключ за идемпотентност.
2. Връщане на записите за собственост и потвърждение на сертификат.
3. Проучване или получаване на събития от доставчик, докато и двете потвърждения успеят.
4. Потвърдете, че сертификатът е внедрен за точното име на хост.
5. Помолете клиента да насочете производствения CNAME към целта на шлюза.
6. Разрешаване на авторитетен DNS от повече от едно мрежово местоположение.
7. Активиране на маршрута и извършване на удостоверена сонда от край до край.
8. Маркиране на домейна ready.

Факт: управляван Документацията на SaaS-edge описва последователности за миграция с нулево време на престой, при които валидирането и издаването на сертификат се извършват преди промяната на производствения CNAME. Компромис: това избягва видим пропуск при активиране на TLS, но изисква клиентът да създаде допълнителни TXT, CNAME или делегирани записи за валидиране.

Ако предварителното валидиране не е налично, посочете изрично вероятното прекъсване. Не обещавайте нулев престой, когато издаването на сертификат започне само след като трафикът се премести.

Маршрут по точен орган, след което оторизирайте ключа

Довереният край трябва да поддържа точен разрешен списък от име на хост до разрешен клиент или контекст на марка:

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

Отхвърляне на неизвестни, неактивни и двусмислени авторитети. Никога не ги изпращайте на наемател по подразбиране. За HTTP/1.1 потвърдете Host; за HTTP/2 и HTTP/3, потвърдете :authority. Когато TLS се прекратява на същия ръб, сравнете органа за заявка със SNI и контекста на сертификата, както се поддържа от проксито.

Препращащите заглавки изискват същата дисциплина. Публичният край трябва да премахне входящите X-Forwarded-Host, Forwarded и всички вътрешни заглавки на клиента, след което да добави каноничен хост и сигнал за разрешен клиент. Произходът трябва да приема тези сигнали само през удостоверени връзки от край към източник.

Поредицата за упълномощаване по време на изпълнение трябва да бъде:

1. Разрешаване на нормализираните права чрез списъка с разрешени активни имена на хостове.
2. Удостоверяване на ключа API независимо.
3. Зареждане на неизменния идентификатор на клиента прикачен към ключа.
4. Уверете се, че клиентът на ключа е разрешен на разрешеното име на хост.
5. Приложете модел, бюджет, ограничение на скоростта и политика за маршрутизиране, като използвате идентификационни номера на клиент и ключ.
6. Запишете записи за използване срещу тези неизменни идентификатори, а не името на хост.

Това запазва ролята на Партньор API автоматизация, без да превръща операция за управление на домейн в пряк път за оторизация.

Връщане 421 Misdirected Request, когато пълномощията не съответстват на конфигурирания произход или контекст на връзката. Върнете 403 Forbidden, когато името на хоста е валидно, но удостовереният ключ принадлежи на клиент, който няма право да го използва. Поддържайте телата на грешките достатъчно общи, за да не разкриват кой клиент притежава име на хост.

Съвместимост на канонична и брандирана крайна точка

Някои клиенти се нуждаят от един ключ, за да работят както на каноничната крайна точка на шлюза, така и на тяхната брандирана крайна точка. Това е приемливо само когато и двете имена на хост се разрешават в един и същ контекст на оторизиран клиент.Строгото обвързване на всеки ключ с едно име на хост намалява използването на различни марки, но усложнява миграциите и клиентите, които превключват между крайни точки.

Препоръка: моделира разрешените контексти на крайни точки като политика за ключове, вместо да сравнява низове в кода на приложението. Например ключът може да позволява tenant:any-active-hostname, brand:brand_42 или един точен domain_id.

Операциите за излагане на жизнения цикъл чрез партньора API

Минимален API трябва да поддържа създаване, проверка, повторно валидиране, спиране, възобновяване и изтриване:

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}

Операциите за създаване и изтриване трябва да приемат стабилни ключове за идемпотентност. Приложните програмни интерфейси (API) на доставчика, разпространението на DNS и изтичането на времето на мрежата могат да оставят обаждащия се несигурен дали операцията е успешна. Запазете записа на операцията, преди да извикате периферния доставчик, и върнете същия домейн или операция за изтриване, когато заявката се опита повторно със същия ключ и еквивалентен полезен товар.

Излъчване на подписани събития от жизнения цикъл като custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk и custom_domain.deleted. Събитията са известия, а не единственият източник на истина; потребителите трябва да могат да извличат текущото състояние след пропусната или дублирана доставка.

Непрекъснато съгласуване на DNS, сертификати и маршрутизиране

Активирането не е краят на жизнения цикъл. DNS записите се редактират, записите за валидиране изчезват, крайната конфигурация се отклонява и сертификатите се подновяват.

Изпълнете периодичен съгласувател, който проверява:

• Оторитетен DNS и очакваната CNAME или делегирана цел
• Име на хоста на доставчика и състояния на сертификати
• Имена на сертификати, изтичане и състояние на подновяване
• Наличие на необходими записи за валидиране на DNS
• Точно притежание на крайния маршрут и състояние на активиране
• Текущото право на наемателя да обслужва трафик

Автоматизирането на удостоверения с DNS-валидиране може да зависи от валидиращите CNAME записи, оставащи публично разрешими. Предупреждение преди изтичане, вместо да се предполага, че автоматичното подновяване винаги ще успее.

Използвайте ограничени повторни опити с експоненциално забавяне и трептене за операции със сертификати. Запазете акаунта в ACME и състоянието на поръчката, където извършвате директно издаване. Повтарящото се изтриване и повторно създаване може да изразходва ограничения за скоростта на поръчка на сертификат или регистриран домейн. Чакащите записи на имена на хостове може също да заемат квотата на доставчика, докато не бъдат изрично премахнати.

Оперативно предвиждане: без съгласуване, най-често срещаните грешки ще се появят след успешно включване, по време на редакции на DNS, подновяване на сертификат, отклонение от страна на доставчика или отлив на клиенти. Това е архитектурно очакване, а не измерен процент на неуспех.

Извън борда на две фази

Изтриването първо на реда на базата данни не е безопасно, тъй като крайните съпоставяния, сертификатите или DNS могат да го надживеят.Използвайте подлежащ на проверка двуфазен работен процес:

1. Преместете домейна на draining и спрете да го рекламирате за нови интеграции.
2. Решете дали съществуващите заявки получават кратък гратисен период или незабавно отхвърляне.
3. Деактивирайте крайния маршрут, така че името на хоста да не може да се преобразува в клиент по подразбиране.
4. Премахнете персонализираното име на хост и асоциацията на сертификат от доставчик.
5. Помолете клиента да премахне или замени DNS записа.
6. Уверете се, че DNS вече не сочи към вашата услуга.
7. Маркирайте ресурса deleted, като запазите идентификатори и запис за проверка.

Висящ CNAME, който е насочен към депровизирана услуга, може да създаде риск от поглъщане на поддомейн. Обратно, оставянето на остаряло картографиране активно може да продължи да изпраща трафик на бивш клиент през вашия край. Свържете почистването на доставчика и проверката на DNS към една и съща операция за изтриване, но запишете всеки резултат независимо.

Тествайте границата, а не само щастливия път

Преди да активирате клиентски домейни, автоматизирайте тестовете за съответствие за:

• Подправен Host или X-Forwarded-Host заглавие
• Конфликт на SNI и HTTP стойности на авторитет
• Неизвестно име на хост и известно, но спряно име на хост
• Валиден ключ от клиент A, използван на име на хост на клиент Б
• Дублирани заявки за създаване и изтриване със същия ключ за идемпотентност
• Същото име на хост, изпратено с регистър, крайна точка или варианти на Unicode
• DNS се промени от очакваната цел след активиране
• Премахнат запис за валидиране на сертификат преди подновяване
• Изтриването е прекъснато след премахване на съпоставянето на границите, но преди DNS промени

Също така проверете дали регистрационни файлове, таксуване, използване приписването, лимитите на скоростта и решенията за политики използват идентификатори на наематели и ключове. Имената на хостове са променливи входове за представяне и маршрутизиране; те не трябва да се превръщат във финансови самоличности или идентичности за сигурност.

Контролен списък за внедряване

• Нормализиране на имената на хостове и налагане на глобална уникалност.
• Проследяване на собствеността, сертификат, DNS и готовност за маршрут поотделно.
• Предварително валидиране на сертификати преди прекъсване, където поддържа се.
• Позволени точни авторитети в надеждния край.
• Отстранете ненадеждните заглавки за пренасочване и създайте удостоверен сигнал за произход.
• Упълномощавайте ключа API спрямо контекста на клиента на името на хоста.
• Използвайте 421 за произход или несъответствие на връзката и 403 за използване на ключ между наематели.
• Направете създаването и изтриването идемпотентни.
• Съгласувайте непрекъснато състоянието на доставчика, DNS, маршрутизирането и изправността на подновяването.
• Изрично изтрийте съпоставянията на границите и проверете DNS по време на изключване.

Брандираната крайна точка е готова само когато състоянието на контролната равнина и поведението на равнината на данните са съгласни.Моделирайте изрично това споразумение, тествайте отрицателните пътища и запазете ключа API като крайна граница за упълномощаване на наемател.

Свързано четене

• идемпотентен партньор API операции