huaweicloud/huawei-cloud-obs-website-host

Huawei Cloud OBS Website Host

Visão Geral

Configure um bucket OBS existente da Huawei Cloud para alojamento de site estático com o Huawei Cloud OBS Python SDK e registre um domínio personalizado para o site.

Use esta habilidade quando o usuário quiser:

• ativar ou reparar o alojamento de site estático OBS
• definir um documento de índice ou documento de erro
• tornar o site acessível através de um domínio personalizado apoiado pelo endpoint do site estático OBS
• adicionar ou reparar um domínio personalizado, incluindo Huawei Cloud DNS quando aplicável
• diagnosticar problemas 403, 404 ou DNS em um site OBS alojado

Aspecto Ideal

Esta habilidade realiza operações de escrita: ativa o alojamento de site estático num bucket (setBucketWebsite) e regista o domínio personalizado necessário nesse bucket (setBucketCustomDomain). Quando o usuário o solicita, também cria/atualiza registos DNS. Estas escritas são executadas pelos scripts incluídos nesta própria sessão da habilidade — não são simuladas, diferidas ao usuário, ou substituídas por verificações só de leitura. A verificação é executada após as escritas para confirmar o resultado.

• O bucket tem o alojamento de site estático ativado por esta habilidade.
• O bucket pode servir index.html a partir do endpoint do site.
• Utilizadores anónimos podem ler o conteúdo do site.
• Um caminho inexistente devolve a página de erro configurada ou um 404 limpo.
• Um domínio personalizado é registado por esta habilidade e resolve para o endpoint do site OBS através do DNS. Um domínio personalizado é obrigatório — o domínio padrão do bucket OBS não é permitido para pré-visualização online de objetos devido a requisitos de conformidade de segurança.
• A configuração não é considerada completa até que o domínio personalizado esteja registado no bucket e resolva corretamente.
• O endpoint do site OBS é utilizado, não o endpoint normal da API do bucket.
• Um 403 geralmente tem duas causas comuns: a leitura anónima/pública não está ativada no bucket ou nos objetos, ou as AK/SK usadas para operações OBS não têm as permissões IAM necessárias.
• Um 404 geralmente significa que o nome do documento de índice ou o caminho de upload está errado.

Conformidade de Segurança: Requisito de Domínio Personalizado

Com base nos requisitos de conformidade de segurança da Huawei Cloud, o nome de domínio padrão do bucket OBS (<bucket_name>.obs.<region>.myhuaweicloud.com) está proibido de ser usado para pré-visualização online de objetos dentro do bucket. Um domínio personalizado é, portanto, obrigatório para alojamento de site estático.

Se o usuário não tiver um domínio personalizado preparado:

1. Primeiro pergunte ao usuário onde o site será implantado (região/jurisdição de implantação) e onde o domínio será registado. Aplique apenas requisitos específicos da região (como o ICP filing) quando a região de implantação realmente os exigir.
2. Direcione o usuário para registar um domínio através do Serviço de Registo de Domínios da Huawei Cloud, ou outros sites comuns de registo de domínios.
3. Se (e apenas se) a região de implantação do usuário for a China continental, o domínio também deve completar o ICP filing (网站备案) antes de poder ser usado para alojamento de site. Para implantações fora da China continental, este passo não é necessário — não o imponha.
4. Apenas após a verificação da região e, quando aplicável, a confirmação do registo/filing do domínio, a configuração do alojamento de site estático deve prosseguir.

Importante: Não prossiga com a configuração do alojamento de site estático até que o pré-requisito do domínio personalizado seja confirmado. O domínio OBS padrão não é uma alternativa válida para acesso ao site, mesmo no ambiente de teste.

Entradas Necessárias

Recolha estas antes de fazer alterações:

• region
• bucket_name
• custom_domain (obrigatório — veja a secção de Conformidade de Segurança acima)
• index_document (opcional, padrão: index.html)
• error_document (opcional)
• dns_zone ou contexto de conta DNS (opcional; necessário apenas se o usuário quiser alterações no Huawei Cloud DNS nesta execução)

