Pular para o conteúdo

Domínio curinga (*.seudominio)

Escopo do token: domains:write (e projects:read para ler). O serviço precisa ser public.

Um domínio curinga (*.azarod.com) liga todos os subdomínios de um nível de um domínio seu a um único serviço. O serviço recebe o Host original e decide o que mostrar. Conta 1 domínio na cota, não importa quantos subdomínios existam.

  • Multi-tenant ou multi-estúdio: cada cliente ganha cliente.seusite.com sem você cadastrar um domínio por cliente. O app lê o Host e escolhe o conteúdo.
  • Ambientes efêmeros por branch, preview ou usuário, quando o app mesmo cria os nomes.
  • Não use se você tem poucos subdomínios fixos: domínios exatos são mais simples, e cada um pode apontar para um serviço diferente.
  1. Cadastre o curinga no serviço, com hostname no formato *.dominio (um único *, no início, seguido de ponto e de um domínio completo).

  2. Crie no seu DNS o que a resposta mandar:

    Registro Nome Valor
    CNAME *.azarod.com o alvo da resposta (dns.value, cname.<domínio de apps>)
    TXT _nebular-verify.azarod.com nebular-verify=<token> (de verification.value)
    • O TXT fica no apex do curinga (azarod.com), sem asterisco. O nome antigo _nebular-challenge.azarod.com também vale.
    • Se o seu provedor de DNS não aceita CNAME curinga, use A (e AAAA, se vierem) em *.azarod.com com os IPs de dns.alt.
    • Com Cloudflare, deixe os registros em DNS only (nuvem cinza); o proxy laranja é recusado (proxied).
  3. Verifique: espere o worker ou chame POST .../domains/{d}/verify até status ser active.

A verificação testa um nome aleatório sob o apex (algo como a1b2c3d4e5f6.azarod.com) e exige que ele resolva para a plataforma. Por isso criar só o registro sharkking.azarod.com não ativa o curinga: o registro precisa ser o curinga (*).

Janela do terminal
SUF=$(date +%s)-$RANDOM
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
-H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: curinga-proj-$SUF" \
-d "{\"name\": \"demo-curinga-$SUF\"}" | jq -r '.id')
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
-H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
-d "{\"visibility\": \"public\", \"slug\": \"demo-curinga-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r '.id')
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" \
-H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: curinga-add-$SUF" \
-d "{\"hostname\": \"*.curinga-$SUF.exemplo.test\"}"
{"id": "01jb7k6a5q8r7t2v4w6x8y0a4f", "hostname": "*.azarod.com", "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c", "status": "pending_dns",
"wildcard": true, "covers_example": "exemplo.azarod.com",
"dns": {"type": "CNAME", "name": "*.azarod.com", "value": "cname.nebularapp.xyz"},
"verification": {"type": "TXT", "name": "_nebular-verify.azarod.com", "value": "nebular-verify=7f3a9c"},
"primary": false, "redirect_code": 308,
"created_at": "2026-10-19T14:03:11Z"}

Os campos novos são wildcard (sempre true aqui) e covers_example (um exemplo de host coberto). O restante é igual ao de um domínio próprio, incluindo os estados.

Com o MCP da Nebular, as tools add_domain e list_domains já aceitam o curinga:

{"name": "add_domain",
"arguments": {"project": "01jb7k3a5q8r7t2v4w6x8y0a1b", "service": "01jb7k4a5q8r7t2v4w6x8y0a2c",
"hostname": "*.azarod.com", "idempotency_key": "azarod-curinga-1"}}

Entregue à pessoa os registros dns e verification do resultado (o agent não cria DNS) e depois chame list_domains até o status ser active.

POST /v1/projects/{p}/services/{s}/domains/{d}/verify (escopo domains:write, sem corpo) roda a checagem na hora e devolve o domínio com o diagnostic atualizado (reason, message, txt_found, shadowed). Com reason = no_records, falta o CNAME curinga; com txt_missing, falta o TXT no apex.

Para cada requisição a plataforma decide nesta ordem:

  1. Domínios da plataforma (<slug>.nebularapp.xyz, painel, auth) nunca entram na tabela de domínios.
  2. Domínio exato ativo vence sempre. Se loja.azarod.com está cadastrado (em qualquer serviço ou time) e ativo, ele serve loja.azarod.com, não o curinga. Remover o exato devolve o host ao curinga.
  3. Curinga ativo: *.azarod.com cobre um nível: sharkking.azarod.com.
  4. Fora do curinga:
    • o apex azarod.com não é coberto; se quiser servi-lo, cadastre azarod.com à parte (conta mais um na cota);
    • netos não são cobertos: a.sharkking.azarod.com precisa de *.sharkking.azarod.com, outro curinga.

