mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-11-01 18:32:13 +00:00
761 lines
32 KiB
JSON
761 lines
32 KiB
JSON
{
|
|
"meta": {
|
|
"title": "API Proxmox Monitor — Referência de integração | ProxMenux",
|
|
"description": "Endpoints HTTP do ProxMenux Monitor para Home Assistant, Homepage, Grafana, Prometheus, n8n e painéis próprios. Consulta de estado e operações documentadas: controlo de VM, início de cópias, notificações e confirmação de alertas.",
|
|
"ogTitle": "API Proxmox Monitor — Referência de integração",
|
|
"ogDescription": "Endpoints do ProxMenux Monitor para Home Assistant, Homepage, Grafana, Prometheus, n8n e painéis próprios.",
|
|
"twitterTitle": "Monitor Proxmox API | ProxMenux",
|
|
"twitterDescription": "Endpoints para Home Assistant, Homepage, Grafana, Prometheus, n8n e painéis próprios."
|
|
},
|
|
"header": {
|
|
"title": "Referência da API",
|
|
"description": "Endpoints HTTP para consultar estado e executar ações documentadas: sensores Home Assistant, cartões Homepage, painéis Grafana, recolha Prometheus, fluxos n8n e scripts próprios. Inclui categorias, métricas exportadas e exemplos curl.",
|
|
"section": "ProxMenux Monitor"
|
|
},
|
|
"intro": {
|
|
"title": "Para que serve esta página",
|
|
"body": "Esta página reúne endpoints para integrações: leitura de dados, início de cópias, notificações próprias e confirmação de alertas. A API usa o processo Flask do painel na porta TCP <strong>8008</strong>. O endereço de escuta e TLS são descritos em <link>Acesso e autenticação</link>."
|
|
},
|
|
"headerEndpoint": "Endpoint",
|
|
"headerMethod": "Método",
|
|
"headerUse": "Utilização",
|
|
"auth": {
|
|
"heading": "Autenticação",
|
|
"intro": "Com autenticação ativa, os endpoints protegidos esperam um token JWT Bearer no cabeçalho:",
|
|
"tokensIntro": "Duas formas de obter o token:",
|
|
"items": [
|
|
"<strong>Tokens API, recomendados para integrações.</strong> Válidos por 365 dias, criados em <strong>Segurança → Tokens API</strong>. Têm nome e revogação individual. Use read_only para dados e full_admin apenas para ações administrativas necessárias.",
|
|
"<strong>Início de sessão, JWT de 24 horas.</strong> <code>POST /api/auth/login</code> com utilizador, palavra-passe e TOTP se exigido pela 2FA. O JWT expira após 24 horas; os scripts devem voltar a autenticar-se."
|
|
],
|
|
"flowLink": "Acesso, palavras-passe, 2FA, auditoria e TLS são descritos em <link>Acesso e autenticação</link>.",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/auth/login",
|
|
"method": "POST",
|
|
"use": "Campos do corpo (esquema): <code>'{'\"username\",\"password\",\"totp_token?\"'}'</code>. Devolve um JWT de 24 horas."
|
|
},
|
|
{
|
|
"endpoint": "/api/auth/api-tokens",
|
|
"method": "GET",
|
|
"use": "Listar os tokens API (apenas metadados — nomes, prefixos, datas; nunca o segredo real)."
|
|
},
|
|
{
|
|
"endpoint": "/api/auth/generate-api-token",
|
|
"method": "POST",
|
|
"use": "Cria um token API de 365 dias numa sessão autenticada. Campos: <code>password, token_name?, totp_token?, scope?</code>. Palavra-passe e TOTP exigido são verificados de novo. scope usa read_only por predefinição; full_admin exige escolha explícita. O segredo é devolvido uma só vez."
|
|
},
|
|
{
|
|
"endpoint": "/api/auth/api-tokens/<id>",
|
|
"method": "DELETE",
|
|
"use": "Revogar um token API específico pelo seu ID."
|
|
}
|
|
]
|
|
},
|
|
"conventions": {
|
|
"heading": "Convenções",
|
|
"items": [
|
|
"A maioria usa JSON. Algumas transferências devolvem texto simples; <code>/api/prometheus</code> usa o formato de exposição Prometheus 0.0.4 em vez de OpenMetrics. Verifique o tipo de resposta de cada rota.",
|
|
"Muitas operações devolvem <code>'{'\"success\": true, ...'}'</code>. Os erros variam; um formato habitual é <code>'{'\"success\": false, \"error\": \"'<'reason'>'\"'}'</code>. Verifique estado HTTP e campos: alguns desafios de autenticação usam HTTP 200 com success false.",
|
|
"Os parâmetros dependem do endpoint. Use <code>limit</code>, <code>offset</code>, <code>since</code> e filtros de categoria apenas quando suportados.",
|
|
"Os formatos de tempo variam: marcas Unix, cadeias ISO-8601 e datas systemd. Não presuma a mesma unidade nem um fuso horário explícito em todos os campos."
|
|
]
|
|
},
|
|
"system": {
|
|
"heading": "Sistema e hardware",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/system",
|
|
"method": "GET",
|
|
"use": "Valores atuais de CPU, memória, swap, tempo de atividade e carga."
|
|
},
|
|
{
|
|
"endpoint": "/api/info",
|
|
"method": "GET",
|
|
"use": "Informações estáticas do host: hostname, kernel, versão PVE, modelo CPU, distro."
|
|
},
|
|
{
|
|
"endpoint": "/api/system-info",
|
|
"method": "GET",
|
|
"use": "Dados alargados usados no cabeçalho: métricas gerais e hora de arranque."
|
|
},
|
|
{
|
|
"endpoint": "/api/hardware",
|
|
"method": "GET",
|
|
"use": "Inventário detalhado de hardware: dispositivos PCI, GPU e sensores."
|
|
},
|
|
{
|
|
"endpoint": "/api/hardware/live",
|
|
"method": "GET",
|
|
"use": "Valores atuais de sensores que variam rapidamente."
|
|
},
|
|
{
|
|
"endpoint": "/api/temperature/history",
|
|
"method": "GET",
|
|
"use": "Séries temporais das temperaturas da CPU e do encapsulamento."
|
|
},
|
|
{
|
|
"endpoint": "/api/gpu/<slot>/realtime",
|
|
"method": "GET",
|
|
"use": "Métricas atuais de GPU NVIDIA, Intel e AMD por posição PCI."
|
|
}
|
|
]
|
|
},
|
|
"actions": {
|
|
"heading": "Ações do sistema",
|
|
"intro": "Estas ações assíncronas usam unidades systemd temporárias. Com autenticação ativa, as escritas exigem <code>full_admin</code>; <code>read_only</code> pode consultar <code>.../status</code>. O início aceite devolve HTTP 202 e estado; consulte <code>.../status</code> para o progresso. Controlo de hóspedes e cópias usam respostas diferentes, descritas abaixo.",
|
|
"shapeTitle": "Forma de resposta comum",
|
|
"shapeIntro": "As ações de sistema assíncronas partilham este objeto JSON de estado. Controlo de hóspedes e cópias usam formatos diferentes:",
|
|
"shapeCode": "{\n \"unit\": \"proxmenux-action-pve-update.service\",\n \"state\": \"idle | running | success | failed | cancelled\",\n \"started_at\": \"Sat 2026-08-01 11:01:32 CEST\",\n \"finished_at\": null,\n \"exit_code\": null,\n \"result\": null\n}",
|
|
"concurrencyTitle": "Concurrência e cancelamento",
|
|
"concurrencyBody": "Iniciar outra execução da mesma ação ativa devolve HTTP 409. Só se pode cancelar com uma rota DELETE documentada, como na atualização PVE. O estado passa a <code>cancelled</code> e preserva as datas. Os estados finais ficam na memória do processo e podem perder-se ao reiniciar o Monitor.",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/system/power/reboot",
|
|
"method": "POST",
|
|
"use": "Inicia o reinício do anfitrião Proxmox. A ligação HTTP pode fechar quando systemd inicia o encerramento."
|
|
},
|
|
{
|
|
"endpoint": "/api/system/power/reboot/status",
|
|
"method": "GET",
|
|
"use": "Estado do reinício atual ou anterior."
|
|
},
|
|
{
|
|
"endpoint": "/api/system/power/shutdown",
|
|
"method": "POST",
|
|
"use": "Desliga o anfitrião Proxmox, por exemplo em resposta ao sinal de encerramento da UPS."
|
|
},
|
|
{
|
|
"endpoint": "/api/system/power/shutdown/status",
|
|
"method": "GET",
|
|
"use": "Estado do encerramento atual ou anterior."
|
|
},
|
|
{
|
|
"endpoint": "/api/system/pve-update/run",
|
|
"method": "POST",
|
|
"use": "Inicia a atualização PVE usada por Atualizar agora do Health Monitor e pelo menu da shell; delega em update-pve-safe.sh."
|
|
},
|
|
{
|
|
"endpoint": "/api/system/pve-update/status",
|
|
"method": "GET",
|
|
"use": "Estado da atualização PVE atual ou anterior."
|
|
},
|
|
{
|
|
"endpoint": "/api/system/pve-update",
|
|
"method": "DELETE",
|
|
"use": "Cancela uma atualização PVE em curso com SIGTERM."
|
|
},
|
|
{
|
|
"endpoint": "/api/proxmenux/self-update/run",
|
|
"method": "POST",
|
|
"use": "Atualiza o ProxMenux com o instalador do canal estável ou beta configurado. Uma unidade systemd própria permite continuar durante o reinício de proxmenux-monitor feito pelo instalador."
|
|
},
|
|
{
|
|
"endpoint": "/api/proxmenux/self-update/status",
|
|
"method": "GET",
|
|
"use": "Estado da atualização ProxMenux atual ou anterior."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/control",
|
|
"method": "POST",
|
|
"use": "Envia um comando de controlo de VM ou LXC. <code>action</code> aceita <code>start</code>, <code>stop</code>, <code>shutdown</code> ou <code>reboot</code>. A resposta bem-sucedida devolve uma tarefa PVE confirmada, sem indicar que terminou. Consulte o endpoint control-task do hóspede para o resultado."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/backup",
|
|
"method": "POST",
|
|
"use": "Cria uma cópia vzdump de uma VM ou LXC. Campos do corpo, todos opcionais exceto se as predefinições não corresponderem à organização do armazenamento: <code>storage</code> (um armazenamento PVE), <code>mode</code> (<code>snapshot</code>, <code>suspend</code> ou <code>stop</code>), <code>compress</code> (<code>zstd</code>, <code>lzo</code>, <code>gzip</code> ou <code>none</code>), <code>protected</code> (<code>true</code> ou <code>false</code>), <code>notes</code> e <code>pbs_change_detection</code> (<code>default</code>, <code>legacy</code> ou <code>data</code>). Devolve o UPID da tarefa PVE."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/backups",
|
|
"method": "GET",
|
|
"use": "Listar backups anteriores para um VM ou LXC em todos os armazenamentos alcançáveis."
|
|
}
|
|
],
|
|
"syncVsAsyncTitle": "Dois tipos de ações",
|
|
"syncVsAsyncBody": "Energia e atualizações do anfitrião usam unidades systemd temporárias com <code>.../status</code>. Só a atualização PVE tem aqui uma rota <code>DELETE</code> para cancelar. O controlo VM/LXC devolve uma tarefa a acompanhar; a cópia um UPID de trabalho em segundo plano. Aceitação não significa conclusão. Autenticação e permissões dependem da rota.",
|
|
"curlTitle": "Exemplo curl",
|
|
"curlBody": "Inicia uma atualização PVE e acompanha até terminar, como uma automação Home Assistant ou um playbook Ansible.",
|
|
"curlCode": "TOKEN=<your full_admin token>\n\ncurl -sSf -X POST \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://<host>:8008/api/system/pve-update/run\n\nwhile true; do\n state=$(curl -sSf -H \"Authorization: Bearer $TOKEN\" \\\n https://<host>:8008/api/system/pve-update/status | jq -r .state)\n [ \"$state\" != \"running\" ] && break\n sleep 30\ndone\necho \"final state: $state\"",
|
|
"haTitle": "Exemplo para Home Assistant",
|
|
"haBody": "Um sensor <code>rest</code> consulta o estado e <code>rest_command</code> inicia a atualização. Use-os com um botão do painel e as automações pretendidas:",
|
|
"haCode": "# configuration.yaml\nsensor:\n - platform: rest\n resource: https://pve.local:8008/api/system/pve-update/status\n name: pve_update_state\n value_template: \"{{ value_json.state }}\"\n scan_interval: 60\n headers:\n Authorization: \"Bearer !secret proxmenux_token\"\n\nrest_command:\n pve_update:\n url: https://pve.local:8008/api/system/pve-update/run\n method: POST\n headers:\n Authorization: \"Bearer !secret proxmenux_token\"\n\n # Start VM 100 (works for LXC too — same endpoint)\n vm_100_start:\n url: https://pve.local:8008/api/vms/100/control\n method: POST\n content_type: 'application/json'\n payload: '{\"action\": \"start\"}'\n headers:\n Authorization: \"Bearer !secret proxmenux_token\"\n\n # Backup VM 100 to the 'pbs-main' storage\n vm_100_backup:\n url: https://pve.local:8008/api/vms/100/backup\n method: POST\n content_type: 'application/json'\n payload: '{\"storage\": \"pbs-main\", \"mode\": \"snapshot\", \"compress\": \"zstd\"}'\n headers:\n Authorization: \"Bearer !secret proxmenux_token\""
|
|
},
|
|
"health": {
|
|
"heading": "Monitor de Saúde",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/health",
|
|
"method": "GET",
|
|
"use": "Verificação leve que devolve JSON com <code>status</code>, <code>timestamp</code> e <code>version</code>. Serve para palavras-chave do Uptime Kuma; com autenticação ativa, o cliente deve enviar o cabeçalho Bearer."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/status",
|
|
"method": "GET",
|
|
"use": "Estado global: um nível de gravidade e um resumo."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/details",
|
|
"method": "GET",
|
|
"use": "As dez categorias com estado e dados estruturados de cada verificação."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/full",
|
|
"method": "GET",
|
|
"use": "Dados completos: categorias, erros ativos, alertas dispensados e definições de silenciamento. Usa resultados de fundo com menos de seis minutos; caso contrário, ou numa atualização forçada, faz nova verificação."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/active-errors",
|
|
"method": "GET",
|
|
"use": "Lista ativa, filtrada por <code>?category=<name></code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/dismissed",
|
|
"method": "GET",
|
|
"use": "Alertas dispensados com as horas de silenciamento restantes."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/settings",
|
|
"method": "GET",
|
|
"use": "Duração do silenciamento configurada por categoria."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/remote-storages",
|
|
"method": "GET",
|
|
"use": "Inventário de armazenamentos remotos definidos por Proxmox, com estado online."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/interfaces",
|
|
"method": "GET",
|
|
"use": "Interfaces de rede com tipo (bridge / bond / física), IP e velocidade da ligação."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/acknowledge",
|
|
"method": "POST",
|
|
"use": "Corpo: <code>'{'\"error_key\":\"smart_sdh\"'}'</code>. Silencia um alerta durante o período configurado para a categoria."
|
|
},
|
|
{
|
|
"endpoint": "/api/health/cleanup-orphans",
|
|
"method": "POST",
|
|
"use": "Limpeza manual de erros cujo dispositivo subjacente ou VM desapareceu. Idempotente."
|
|
}
|
|
],
|
|
"outro": "Os formatos das respostas e as categorias são descritos em <link>Health Monitor</link>."
|
|
},
|
|
"storage": {
|
|
"heading": "Armazenamento",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/storage",
|
|
"method": "GET",
|
|
"use": "Discos visíveis pelo anfitrião: dispositivos de blocos, pools ZFS e LVM."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/summary",
|
|
"method": "GET",
|
|
"use": "Resumo compacto usado nos cartões do painel."
|
|
},
|
|
{
|
|
"endpoint": "/api/proxmox-storage",
|
|
"method": "GET",
|
|
"use": "Armazenamentos definidos por Proxmox de <code>/etc/pve/storage.cfg</code> com estado online e espaço livre."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/observations",
|
|
"method": "GET",
|
|
"use": "Histórico persistente: avisos SMART, erros de E/S e eventos ZFS. Mantém-se após a resolução automática dos alertas."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/<disk>",
|
|
"method": "GET",
|
|
"use": "Atributos SMART atuais para um disco."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/<disk>/latest",
|
|
"method": "GET",
|
|
"use": "Mais recente SMART auto-teste para o disco."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/<disk>/history",
|
|
"method": "GET",
|
|
"use": "Lista de relatórios SMART armazenados para o disco."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/<disk>/history/<file>",
|
|
"method": "GET",
|
|
"use": "Leia um relatório SMART armazenado específico."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/<disk>/test",
|
|
"method": "POST",
|
|
"use": "Inicia um autoteste SMART. Esquema do corpo: <code>'{'\"test_type\":\"short\"|\"long\"'}'</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/schedules",
|
|
"method": "GET",
|
|
"use": "Listar os testes SMART programados atualmente."
|
|
},
|
|
{
|
|
"endpoint": "/api/storage/smart/tools",
|
|
"method": "GET",
|
|
"use": "Verifica se <code>smartctl</code> e as ferramentas associadas estão instalados."
|
|
}
|
|
]
|
|
},
|
|
"network": {
|
|
"heading": "Rede",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/network",
|
|
"method": "GET",
|
|
"use": "Todas as interfaces com o estado de ligação e endereços."
|
|
},
|
|
{
|
|
"endpoint": "/api/network/summary",
|
|
"method": "GET",
|
|
"use": "Visualização compacta usada pelo painel."
|
|
},
|
|
{
|
|
"endpoint": "/api/network/<iface>/metrics",
|
|
"method": "GET",
|
|
"use": "RX/TX por interface, contadores de erros e séries temporais RRD."
|
|
},
|
|
{
|
|
"endpoint": "/api/network/latency/current",
|
|
"method": "GET",
|
|
"use": "Última medição de latência até ao gateway."
|
|
},
|
|
{
|
|
"endpoint": "/api/network/latency/history",
|
|
"method": "GET",
|
|
"use": "Série temporal de latência do gateway."
|
|
}
|
|
]
|
|
},
|
|
"vms": {
|
|
"heading": "VMs e contêineres",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/vms",
|
|
"method": "GET",
|
|
"use": "VM e CT do nó local com estado, vmid e nome."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>",
|
|
"method": "GET",
|
|
"use": "Detalhes completos de um sistema convidado: configuração, rede e discos."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/metrics",
|
|
"method": "GET",
|
|
"use": "Séries temporais de CPU, memória e E/S de disco de um sistema convidado (RRD)."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/logs",
|
|
"method": "GET",
|
|
"use": "Registos de tarefas recentes desse hóspede."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/backups",
|
|
"method": "GET",
|
|
"use": "Cópias de segurança guardadas para este sistema convidado."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/control",
|
|
"method": "POST",
|
|
"use": "Escolha uma ação do esquema: <code>'{'\"action\":\"start|stop|reboot|shutdown\"'}'</code>. Controla a alimentação do sistema convidado."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/backup",
|
|
"method": "POST",
|
|
"use": "Inicia <code>vzdump</code> para o hóspede. O corpo indica armazenamento e modo (<code>snapshot</code> / <code>suspend</code> / <code>stop</code>)."
|
|
},
|
|
{
|
|
"endpoint": "/api/vms/<vmid>/config",
|
|
"method": "PUT",
|
|
"use": "Atualizar o campo de descrição (notas) de um VM / CT. Outras chaves de configuração não são modificáveis a partir deste endpoint."
|
|
},
|
|
{
|
|
"endpoint": "/api/node/metrics",
|
|
"method": "GET",
|
|
"use": "Métricas agregadas do nó em séries RRD."
|
|
}
|
|
]
|
|
},
|
|
"backups": {
|
|
"heading": "Cópias de segurança",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/backups",
|
|
"method": "GET",
|
|
"use": "Cópias encontradas nos armazenamentos dir, NFS, CIFS e PBS consultados através do nó local. Não percorre todos os nós do cluster."
|
|
},
|
|
{
|
|
"endpoint": "/api/backup-storages",
|
|
"method": "GET",
|
|
"use": "Armazenamentos indicados como destinos de cópias, com espaço livre."
|
|
}
|
|
]
|
|
},
|
|
"logs": {
|
|
"heading": "Registos, tarefas, eventos",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/logs",
|
|
"method": "GET",
|
|
"use": "Entradas filtradas no diário. Consulta: <code>?level=&service=&limit=</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/logs/download",
|
|
"method": "GET",
|
|
"use": "Exporta o intervalo filtrado como texto simples."
|
|
},
|
|
{
|
|
"endpoint": "/api/events",
|
|
"method": "GET",
|
|
"use": "Fluxo de eventos internos — o mesmo que alimenta notificações."
|
|
},
|
|
{
|
|
"endpoint": "/api/task-log/<upid>",
|
|
"method": "GET",
|
|
"use": "Registo completo em texto simples de uma tarefa Proxmox identificada por UPID."
|
|
}
|
|
]
|
|
},
|
|
"notifications": {
|
|
"heading": "Notificações e IA",
|
|
"intro": "Envio, canais e reformulação com IA são descritos em <notifLink>Notificações</notifLink> e <aiLink>Assistente de IA</aiLink>.",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/notifications",
|
|
"method": "GET",
|
|
"use": "Notificações recentes apresentadas no painel."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/download",
|
|
"method": "GET",
|
|
"use": "Exporta as notificações como texto."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/status",
|
|
"method": "GET",
|
|
"use": "Estado do envio: processo de fundo ativo, tamanho da fila e último envio."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/settings",
|
|
"method": "GET",
|
|
"use": "Lê a configuração das notificações: canais, controlos por evento, reformulação IA e nome apresentado."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/history",
|
|
"method": "GET",
|
|
"use": "Histórico de envio. Parâmetros: <code>?limit=&offset=&severity=&channel=</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/history",
|
|
"method": "DELETE",
|
|
"use": "Limpa a tabela do histórico de envio."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/test",
|
|
"method": "POST",
|
|
"use": "Envia uma notificação de teste a um canal. Corpo: <code>'{'\"channel\":\"telegram\"'}'</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/send",
|
|
"method": "POST",
|
|
"use": "Emite um evento personalizado. Corpo: <code>'{'\"event_type\":\"custom\",\"severity\":\"WARNING\",\"title\":\"...\",\"body\":\"...\",\"data\":'{''}''}'</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/test-ai",
|
|
"method": "POST",
|
|
"use": "Testa a ligação ao fornecedor de IA. Campos do corpo (esquema): <code>'{'\"provider\",\"api_key\",\"model\",\"ollama_url?\"'}'</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/provider-models",
|
|
"method": "POST",
|
|
"use": "Listar modelos disponíveis para o fornecedor de IA selecionado."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/proxmox/setup-webhook",
|
|
"method": "POST",
|
|
"use": "Registar o Monitor como alvo webhook em <code>/etc/pve/notifications.cfg</code>."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/proxmox/cleanup-webhook",
|
|
"method": "POST",
|
|
"use": "Remova o alvo Monitor da configuração de notificação do PVE."
|
|
},
|
|
{
|
|
"endpoint": "/api/notifications/proxmox/read-cfg",
|
|
"method": "GET",
|
|
"use": "Leia o <code>notifications.cfg</code> atual do PVE como ele vê."
|
|
}
|
|
]
|
|
},
|
|
"security": {
|
|
"heading": "Segurança (leitura)",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/security/firewall/status",
|
|
"method": "GET",
|
|
"use": "Estado de firewall PVE e regras ativas."
|
|
},
|
|
{
|
|
"endpoint": "/api/security/fail2ban/details",
|
|
"method": "GET",
|
|
"use": "Estado do jail Fail2Ban; exige esse componente opcional instalado."
|
|
},
|
|
{
|
|
"endpoint": "/api/security/fail2ban/activity",
|
|
"method": "GET",
|
|
"use": "Eventos recentes Fail2Ban: bloqueios, desbloqueios e arranques do jail."
|
|
},
|
|
{
|
|
"endpoint": "/api/security/lynis/status",
|
|
"method": "GET",
|
|
"use": "Estado do Lynis: instalação e data da última análise."
|
|
},
|
|
{
|
|
"endpoint": "/api/security/lynis/report",
|
|
"method": "GET",
|
|
"use": "Último relatório Lynis: avisos, sugestões e índice de reforço da segurança."
|
|
},
|
|
{
|
|
"endpoint": "/api/security/tools",
|
|
"method": "GET",
|
|
"use": "Detecte quais ferramentas de segurança opcionais (Fail2Ban, Lynis) estão instaladas."
|
|
}
|
|
]
|
|
},
|
|
"proxmenuxIntegration": {
|
|
"heading": "Integração ProxMenux",
|
|
"rows": [
|
|
{
|
|
"endpoint": "/api/proxmenux/update-status",
|
|
"method": "GET",
|
|
"use": "Disponibilidade de atualização do ProxMenux Monitor, versão instalada e mais recente."
|
|
},
|
|
{
|
|
"endpoint": "/api/proxmenux/installed-tools",
|
|
"method": "GET",
|
|
"use": "Lista de cada otimização pós-instalação ProxMenux atualmente registrada no host (de <code>/usr/local/share/proxmenux/installed_tools.json</code>)."
|
|
},
|
|
{
|
|
"endpoint": "/api/proxmenux/tool-source/<key>",
|
|
"method": "GET",
|
|
"use": "Código da função pós-instalação associada, extraído dos scripts atuais do anfitrião ou de código antigo preservado. Não garante uma cópia do código executado originalmente."
|
|
}
|
|
]
|
|
},
|
|
"prometheus": {
|
|
"heading": "Métricas Prometheus",
|
|
"intro": "O endpoint autenticado <code>GET /api/prometheus</code> devolve o formato de texto Prometheus 0.0.4. Cada métrica inclui <code>node=\"<hostname>\"</code> e uma marca temporal explícita. Recolha com Prometheus ou outra base temporal compatível.",
|
|
"exportedTitle": "métricas exportadas",
|
|
"headerGroup": "Grupo",
|
|
"headerMetric": "Métrica",
|
|
"headerDesc": "Descrição",
|
|
"groups": [
|
|
{
|
|
"group": "Sistema",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_cpu_usage",
|
|
"desc": "Percentagem de utilização da CPU, tipo gauge."
|
|
},
|
|
{
|
|
"metric": "proxmox_memory_total_bytes",
|
|
"desc": "Memória física total em bytes."
|
|
},
|
|
{
|
|
"metric": "proxmox_memory_used_bytes",
|
|
"desc": "Memória utilizada em bytes."
|
|
},
|
|
{
|
|
"metric": "proxmox_memory_usage_percent",
|
|
"desc": "Percentagem de utilização da memória."
|
|
},
|
|
{
|
|
"metric": "proxmox_load_average",
|
|
"desc": "Média de carga do sistema. Rótulo <code>period=\"1m\" | \"5m\" | \"15m\"</code>."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "Tempo de atividade",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_uptime_seconds",
|
|
"desc": "Segundos desde o último arranque."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "Hardware",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_cpu_temperature_celsius",
|
|
"desc": "Temperatura do encapsulamento da CPU."
|
|
},
|
|
{
|
|
"metric": "proxmox_disk_temperature_celsius",
|
|
"desc": "Temperatura por disco. Rótulo <code>disk</code>."
|
|
},
|
|
{
|
|
"metric": "proxmox_fan_speed_rpm",
|
|
"desc": "Velocidades das ventoinhas. Rótulo <code>fan</code>."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "Espaço em disco",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_disk_total_bytes",
|
|
"desc": "Capacidade total de cada entrada de disco exportada. Rótulo <code>disk</code>."
|
|
},
|
|
{
|
|
"metric": "proxmox_disk_used_bytes",
|
|
"desc": "Capacidade utilizada de cada entrada de disco exportada."
|
|
},
|
|
{
|
|
"metric": "proxmox_disk_usage_percent",
|
|
"desc": "Percentagem utilizada de cada entrada de disco exportada."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "Rede",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_network_bytes_sent_total",
|
|
"desc": "Total de bytes enviados, tipo counter."
|
|
},
|
|
{
|
|
"metric": "proxmox_network_bytes_received_total",
|
|
"desc": "Total de bytes recebidos, tipo counter."
|
|
},
|
|
{
|
|
"metric": "proxmox_interface_bytes_sent_total",
|
|
"desc": "Bytes enviados por interface. Rótulo <code>interface</code>."
|
|
},
|
|
{
|
|
"metric": "proxmox_interface_bytes_received_total",
|
|
"desc": "Bytes recebidos por interface."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "VMs / CTs",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_vms_total",
|
|
"desc": "Número total de VMs e LXCs."
|
|
},
|
|
{
|
|
"metric": "proxmox_vms_running",
|
|
"desc": "Número de sistemas convidados em execução."
|
|
},
|
|
{
|
|
"metric": "proxmox_vms_stopped",
|
|
"desc": "Número de convidados parados."
|
|
},
|
|
{
|
|
"metric": "proxmox_vm_status",
|
|
"desc": "Estado por VM/CT: 1 em execução, 0 nos restantes estados. Rótulos <code>node</code>, <code>vmid</code> e <code>name</code>."
|
|
},
|
|
{
|
|
"metric": "proxmox_vm_cpu_usage",
|
|
"desc": "Utilização de CPU por VM/CT, com os mesmos rótulos."
|
|
},
|
|
{
|
|
"metric": "proxmox_vm_memory_used_bytes / _max_bytes",
|
|
"desc": "Memória utilizada e máximo configurado por VM/CT."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "GPU",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_gpu_temperature_celsius",
|
|
"desc": "Temperatura GPU. Rótulos <code>slot</code> e <code>vendor</code>; gpu inclui também o nome da GPU."
|
|
},
|
|
{
|
|
"metric": "proxmox_gpu_utilization_percent",
|
|
"desc": "Percentagem de utilização da GPU."
|
|
},
|
|
{
|
|
"metric": "proxmox_gpu_memory_total_bytes",
|
|
"desc": "Memória total da GPU."
|
|
},
|
|
{
|
|
"metric": "proxmox_gpu_power_draw_watts",
|
|
"desc": "Potência consumida pela GPU em watts."
|
|
},
|
|
{
|
|
"metric": "proxmox_gpu_clock_speed_mhz",
|
|
"desc": "Frequência do núcleo da GPU."
|
|
},
|
|
{
|
|
"metric": "proxmox_gpu_memory_clock_mhz",
|
|
"desc": "Frequência da memória da GPU."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "UPS",
|
|
"metrics": [
|
|
{
|
|
"metric": "proxmox_ups_battery_charge_percent",
|
|
"desc": "Percentagem de carga da bateria."
|
|
},
|
|
{
|
|
"metric": "proxmox_ups_load_percent",
|
|
"desc": "Carga actual na UPS."
|
|
},
|
|
{
|
|
"metric": "proxmox_ups_runtime_seconds",
|
|
"desc": "Autonomia estimada em bateria."
|
|
},
|
|
{
|
|
"metric": "proxmox_ups_input_voltage_volts",
|
|
"desc": "Tensão de entrada."
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"scrapeTitle": "Configuração de recolha do Prometheus",
|
|
"scrapeIntro": "Com autenticação ativa, adicione um token API ao cabeçalho Bearer da configuração de recolha Prometheus:",
|
|
"perHostTitle": "Recolha por anfitrião",
|
|
"perHostBody": "Cada instância exporta métricas do seu anfitrião. Num cluster, configure Prometheus para consultar cada nó. O rótulo <code>node</code> distingue as séries no Grafana (<code>proxmox_vms_running'{'node=\"pve01\"'}'</code>)."
|
|
},
|
|
"puttingItTogether": {
|
|
"heading": "Combinar as integrações",
|
|
"body": "Consulte <link>Integrações</link> para ligar os endpoints a sensores Home Assistant, cartões Homepage, painéis Grafana, fluxos n8n e outras ferramentas. Inclui configurações habituais copiáveis de cada plataforma. Esta página reúne o catálogo de endpoints."
|
|
},
|
|
"whereNext": {
|
|
"heading": "Para continuar",
|
|
"items": [
|
|
{
|
|
"label": "Acesso e autenticação",
|
|
"href": "/docs/monitor/access-auth",
|
|
"tail": " — criação de tokens, registo de auditoria, jail Fail2Ban opcional e TLS."
|
|
},
|
|
{
|
|
"label": "Notificações",
|
|
"href": "/docs/monitor/notifications",
|
|
"tailRich": " — conteúdo de <code>data</code> por evento ao chamar <code>/api/notifications/send</code>."
|
|
},
|
|
{
|
|
"label": "Assistente de IA",
|
|
"href": "/docs/monitor/ai-assistant",
|
|
"tailRich": " — funcionamento de <code>/api/notifications/test-ai</code> e <code>/api/notifications/provider-models</code>."
|
|
},
|
|
{
|
|
"label": "Monitor de Saúde",
|
|
"href": "/docs/monitor/health-monitor",
|
|
"tailRich": " — formato das respostas de <code>/api/health/*</code> e significado das dez categorias."
|
|
}
|
|
]
|
|
}
|
|
}
|