> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-center/kilo-mioty-service-center/operations/operations-and-troubleshooting.md). # Operações e Resolução de Problemas Operações do KiloCenter — endpoints de saúde para KC-Core, KC-Gateway, KC-Identity, problemas comuns de arranque e diagnósticos. ### Objetivo Execute verificações repetíveis para problemas de arranque, problemas de conectividade e falhas no fluxo de mensagens. ### Verificações de saúde De `kilocenter-modules/`: ```bash # saúde do KC-Core curl -s http://localhost:8086/health # saúde do KC-Gateway curl -s http://localhost:8087/health # saúde do serviço gRPC grpcurl -plaintext localhost:9090 grpc.health.v1.Health/Check # todos os serviços do contentor docker compose ps ``` ### Verificações de portas Verifique se todos os serviços esperados estão a escutar: ```bash lsof -i :80 # KC-Web (modo contentor) lsof -i :9090 # KC-Gateway (gRPC-web) lsof -i :8086 # saúde do KC-Core lsof -i :8087 # saúde do KC-Gateway lsof -i :5000 # BSSCI lsof -i :5001 # SCACI lsof -i :50051 # gRPC interno do KC-Core lsof -i :5433 # PostgreSQL (Docker) lsof -i :6379 # Redis lsof -i :1883 # MQTT (se ativado) ``` A porta 5173 é usada apenas no modo de desenvolvimento a partir do código-fonte (servidor de desenvolvimento Vite). ### Operações no modo contentor ```bash # Ver logs de um serviço docker compose logs -f kilocenter docker compose logs -f kc-gateway docker compose logs -f kc-web # Reiniciar um único serviço docker compose restart kilocenter # Verificar o estado de todos os serviços docker compose ps ``` ### Ficheiros de registo (modo de desenvolvimento a partir do código-fonte) Todos os registos dos serviços são escritos em `kilocenter-modules/logs/runtime/`: ```bash # registos do KC-Core (atividade BSSCI, processamento de mensagens) tail -f logs/runtime/kc-core.log # registos do KC-Gateway (atividade do proxy da API) tail -f logs/runtime/kc-gateway.log # registos do KC-Web (servidor de desenvolvimento do frontend) tail -f logs/runtime/kc-web.log # Procurar erros em todos os registos grep -E "ERROR|FATAL" logs/runtime/*.log ``` ### Verificação da ligação à base de dados Verifique se o PostgreSQL está acessível: ```bash PGPASSWORD=changeme psql -U kilocenter -h localhost -p 5433 -d kilocenter -c "SELECT 1;" ``` Use a porta `5432` em vez de `5433` se estiver a executar o PostgreSQL diretamente no host (não via Docker). ### Parar serviços **Modo contentor:** ```bash docker compose down ``` **Modo de desenvolvimento a partir do código-fonte:** ```bash ./stop-all-services.sh # Parar também os contentores de infraestrutura docker compose stop postgres redis mosquitto ``` ### Problemas comuns | Sintoma | Causa | Correção | | ---------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | `dial tcp ...5432: connection refused` | Incompatibilidade da porta do PostgreSQL | Use `5433` para Docker, `5432` para instalação no host | | KC-Web mostra erros de gRPC | KC-Gateway não está em execução ou a porta está incorreta | Verifique o KC-Gateway na porta 9090; verifique a configuração do nginx no modo contentor | | `permission denied /var/run/docker.sock` | Pertencimento ao grupo Docker | Execute `sudo usermod -aG docker $USER` e volte a iniciar sessão | | `falha ao carregar o certificado TLS` | Ficheiros de certificado em falta ou inválidos | Execute `certgen` -- consulte Instalação | | Base station não está a ligar | Porta 5000 do BSSCI não está a escutar | Verifique se o KC-Core foi iniciado e se os certificados TLS estão configurados | | SCACI não está a aceitar ligações | Falta `scaci_tls` bloco de configuração | Verifique `config/config.docker.yaml` tem `scaci_host` e `scaci_tls` secção | | KC-Web devolve 502 para chamadas gRPC | nginx não consegue alcançar `kc-gateway:9090` | Verifique `kc-gateway` está saudável: `docker compose ps` | | `start-dev.sh` falha | Dependências não estão em execução | Inicie `docker compose up -d postgres redis mosquitto` primeiro | | Bun não encontrado | Ambiente de execução Bun não instalado | Instale o Bun: `curl -fsSL https://bun.sh/install \| bash` | | KC-Web carrega mas não mostra dados | KC-Core não está em execução ou não há base stations ligadas | Verifique os endpoints de saúde e o estado da base station | ### Sequência de recuperação **Modo contentor:** 1. Pare todos os serviços: `docker compose down` 2. Inicie todos os serviços: `docker compose up -d` 3. Execute as verificações de saúde (ver acima) **Modo de desenvolvimento a partir do código-fonte:** 1. Pare todos os serviços: `./stop-all-services.sh` 2. Reinicie a infraestrutura: `docker compose restart postgres redis mosquitto` 3. Inicie os serviços: `./start-dev.sh` 4. Execute as verificações de saúde (ver acima) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiloiot.io/kilo-docs-pt/kilo-center/kilo-mioty-service-center/operations/operations-and-troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.