Vender alojamento web com HestiaCP

O HestiaCP é o painel de controlo aberto mais saudável que há. Medido no GitHub a 21 de agosto de 2026: 4481 estrelas, 345 colaboradores e três lançamentos numa única semana. Dá contas, pacotes, DNS, correio, bases de dados e uma interface limpa, e não custa nada.

O que não dá é uma forma de vender qualquer disso. Não há formulário de encomenda, nem fatura, nem cobrança, nem «este cliente deixou de pagar, desliguem-no». Pesquise-se hestiacp billing e, medido no mesmo dia, os primeiros resultados são tópicos de fórum: pessoas a perguntar como vender contas HestiaCP, e outras a responder com meio script.

Esta página trata da camada por cima: o que a API do HestiaCP devolve na realidade, onde vai morder, e o que tem de estar certo antes de se poder colocar um botão Comprar diante de um desconhecido.

O que o HestiaCP já lhe dá

Duas coisas, e são as duas certas.

Os pacotes. Um pacote HestiaCP descreve o que uma conta pode usar: espaço em disco, largura de banda, e quantos domínios, bases de dados e caixas de correio. É o catálogo de produtos, definido uma vez e referido por nome de todo o resto.

Um ciclo de vida de conta que corresponde a uma subscrição. Criar, suspender, reativar, mover para outro pacote, eliminar, exatamente os estados por que passa uma conta de alojamento paga, e há um comando para cada:

O resto desta página trata da distância entre essa tabela e algo em que se possa confiar às três da manhã.

A API tem duas portas, e uma delas mente

POST https://host:8083/api/ aceita dois tipos de credenciais, e o que se envia decide que caminho de código trata o pedido. O caminho antigo usa um nome de utilizador e uma palavra-passe. O mais recente, disponível desde o HestiaCP 1.6, usa uma chave de acesso: um id de 20 caracteres e um segredo de 40 caracteres.

Não se comportam da mesma forma. Ao enviar um comando que não existe:

O caminho antigo comunica sucesso para um comando que nunca correu. A causa está no próprio código-fonte do HestiaCP: ele devolve OK assim que a autenticação devolveu zero e o comando não escreveu nada na saída padrão. Nunca olha para o código de saída do próprio comando, e nunca define um estado HTTP nem o cabeçalho de código de saída para o resultado. Qualquer comando que falhe em silêncio regressa como OK.

Por isso: use chaves de acesso. Não só porque o caminho antigo pode mentir, mas porque uma chave revoga-se por si só, figura no painel pelo nome, e não põe a palavra-passe de administrador do painel no cofre de outra pessoa. E também não se deve construir um recuo de uma para a outra: duas portas significam duas superfícies de erro, e aqui a porta de recuo é a que não é de confiança.

O estado HTTP não é a resposta: o código de saída é

O HestiaCP dobra cerca de vinte códigos de saída internos em quatro estados HTTP. Duas consequências, ambas medidas:

Uma mutação bem-sucedida devolve 204, não 200. Cada v-add-user, v-suspend-user, v-delete-user, v-add-web-domain e v-change-user-package regressou como HTTP 204 com um corpo vazio. Um cliente que só aceita 200 rejeita cada chamada que funcionou.

O HTTP 401 significa aqui quatro coisas diferentes: segredo errado (saída 9), chave fora das suas permissões (10), endereço não autorizado (10), e «este utilizador já está suspenso» (5). Um cliente que leia 401 como «credenciais erradas» anunciará que a chave expirou quando tudo o que se fez foi suspender uma conta duas vezes.

Leia-se Hestia-Exit-Code. O estado é apenas uma derivada.

O que o vai mesmo deitar abaixo

Cinco chamadas recusadas e o HestiaCP bane o seu endereço. Isto não é um limite de débito de que se possa recuar: é o fail2ban, configurado por predefinição com maxretry = 5 sobre /var/log/hestia/auth.log, e acaba num DROP de iptables. A partir daí o painel não recusa as chamadas, deixa de lhes responder: a monitorização mostra tempos esgotados e parece um problema de rede.

A parte que apanha as pessoas é o que conta como início de sessão falhado. Não só um segredo errado: a verificação de chave do HestiaCP escreve a mesma linha failed to login quando uma chave é usada para um comando fora do seu conjunto de permissões. Medido, no próprio registo de autenticação do painel:

12:57:52 <key> 84.85.173.142 v-list-users successfully launched
12:57:52 <key> 84.85.173.142 failed to login      ← um comando fora do âmbito da chave

Daqui decorrem três regras, e nenhuma é opcional:

1. 01Nunca repetir automaticamente após um erro de autenticação ou de permissão. Um ciclo de repetição sobre uma chave errada tranca-o do lado de fora num minuto, e nessa altura a mensagem que o cliente vê é «painel inacessível» em vez de «a chave está errada», o pior sinal possível, porque aponta para o problema errado.
2. 02A chave tem de ser sem restrições de âmbito, ou seja, a do administrador. Permissões vazias significam todos os comandos, e o HestiaCP só o aceita para o utilizador root. O conjunto de permissões billing fornecido de origem aproxima-se disso, mas deixa de fora v-list-user-packages e v-list-web-domains, os dois comandos que leem o catálogo de pacotes e os domínios de uma conta. Com esse conjunto, ambos regressam vazios, e uma chave restrita que lhes toque uma vez por ciclo de sondagem bane-o à hora certa.
3. 03O texto de erro tem de mencionar isto, porque levantar o banimento exige uma shell no painel: v-delete-firewall-ban <endereço> HESTIA.

Vazio significa ninguém

Mais uma armadilha da primeira utilização. O HestiaCP mantém em API_ALLOWED_IP uma lista dos endereços autorizados a usar a API. Numa instalação nova essa lista está vazia, e vazio aqui significa ninguém, não toda a gente. Cada chamada regressa com 401 e IP is not allowed to connect with API enquanto a chave está perfeitamente boa. Esta é a falha inicial mais provável de toda a integração, e merece a sua própria mensagem de erro em vez de um genérico «falha de autenticação».

Criar uma conta exige duas chamadas, e essa distância é real

O DirectAdmin, o cPanel e o Virtualmin criam uma conta juntamente com o seu domínio numa só chamada. O HestiaCP não:

v-add-user        USER PASSWORD EMAIL [PACKAGE] [NAME]   → cria o utilizador
v-add-web-domain  USER DOMAIN [IP] [RESTART] [ALIASES]   → liga o domínio

Se a segunda chamada falhar (o domínio já pertence a alguém, ou o seu formato é recusado), fica-se com um verdadeiro utilizador unix, com um diretório pessoal, sem site, e uma linha em cada contagem que se faça. Medido com um domínio propositadamente inválido: o utilizador existia a seguir com U_WEB_DOMAINS = 0. Tudo o que se construa tem de compensar: se o segundo passo falhar, elimine-se o utilizador e comunique-se o erro original.

O que o Provibr faz com tudo isto

O Provibr liga-se ao HestiaCP através de um agente que corre dentro da sua própria rede e faz a ligação para o exterior, pelo que nada no painel tem de ser exposto. Dão-se-lhe quatro coisas: o endereço do painel, incluindo a porta 8083, o id da chave de acesso, o segredo e (enquanto o painel ainda usar o seu certificado autoassinado) a impressão digital SHA-256 a fixar. O agente guarda-os no seu próprio cofre no seu anfitrião; a plataforma não os consegue reler.

A partir daí:

• Os pacotes tornam-se vendáveis. Um plano de alojamento web aponta para um pacote de uma integração, sob um nome próprio, a um preço próprio.
• Cinco ações, endereçadas pelo nome de utilizador: criar com um domínio e um pacote, suspender, reativar, mudar de pacote, eliminar. A criação em duas chamadas é compensada como descrito acima.
• A utilização vem grátis com a sondagem. Cada leitura de v-list-users transporta DISK_QUOTA, U_DISK, BANDWIDTH e U_BANDWIDTH para cada conta, tudo em megabytes, por isso limites e utilização chegam à página do servidor e aos gráficos sem uma segunda chamada que pudesse atrasar-se face à primeira.
• As contas que já existem podem ser importadas. O agente lista o que está no painel e assinala-se quais delas se tornam servidores no Provibr.

O que não faz

O Provibr gere contas, não o painel. Não instala o HestiaCP, não o atualiza, não altera definições do servidor, e não toca no DNS, nas caixas de correio ou nas bases de dados: isso fica no HestiaCP, onde o operador e os seus clientes continuam a usá-los. Não há consola para uma conta de alojamento, porque não há nada a que a ligar.

E uma nota de desempenho honesta: ler um painel com muitas contas custa uma chamada adicional por conta, porque o HestiaCP não tem qualquer comando que liste de uma vez os domínios de todas as contas. Medido em 26 contas, em série isso são cerca de 8,5 segundos; em paralelo regressa abaixo de dois. Quem escreva isto por si próprio, que não o faça em série: por volta das 60 contas, uma sondagem em série começa a colidir com a sua própria ronda seguinte.

Não é preciso escolher um painel e conformar-se com ele. O Provibr faz correr hoje os seus painéis de controlo, os seus hipervisores e os seus painéis de jogo lado a lado, sob um só inventário, um só modelo de permissões e um só registo de atividade. O HestiaCP para os clientes que querem um painel aberto, outra coisa para os que pedem o cPanel pelo nome, e um só lugar onde se veem ambos.