Só domínio com status = active roteia e recebe certificado. Um curinga pending_dns, error (DNS caído) ou sem serviço não serve nada. O curinga serve direto: não redireciona, não envia Link: canonical e ignora a política de domínios do serviço. O HSTS configurado vale para todos os hosts cobertos.

O curinga nunca é o domínio primário e não redireciona nem pode ser alvo de redirect_to. Variáveis como PUBLIC_URL e NEBULAR_PRIMARY_DOMAIN continuam usando um domínio exato.

Na resposta, diagnostic.shadowed lista os domínios exatos ativos do seu time que estão sob o curinga (eles vencem), e shadowed_others conta os de outros times (o nome de outro time nunca aparece). Serve para você entender por que um host específico não cai no curinga.

Não existe certificado curinga. Cada host sob o curinga recebe o seu próprio certificado no primeiro acesso HTTPS, e a verificação não pede nenhuma chave nem token do seu DNS.

  • Teto por apex por hora. Para impedir que um curinga esgote a cota de emissão, a plataforma aprova no máximo 20 certificados novos por hora por apex (padrão; a instalação pode alterar com API_WILDCARD_ISSUE_PER_HOUR). Acima disso a emissão é recusada com 429 e Retry-After: 3600; o navegador (ou a requisição seguinte) tenta de novo e passa quando a janela libera. Hosts que já têm certificado não consomem o teto, nem os domínios exatos.
  • Limite do Let’s Encrypt. A autoridade pública limita 50 certificados por semana por domínio registrado. Um rollout de centenas de subdomínios novos pode levar dias para ter todos os certificados.
  • Recomendação: antes de um lançamento, pré-aqueça os subdomínios principais, acessando cada um por HTTPS (curl -sI https://sharkking.azarod.com) com antecedência, espalhado ao longo das horas. O primeiro acesso de um visitante a um host sem certificado pode demorar alguns segundos ou falhar por um instante (e funcionar na tentativa seguinte).

Detalhes gerais em TLS.

O curinga conta 1 em domains e em domains_per_service (Limites e cotas). A feature features.wildcard_domains do plano (GET /v1/limits e a conta) liga ou desliga o curinga; desligada, só o curinga é barrado e os domínios exatos continuam valendo. features.custom_domains desligada barra todos os domínios.

Resposta error Quando Como resolver
400 invalid_request nome fora do formato (*, **.x.com, a.*.x.com, *x.com), sufixo público (*.com.br, *.github.io, *.vercel.app) ou nome que cobriria a própria plataforma Use *.seudominio.com, um domínio que seja seu, com um único * no início.
409 domain_taken já existe um curinga igual ativo (ou desconfigurado) na plataforma, ou o seu time já tem o nome Publique o TXT de posse no apex para provar que é seu (veja Problemas comuns), ou remova o duplicado.
422 wildcard_not_allowed curinga com redirect_to, PATCH com primary: true, redirect_to num curinga, ou outro domínio redirecionando para um curinga Curinga serve direto; use um domínio exato para primário e redirecionamentos.
422 feature_not_allowed (feature) o plano não tem features.wildcard_domains (ou features.custom_domains) Peça a mudança de plano; domínios exatos seguem funcionando.
422 quota_exceeded (limit) cota de domínios do time ou do serviço Remova um domínio ou peça aumento (Limites e cotas).
422 rate_limited mais de 30 domínios criados na última hora pelo time Espere Retry-After.
429 (resposta do HTTPS do host, não da API) teto de emissões de certificado do apex Espere; o navegador tenta de novo. Veja acima.
404 not_found domínio de outro time ou serviço Confira os identificadores.

Um nome fora do formato volta 400:

Janela do terminal
SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
-d "{\"name\": \"demo-curinga-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
-d "{\"visibility\": \"public\", \"slug\": \"demo-curinga-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" -H "$H" -H "Content-Type: application/json" \
-d "{\"hostname\": \"a.*.exemplo.test\"}"
{"error": "invalid_request", "message": "Use o curinga no formato *.seudominio.com: um único * no início, seguido de ponto e de um domínio completo."}

O curinga que não ativa é diagnosticado como qualquer domínio: veja diagnostic.message (cita o registro curinga certo) e Problemas comuns.

Cenário: *.azarod.com aponta para um serviço Next.js; sharkking.azarod.com mostra o estúdio “sharkking”. O apex e o www ficam no site principal.

  1. Cadastre *.azarod.com no serviço da plataforma de estúdios (esta página).
  2. Cadastre azarod.com e www.azarod.com no serviço do site principal (domínios exatos; vencem o curinga no www).
  3. Cadastre como domínios exatos, em outros serviços, os nomes reservados que não são estúdios (api.azarod.com, auth.azarod.com, admin.azarod.com), ou trate-os no app, como abaixo.

Roteamento por Host no middleware.ts:

import { NextRequest, NextResponse } from 'next/server';
const APEX = 'azarod.com';
const RESERVADOS = new Set(['www', 'api', 'auth', 'admin', 'app', 'mail']);
// middleware roteia a requisição pelo Host: apex e www vão para o site principal, nomes reservados
// e hosts desconhecidos retornam 404 do próprio app, e o resto reescreve para a árvore do estúdio.
export function middleware(req: NextRequest) {
// A Nebular repassa o Host original e define x-forwarded-host com o host da requisição.
const host = (req.headers.get('x-forwarded-host') ?? req.headers.get('host') ?? '')
.toLowerCase().split(':')[0];
if (host === APEX || host === `www.${APEX}`) return NextResponse.next(); // site principal
if (!host.endsWith(`.${APEX}`)) return new NextResponse('Não encontrado', { status: 404 });
const estudio = host.slice(0, -(APEX.length + 1)); // só um nível: o curinga não cobre netos
if (!estudio || estudio.includes('.') || RESERVADOS.has(estudio) || !/^[a-z0-9-]{1,40}$/.test(estudio)) {
return new NextResponse('Não encontrado', { status: 404 });
}
const url = req.nextUrl.clone();
url.pathname = `/estudios/${estudio}${req.nextUrl.pathname}`;
const res = NextResponse.rewrite(url);
res.headers.set('x-estudio', estudio); // as páginas validam se o estúdio existe e dão notFound() se não
return res;
}
export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };

Boas práticas do caso multi-estúdio:

  • Host desconhecido = 404 do app. A plataforma entrega qualquer subdomínio do curinga ao serviço; quem sabe quais estúdios existem é o app. Faça a página do estúdio chamar notFound() quando ele não existir.
  • Reservados: trate www, api, auth, admin no app (404 ou redirecionamento) ou cadastre-os como domínios exatos em outros serviços (o exato vence).
  • Cookie de sessão SEM Domain=. Sem o atributo Domain, o cookie fica preso ao host que o criou (sharkking.azarod.com) e não vaza para os outros estúdios. Com Domain=.azarod.com, qualquer estúdio leria a sessão dos demais. Use também Secure, HttpOnly e SameSite=Lax.
  • NEXT_PUBLIC_* e URLs absolutas: monte a URL a partir do Host da requisição, não da variável PUBLIC_URL (que vem de um domínio exato).

Resumo para LLM:

  • Cadastrar: POST /v1/projects/{p}/services/{s}/domains com {"hostname": "*.dominio.com"}; escopo domains:write; o serviço precisa ser public. Pelo MCP: add_domain, depois list_domains.
  • Resposta traz wildcard: true, covers_example, dns (CNAME em *.dominio; alternativa A/AAAA em dns.alt) e verification (TXT _nebular-verify.<apex>, sem asterisco, no apex). Entregue esses registros a uma pessoa: o agent não cria DNS.
  • Acompanhe com GET ou verify até status = active; siga diagnostic.message se parar.
  • Cobre um nível; o apex e os netos não são cobertos; domínio exato ativo vence; curinga não é primário e não redireciona.
  • HTTPS por host no primeiro acesso; teto de 20 emissões/hora por apex (429 + Retry-After: espere e tente de novo, não é falha); limite do Let’s Encrypt de 50 certificados por semana por domínio registrado; pré-aqueça os hosts principais.
  • Erros: 400 invalid_request (nome), 409 domain_taken, 422 wildcard_not_allowed, 422 feature_not_allowed, 422 quota_exceeded. Não repita sem alterar a requisição.
  • O app roteia por Host/X-Forwarded-Host; host desconhecido deve responder 404 pelo próprio app; cookie de sessão sem Domain=.

Veja também Domínio próprio, Redirecionamentos, TLS e Referência de domínios.