Presuma que os ficheiros do site estático já foram carregados pelo usuário.

Dependências

A habilidade depende dos seguintes componentes de execução/ferramentas:

• Python 3.10+ (necessário para scripts/set_obs_website_sdk.py e scripts/verify_obs_website.py)
• Pacote Huawei OBS Python SDK: esdk-obs-python
• obsutil (para gerar e manter a configuração de credenciais .obsutilconfig)
• Credenciais Huawei Cloud AK/SK (a partir de .obsutilconfig)
• Acesso de rede ao endpoint OBS e ao endpoint do site
• CLI hcloud (necessária apenas quando esta habilidade gere operações de registo DNS na Huawei Cloud)
• dig / nslookup (opcional)

Comando de instalação:

pip install esdk-obs-python

Âmbito de Capacidade e Permissão

Esta habilidade declara a sua capacidade e âmbito de permissão exatos para que quem a invoca e os revisores saibam o que pode e não pode fazer antes de a invocar:

O que pode escrever (modificar):

• A configuração do site do bucket OBS especificado pelo usuário apenas (setBucketWebsite: documento de índice, documento de erro), via scripts/set_obs_website_sdk.py.
• A ligação do domínio personalizado nesse mesmo bucket (setBucketCustomDomain), incluindo uma ligação opcional de certificado HTTPS.
• Registos DNS numa zona DNS da Huawei Cloud apenas quando o usuário solicita explicitamente alterações no Huawei Cloud DNS nesta execução e fornece/especifica a zona (hcloud DNS CreateRecordSet).
• Estas são alterações viradas para produção: podem afetar o tráfego web ativo para o domínio personalizado e tornar o conteúdo do bucket acessível publicamente. Avisos são dados antes de cada escrita (veja Fluxo de Trabalho).

Credenciais lidas (e suas fontes):

• scripts/set_obs_website_sdk.py e scripts/verify_obs_website.py leem credenciais de, por ordem de prioridade: (1) flags da CLI --access-key/--secret-key/--security-token, (2) variáveis de ambiente HW_ACCESS_KEY / HW_SECRET_KEY / HW_SECURITY_TOKEN, (3) ~/.obsutilconfig local. hcloud usa o seu próprio perfil CLI configurado para operações DNS.
• Apenas a presença de credenciais é reportada; os valores nunca são impressos, ecoados ou escritos em disco.

Acesso de rede:

• Apenas ao endpoint do serviço OBS (https://obs.<region>.myhuaweicloud.com), ao endpoint do site OBS e (apenas quando solicitado) ao serviço Huawei Cloud DNS da região configurada.

O que nunca faz:

• Nunca carrega, elimina ou modifica objetos/conteúdo dentro do bucket.
• Nunca toca em buckets, domínios, zonas DNS ou credenciais diferentes dos que o usuário especificou.
• Nunca cria cron jobs, scripts de inicialização ou ficheiros de estado, e nunca persiste nada entre sessões (veja "Comportamento da Sessão" abaixo).
• Nunca expõe ou encaminha as credenciais que lê a terceiros.

Comportamento da Sessão

Esta habilidade realiza uma operação de sessão única e imediata: executa as chamadas à API OBS/DNS solicitadas durante a execução atual e depois termina. Não cria cron jobs, lança scripts, daemons em segundo plano ou ficheiros de estado, e não persiste configuração para execuções posteriores. Cada invocação é independente e deve ser acionada pelo usuário; nada é agendado ou repetido automaticamente. Qualquer passo de longa duração ou agendado externamente (por exemplo, esperar pela propagação DNS) é descrito ao usuário como algo a verificar, não sendo instalado como uma tarefa por esta habilidade.

Divulgação e Confirmação de Credenciais

Porque scripts/set_obs_website_sdk.py lê credenciais da cloud do seu ambiente ou do ~/.obsutilconfig local e depois altera a configuração remota do bucket/DNS, executá-lo tem um impacto real de segurança. Antes de o executar, deve:

1. Divulgar ao usuário que o script lerá credenciais das suas flags da CLI / variáveis de ambiente / ~/.obsutilconfig, e modificará a configuração do site do bucket remoto e o domínio personalizado (e DNS, se solicitado).
2. Obter a confirmação do usuário de que o nome do bucket, domínio personalizado e zona DNS (se houver) estão corretos e que autoriza a alteração.
3. Apenas após essa confirmação, executar o script.

Referência da CLI hcloud

Carregue references/cli-installation-guide.md quando for necessária a instalação e configuração da CLI hcloud ou do obsutil. Carregue references/hcloud-dns-obs-website.md ao criar ou gerir registos CNAME DNS para domínios personalizados de site estático OBS (guia passo a passo com comandos hcloud DNS CreateRecordSet).

Nota de segurança:

• Nunca codifique AK/SK em scripts ou ficheiros verificados.
• Prefira variáveis de ambiente para scripts SDK e armazenamento de perfil local seguro para uso da CLI.

Dependência de Configuração do obsutil

Carregue references/cli-installation-guide.md quando precisar de orientação de instalação do obsutil ou configuração do .obsutilconfig.

O script auxiliar do Python SDK (scripts/set_obs_website_sdk.py) lê credenciais por omissão de:

1. Flags da CLI (--access-key, --secret-key, --security-token)
2. Variáveis de ambiente (HW_ACCESS_KEY, HW_SECRET_KEY, HW_SECURITY_TOKEN)
3. .obsutilconfig

Se ak/sk estiverem vazios em todas as fontes, o script deve parar e pedir ao usuário para preencher as chaves em falta no .obsutilconfig (ou fornecer credenciais via CLI/env).

Regra de verificação de credenciais:

• Apenas reporte presença/ausência de chaves (ak, sk, securitytoken).
• Nunca imprima valores de credenciais durante as verificações.
• Nunca imprima linhas completas do .obsutilconfig na consola.
• Trate a saída da consola como contexto do modelo; qualquer valor divulgado é um incidente de segurança.

Exemplos de verificação segura (apenas estado, sem valores secretos):

Linux/macOS:

CFG="${HOME}/.obsutilconfig"
if [ ! -f "$CFG" ]; then
  echo "obsutilconfig_exists=false"
  echo "ak_configured=false"
  echo "sk_configured=false"
  echo "securitytoken_configured=false"
else
  awk -F= '
    BEGIN { ak=0; sk=0; st=0 }
    /^[[:space:]]*#/ { next }
    /^[[:space:]]*(ak|access_key_id)[[:space:]]*=/ { if ($2 ~ /[^[:space:]]/) ak=1 }
    /^[[:space:]]*(sk|secret_access_key)[[:space:]]*=/ { if ($2 ~ /[^[:space:]]/) sk=1 }
    /^[[:space:]]*(securitytoken|security_token|token)[[:space:]]*=/ { if ($2 ~ /[^[:space:]]/) st=1 }
    END {
      print "obsutilconfig_exists=" (ak || sk || st ? "true" : "false")
      print "ak_configured=" (ak ? "true" : "false")
      print "sk_configured=" (sk ? "true" : "false")
      print "securitytoken_configured=" (st ? "true" : "false")
    }
  ' "$CFG"
fi

Windows (PowerShell):

$cfg = Join-Path $HOME ".obsutilconfig"
if (-not (Test-Path $cfg)) {
  "obsutilconfig_exists=false"
  "ak_configured=false"
  "sk_configured=false"
  "securitytoken_configured=false"
} else {
  $lines = Get-Content $cfg
  $ak = $false; $sk = $false; $st = $false
  foreach ($line in $lines) {
    if ($line -match '^\s*#') { continue }
    if ($line -match '^\s*(ak|access_key_id)\s*=\s*(\S.*)$') { $ak = $true }
    if ($line -match '^\s*(sk|secret_access_key)\s*=\s*(\S.*)$') { $sk = $true }
    if ($line -match '^\s*(securitytoken|security_token|token)\s*=\s*(\S.*)$') { $st = $true }
  }
  "obsutilconfig_exists=true"
  "ak_configured=$ak"
  "sk_configured=$sk"
  "securitytoken_configured=$st"
}

Não use:

• cat ~/.obsutilconfig
• grep -E "ak|sk|token" ~/.obsutilconfig

Intenção de Uso do Script

Use os scripts incluídos por padrão para as tarefas para as quais foram construídos. Estes scripts realizam as operações de escrita que esta habilidade anuncia — não são verificadores só de leitura:

• scripts/set_obs_website_sdk.py escreve a configuração do site do bucket (setBucketWebsite) e regista o domínio personalizado (setBucketCustomDomain) no bucket especificado. Use-o sempre que a tarefa for ativar, reparar ou alterar as definições de alojamento de site estático OBS. Lê credenciais conforme declarado em Âmbito de Capacidade e Permissão e requer confirmação do usuário antes de escrever (veja Divulgação e Confirmação de Credenciais).
• scripts/verify_obs_website.py verifica o endpoint do site publicado (DNS, HTTP, HTTPS) e executa verificações só de leitura do SDK (bucket/região). Use-o após qualquer alteração na configuração do site, e também quando o usuário perguntar se o site está acessível ou ao diagnosticar comportamento 403/404.
• Não substitua estes scripts por código ad hoc avulso, a menos que o script em si esteja avariado e precise de ser corrigido; corrigir um script avariado é o único caso em que escreve chamadas SDK OBS diretamente.
• Use os scripts para manter o manuseamento de credenciais, a construção de objetos SDK e o comportamento de verificação consistentes entre execuções.

Fluxo de Trabalho

1. Verifique se o runtime Python e o SDK OBS estão disponíveis (pip install esdk-obs-python se em falta).
2. Verifique o pré-requisito do domínio personalizado (veja a secção Conformidade de Segurança):
   • Confirme que custom_domain foi fornecido pelo usuário.
   • Pergunte ao usuário onde o site será implantado (região/jurisdição) antes de aplicar qualquer requisito específico da região. Se o usuário não tiver um domínio e a região de implantação for a China continental, guie-o para registar um em Registo de Domínios da Huawei Cloud e completar o ICP filing (网站备案). Para implantações fora da China continental, não imponha o ICP filing. Pare aqui e aguarde que o usuário complete este passo.
   • Verifique se o usuário gere o DNS no Huawei Cloud DNS ou com um fornecedor externo.
   • Se as alterações no Huawei Cloud DNS fizerem parte desta execução, verifique se o hcloud está instalado e autenticado.
   • Se o DNS for gerido fora da Huawei Cloud ou fora desta execução, recolha essa restrição explicitamente antes de prosseguir.
3. Verifique se o bucket existe na região solicitada (use o Método de Verificação de Existência e Região do Bucket abaixo).
4. Verifique se quem chama tem permissão para atualizar as definições do site do bucket.
5. Verifique se a leitura anónima é permitida para os ficheiros do site (use o método em Método de Verificação de Leitura Anónima abaixo).
6. Não carregue ou modifique objetos de conteúdo do site (index.html, ativos, etc.). Presuma que o conteúdo já existe no bucket.
7. Confirme antes de escrever. Diga ao usuário que o próximo passo lê as suas credenciais da cloud (variáveis de env / ~/.obsutilconfig) e modifica a configuração do site do bucket remoto e a ligação do domínio personalizado (e DNS, se solicitado), e que estas são alterações viradas para produção que afetam o tráfego ativo. Apenas após a confirmação prossiga. Depois execute scripts/set_obs_website_sdk.py com --custom-domain <domain> (use index.html se index_document não for fornecido).
   • O script existe para manter a construção de objetos SDK consistente e para garantir que o manuseamento de credenciais, validação de entrada e passos de verificação são executados de forma fiável.
8. Execute a verificação pós-escrita com scripts/verify_obs_website.py.

...

[truncado para tradução]