> 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/project-overview.md).
# Visão Geral do Projeto
Visão geral do projeto KiloCenter — servidor de código aberto nativo de MIOTY com caminhos de implementação em Docker, host Linux e Kubernetes.
## KiloCenter - Servidor de Rede MIOTY de Código Aberto
KiloCenter é um servidor de rede MIOTY de código aberto para operar estações base, endpoints, tráfego de uplink e downlink, e integrações de aplicações em um centro de serviço auto-hospedado.
É um centro de serviço nativo de MIOTY, construído especificamente para a pilha MIOTY desde o início. Não é um fork, wrapper ou adaptação de outro servidor de rede LPWAN.
MIOTY é um protocolo LPWAN criado para resiliência a interferências, comunicação de longo alcance e grandes frotas de endpoints. O KiloCenter implementa o lado do centro de serviço dessa pilha com caminhos de implantação em Docker e em hosts Linux, integrações gRPC e MQTT, e um console de gestão web.
### Como se relaciona com o Kilo Cloud
KiloCenter Community Edition é o centro de serviço gratuito, de código aberto e auto-hospedado. Seu limite é a camada de rede MIOTY: estações base, endpoints, tráfego, operações do centro de serviço e interfaces que encaminham dados para outra aplicação.
A edição Enterprise do KiloCenter é incorporada ao **Kilo Cloud**. Escolha o Kilo Cloud quando a implantação também precisar do restante de uma plataforma IoT: dados de dispositivos normalizados, painéis visuais, gráficos históricos, um mecanismo visual de regras, acionadores de condição sustentada, alarmes e escalonamento, histórico de auditoria, controle de acesso e um assistente de IA. Os dispositivos MIOTY então usam esses recursos diretamente, em vez de exigir sistemas downstream separados.
| Escolha | Quando se aplica |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **KiloCenter Community Edition** | Você precisa de um centro de serviço MIOTY, quer operá-lo você mesmo e irá integrar seus dados gRPC ou MQTT nas suas próprias aplicações. |
| **Kilo Cloud** | Você quer que o centro de serviço Enterprise seja gerenciado para você e precisa de regras, visualização, alarmes ou outros recursos da plataforma Kilo em torno dos dados MIOTY. |
| **Plataforma Kilo IoT local** | Você precisa da plataforma Enterprise completa dentro de uma infraestrutura que você controla. |
Veja [KiloCenter ou Kilo Cloud?](/kilo-docs-pt/kilo-center/kilo-mioty-service-center.md#kilocenter-or-kilo-cloud) para a fronteira de recursos, ou comece com o [conector MIOTY do Kilo Cloud](/kilo-docs-pt/kilo-iot-server/connectors/mioty-connector.md).
### Demonstração ao vivo
Um ambiente de demonstração está disponível em
* **Usuário:** `demo [at] kiloiot.io`
* **Senha:** `demo1234`
> Substitua `[at]` por `@` ao iniciar sessão.
### Aviso de Uso em Produção
A edição comunitária é fornecida como está, sem suporte comercial. O uso em produção é por sua conta e risco.
Para implantações de produção com suporte, use o Kilo Cloud ou a Plataforma Kilo IoT on-premise (Fale com Vendas). A edição Enterprise do KiloCenter é incorporada ao Kilo Cloud e inclui suporte comercial, operação respaldada por SLA, multitenância e capacidades MIOTY opcionais, incluindo subcanais BSSCI, o anexo Variable MAC (VM) e suporte à extensão ReCon. O Kilo Cloud também acrescenta a plataforma completa em torno dos dados MIOTY: gerenciamento de dispositivos, normalização, painéis, regras, alarmes, histórico de auditoria, controle de acesso e operações assistidas por IA.
### Recursos
#### Servidor de Rede MIOTY
* **Protocolo MIOTY BSSCI v1.0.0** - comunicação entre estação base e centro de serviço com segurança TLS
* **Gerenciamento de Estações Base** - autenticação baseada em certificado e monitoramento de status
* **Gerenciamento de Endpoints** - registro de endpoints com propagação de anexos
* **Processamento de Mensagens** - tratamento de uplink e downlink com deduplicação
* **Operação com Múltiplas Estações Base** - cobertura compartilhada entre estações base em uma implantação auto-hospedada
* **Suporte à Divisão de Telegramas** - tratamento nativo do comportamento PHY MIOTY
* **Diversidade de Padrões** - suporte a transmissão com múltiplos padrões para robustez
* **Segurança** - tratamento de chaves de rede e aplicação AES-128
#### Recursos do Centro de Serviço
* **Interface BSSCI** - suporte ao protocolo entre estação base e centro de serviço
* **Interface SCACI** - suporte ao protocolo entre centro de serviço e centro de aplicações com TLS, persistência de sessão, monitoramento e fluxos de fila/status
* **Sistema de Eventos** - persistência centralizada de eventos e alertas
* **Gerenciamento de Certificados** - modelo de confiança baseado em CA com suporte a rotação e monitoramento
* **Particionamento de Banco de Dados** - armazenamento de mensagens particionado mensalmente
* **Sistema de Arquivamento** - suporte ao ciclo de vida e retenção de dados
* **Integração MQTT** - caminho de integração de aplicações com backend Mosquitto
* **API gRPC** - APIs de gerenciamento gRPC e gRPC-web por meio do KC-Gateway
#### Interface de Gerenciamento
* **Painel Web** - console de gestão baseado em React
* **Monitoramento em Tempo Real** - visualizações ao vivo de status, tráfego e alertas
* **Registro de Estações Base** - fluxos de provisionamento baseados em GUI
* **Registro de Endpoints** - fluxos de gerenciamento de endpoints via GUI
* **Fluxos de Certificados** - status do certificado do servidor, renovação e fluxos de certificado da estação base
* **Visualizador de Mensagens** - visualizações de tráfego para diferentes tipos de mensagens
#### Recursos da Plataforma
* **Implantação com Docker Compose** - `postgres`, `redis`, `mosquitto`, `certgen`, `kc-identity`, `kilocenter`, `kc-gateway`, e `kc-web`
* **Migrações de Banco de Dados** - alterações de esquema controladas por versão
* **Registro Estruturado** - logs configuráveis e endpoints de saúde
* **Desenvolvimento Multiplataforma** - Linux, macOS e Windows via WSL
### Arquitetura
KiloCenter usa uma disposição modular de serviços:
```
+-----------------+ +-----------------+
| Navegador | --> | KC-Web | (:80 nginx / :5173 dev)
+-----------------+ +--------+--------+
|
| gRPC-web
v
+-----------------+ +-----------------+ +-----------------+
| Externo | --> | KC-Gateway | -------> | KC-Identity |
| Aplicações | gRPC| (:9090 externo | público | (:50052 interno|
| / Integradores | / | gRPC + | RPCs | :8088 health) |
| |gRPC-| gRPC-web, | +--------+--------+
| | web | :8087 health) | ^
+-----------------+ +--------+--------+ |
| | RPCs internos de identidade
| gRPC interno confiável |
v |
+-----------------+ +-----------------+ |
| Estação Base | --> | KC-Core | ------------------+
| (MIOTY BS) |BSSCI| (:50051 interno| org / membresia /
| (:5000 TLS) | | :5000 BSSCI | resolução admin
+-----------------+ | :5001 SCACI |
| :8086 health) | -------> +-----------------+
+-----------------+ +--------+--------+ SQL | PostgreSQL |
| Centro de | ------------>| | via KC-DB |
| Aplicações | TLS SCACI | | (:5433 mapa host)|
| (:5001 TLS) | | +-----------------+
+-----------------+ |
+-----------------> +-----------------+
| | Redis |
| | (:6379) |
| +-----------------+
|
+-----------------> +-----------------+
| Mosquitto |
| via KC-MQTT |
| (:1883 / :9001) |
+-----------------+
```
Esta é a visão de runtime. `KC-Gateway` é a entrada externa de API para o centro de serviço. Ele expõe gRPC nativo e gRPC-web na porta `9090`, então tanto `KC-Web` quanto aplicações de terceiros integram-se ao KiloCenter pela mesma superfície de API pública. `KC-Core` também usa RPCs internos para `KC-Identity` para fluxos de organização, membresia e resolução de admin. No Docker Compose, um serviço de execução única também roda antes do KC-Core no primeiro início para criar o conjunto compartilhado de CA e certificados do servidor. Os módulos do repositório estão listados abaixo. `certgen` Módulos do Repositório
#### - interface de gestão web servida pelo nginx na porta 80
* **KC-Web** - interface de gestão web servida pelo nginx na porta 80
* **KC-Gateway** - entrada externa gRPC-web e proxy de requisições na porta 9090
* **KC-Identity** - serviço de identidade e organização na porta 50052
* **KC-Core** - BSSCI, SCACI, API gRPC interna e lógica do centro de serviço
* **KC-DB** - migrações PostgreSQL, repositórios e interfaces de armazenamento usadas pelos serviços em runtime
* **KC-MQTT** - pacote de integração MQTT usado pelo KC-Core; não implantado como um contêiner separado na pilha Docker comunitária
* **pkg** - versionamento compartilhado e utilitários Go comuns usados em todos os módulos
### Primeiros Passos
#### Início Rápido (Docker Compose)
Pré-requisitos:
* Docker e Docker Compose v2
* Git
1. Clone o repositório:
```
git clone https://github.com/Kiloiot/KiloServiceCenter.git
cd KiloServiceCenter
```
2. Copie o modelo de ambiente:
```
cp .env.example .env
```
3. Inicie a pilha:
```
docker compose up --build -d
```
Isso inicia `postgres`, `redis`, `mosquitto`, `certgen`, `kc-identity`, `kilocenter`, `kc-gateway`, e `kc-web`.
Os certificados TLS são gerados automaticamente na primeira inicialização. As migrações de banco de dados são executadas na inicialização.
4. Abra a interface web e entre com a conta de administrador padrão:
```
http://localhost/
```
| | |
| ---------- | ----------------------------- |
| **E-mail** | `admin [at] kilocenter.local` |
| **Senha** | `admin123!` |
> Substitua `[at]` por `@` ao iniciar sessão.
> **Aviso:** Altere a senha padrão de administrador ou remova esta conta antes de qualquer implantação em produção ou exposta ao público. As credenciais padrão estão publicadas neste repositório.
> **Importante:** KC-Identity e KC-Gateway precisam compartilhar o mesmo segredo HMAC para que a autenticação JWT funcione. O segredo é configurado em `config/config.identity-docker.yaml` e `config/config.gateway-docker.yaml` em `auth.hmac_secret`. Se esses valores forem diferentes, você verá `invalid_token` erros após o login. Veja o [guia do Docker Compose](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/03-installation-docker-compose.md#authentication-secret-hmac) para detalhes.
Para detalhes específicos do Docker, configuração de hostname TLS personalizado e exportação da CA, veja [Instalação com Docker Compose](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/03-installation-docker-compose.md).
#### Outros Modos de Instalação
* [Instalação em Host Linux](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/04-installation-linux-host.md) - implantação manual em host com `KC-Core/certgen`
* [VM Local e Automação](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/05-installation-local-vm-and-automation.md) - fluxo de trabalho de VM baseado em Docker
* [Primeiros Passos](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/README.md) - arquitetura, pré-requisitos e rota de instalação
#### Exportando o Certificado da CA
Estações base e centros de aplicações SCACI externos precisam do certificado da CA para estabelecer confiança TLS:
```
docker compose cp kilocenter:/app/certificates/ca.crt ./ca.crt
```
#### Parando
```
# Pare os serviços e mantenha os volumes de dados
docker compose down
# Redefinição completa: remove banco de dados, certificados e outros volumes Docker
docker compose down -v
```
### Configuração
Copie `.env.example` para `.env` e ajuste conforme necessário. Chaves comuns do Docker Compose:
```
KILOCENTER_POSTGRESQL_USERNAME=kilocenter
KILOCENTER_POSTGRESQL_PASSWORD=changeme
KILOCENTER_POSTGRESQL_DATABASE=kilocenter
KILOCENTER_LOG_LEVEL=info
# KILOCENTER_TLS_SERVER_NAME=localhost
```
Defina `KILOCENTER_TLS_SERVER_NAME` antes do primeiro `docker compose up` se você precisar de um certificado de servidor para um hostname específico em vez de `localhost`.
### Documentação da API
#### Acesso gRPC
* endpoint externo gRPC / gRPC-web: `http://localhost:9090`
* Saúde do Gateway: `http://localhost:8087/health`
* Saúde do KC-Core: `http://localhost:8086/health`
* Saúde do KC-Identity: `http://localhost:8088/health`
* A reflexão gRPC está habilitada por padrão no KC-Core e no KC-Identity para ferramentas
#### Superfícies de Serviço
* `CoreService` - gerenciamento de dispositivos, operações de protocolo, análises, monitoramento, certificados e RPCs de monitoramento SCACI
* `IdentityService` - autenticação, usuários, organizações e chaves de API
* `KiloCenterService` - superfície de compatibilidade que delega para Core e Identity
No desenvolvimento local a partir do código-fonte, o KC-Web pode apontar seu proxy Vite para um destino de gateway diferente por meio de `INGRESS_GRPC_URL`. Em implantações em contêiner, o KC-Web é servido pelo nginx e faz proxy para o KC-Gateway automaticamente.
### Implantação a partir do Código-fonte e em Host
Docker Compose é o caminho de instalação recomendado para avaliação e para a maioria das implantações.
Se você precisar de um fluxo de trabalho sem contêiner, use os guias dedicados em vez de uma inicialização manual ad hoc:
* [Instalação em Host Linux](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/04-installation-linux-host.md)
* [VM Local e Automação](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/05-installation-local-vm-and-automation.md)
#### Kubernetes
Um chart Helm é fornecido para implantação em Kubernetes. Veja [helm/kilocenter/](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/helm/kilocenter) para o chart completo e a referência de configuração.
```
# Instale o KiloCenter (requer PostgreSQL e Redis externos)
helm install kilocenter helm/kilocenter -f my-values.yaml
```
Consulte o [README do chart Helm](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/helm/kilocenter/README.md) para pré-requisitos, opções de configuração e valores de exemplo.
### Suporte ao Protocolo MIOTY
O KiloCenter implementa a pilha de centro de serviço MIOTY definida pela MIOTY Alliance:
* Consciência da camada física para divisão de telegramas
* Tratamento de mensagens na camada MAC e de rede
* Suporte a endpoints unidirecionais e bidirecionais
* Tratamento de endereços curtos
* Fluxos de anexação e desanexação
* Suporte à criptografia de ponta a ponta
A edição comunitária concentra-se na pilha central do centro de serviço. Capacidades MIOTY opcionais, como subcanais BSSCI, o anexo Variable MAC (VM), extensões ReCon e operação enterprise multi-tenant pertencem à oferta enterprise.
#### Perfis e Comportamentos Suportados
* MIOTY TS-UNB
* Operação de endpoints alimentados por bateria
* Múltiplos padrões de redundância
* Tratamento de recepção em múltiplas estações base
### Implantação em Produção
Este repositório não é o veículo recomendado para implantação em produção. Use o Kilo Cloud ou a Plataforma Kilo IoT on-premise para implantações de produção que exijam suporte comercial, garantias operacionais, cobertura de SLA, multitenância e capacidades MIOTY opcionais, como subcanais BSSCI, Variable MAC (VM) e extensões ReCon. Escolha o Kilo Cloud quando a implantação também precisar de regras visuais, painéis, dados históricos, alarmes e escalonamento, histórico de auditoria ou outros fluxos de trabalho da plataforma sem construir esses sistemas por conta própria em torno da Community Edition.
#### Requisitos do Sistema
* Mínimo: 2 núcleos de CPU, 4 GB de RAM, 20 GB de armazenamento
* Recomendado: 4 núcleos de CPU, 8 GB de RAM, SSD de 100 GB
* SO: Linux (Ubuntu 22.04 LTS recomendado)
#### Considerações de Segurança
* Use sempre certificados TLS em produção
* Altere as credenciais padrão antes da implantação
* Restrinja BSSCI (`5000`) e SCACI (`5001`) a redes confiáveis
* Faça backup do banco de dados regularmente
* Monitore alertas do sistema e a expiração dos certificados
### Documentação
* [Primeiros Passos](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/README.md)
* [Arquitetura e Componentes](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/01-architecture-and-components.md)
* [Instalação com Docker Compose](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/03-installation-docker-compose.md)
* [Instalação em Host Linux](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/04-installation-linux-host.md)
* [Noções Básicas de Configuração](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/02-GettingStarted/06-configuration-basics.md)
* [Documentação da API](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/04-Integrations/02-api.md)
* [Integração MQTT](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/04-Integrations/03-mqtt-first-steps.md)
* [Segurança](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook/05-Security/01-security-and-tenant-isolation-basics.md)
### Licença
KiloCenter Community Edition é licenciado sob a [GNU Affero General Public License v3.0 ou posterior](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/LICENSE).
Se você executar uma versão modificada como um serviço de rede, a AGPL exige que você disponibilize o código-fonte modificado aos usuários. O repositório de código-fonte é [github.com/Kiloiot/KiloServiceCenter](https://github.com/Kiloiot/KiloServiceCenter).
Veja [TRADEMARKS.md](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/TRADEMARKS.md) para a política de marcas registradas.
Copyright 2024-2026 Tim Kravchunovsky e contribuidores.
### Suporte
* **Issues**: [Issues do GitHub](https://github.com/Kiloiot/KiloServiceCenter/issues)
* **Documentação**: [GitBook/](https://github.com/Kiloiot/kilo-service-center/blob/3d0674b296989f1f2337563549e59d6ebd480b65/GitBook)
* **MIOTY Alliance**: [mioty-alliance.com](https://mioty-alliance.com/)
### Agradecimentos
KiloCenter é construído com base em padrões definidos pela MIOTY Alliance e em padrões operacionais comuns para infraestrutura IoT auto-hospedada.
---
# 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/project-overview.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.