> ## Documentation Index > Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt > Use this file to discover all available pages before exploring further. # Worker do Controle de Acesso > Instalação do worker que sincroniza pessoas, credenciais e visitantes com as fechaduras, rodando na rede do cliente # Worker do Controle de Acesso O worker do Controle de Acesso (`ghcr.io/unisec/access-control`) roda na rede do cliente e mantém as fechaduras em dia com o que está cadastrado no Portal: * cadastra e remove pessoas, credenciais e grupos de acesso nas controladoras; * coloca o visitante no início do agendamento e retira no fim, inclusive em controladoras sem agendamento próprio; * reprocessa sozinho o que falhar (com espera crescente) e mostra a fila na aba **Sincronização** do Controle de Acesso. O worker **não** fala direto com os equipamentos. Ele manda os comandos via MQTT para o edge que roda a integração da fechadura (Axis, Hikvision, Control iD, Intelbras...). Por isso a organização também precisa de um edge de integração com essas fechaduras. > [!NOTE] > > Fechaduras em integrações de nuvem (Toptic, Hik-Partner Pro hospedado) continuam sendo sincronizadas pelo Portal e não passam pelo worker. ## Requisitos * Docker com suporte a volumes (ou o binário nativo, ver abaixo). * Acesso de saída ao core (`CORE_BASE_URL`) e ao broker MQTT (`EMQX_HOST`). * Um edge do tipo **Controle de Acesso** criado na organização (um por organização). ## 1. Criar o edge e pegar o token 1. No dashboard, abra **Edges** e clique em **Novo edge**. 2. Escolha **Controle de Acesso** e dê um nome (ex.: `controle-de-acesso`). 3. Copie o token exibido. Ele só aparece uma vez; se perder, use **Rotacionar token** na página do edge. A tela de criação já mostra os comandos de instalação com o token preenchido. ## 2. Subir o worker ```bash Docker theme={null} docker run -d \ --name access-control \ --restart unless-stopped \ --network host \ -e CORE_BASE_URL=https://api.portal.unisec.com.br \ -e EMQX_HOST= \ -e ACCESS_CONTROL_EDGE_TOKEN= \ -v access-control-data:/app/data \ ghcr.io/unisec/access-control:latest ``` ```yaml Docker Compose theme={null} services: access-control: image: ghcr.io/unisec/access-control:latest container_name: access-control restart: unless-stopped network_mode: host environment: CORE_BASE_URL: https://api.portal.unisec.com.br EMQX_HOST: ACCESS_CONTROL_EDGE_TOKEN: # Opcional: Postgres em vez do SQLite local # ACCESS_CONTROL_DATABASE_URL: postgres://user:pass@host:5432/access_control volumes: - ./data:/app/data ``` > [!WARNING] > > O volume em `/app/data` é obrigatório. Ele guarda a réplica local e a fila de sincronização. Sem volume, o worker perde a fila a cada reinício e o histórico do que já foi gravado em cada fechadura. ### Binário nativo Para máquinas sem Docker há binários para Linux e macOS (amd64/arm64), anexados a cada release como `portal-access-control--`. As variáveis são as mesmas; defina `ACCESS_CONTROL_SQLITE_PATH` para um caminho gravável: ```bash theme={null} CORE_BASE_URL=https://api.portal.unisec.com.br \ EMQX_HOST= \ ACCESS_CONTROL_EDGE_TOKEN= \ ACCESS_CONTROL_SQLITE_PATH=/var/lib/portal/access-control.db \ ./portal-access-control-linux-amd64 ``` ## Variáveis de ambiente | Variável | Obrig. | Default | Descrição | | - | :-: | - | - | | `CORE_BASE_URL` | ✓ | — | URL do core do Portal. | | `ACCESS_CONTROL_EDGE_TOKEN` | ✓ | — | Token do edge Controle de Acesso. | | `EMQX_HOST` | ✓ | `localhost` | Broker MQTT. Usuário e senha vêm do core no pareamento. | | `ACCESS_CONTROL_SQLITE_PATH` | — | `/app/data/access-control.db` | Banco local SQLite. | | `ACCESS_CONTROL_DATABASE_URL` | — | — | URL `postgres://` para usar Postgres em vez do SQLite. Use um banco exclusivo do worker. | | `ACCESS_CONTROL_DELTA_INTERVAL_MS` | — | `60000` | Intervalo da sincronização incremental com o core (mínimo 1000). | | `LOG_LEVEL` | — | `info` | Nível de log. | ## 3. Conferir Nos logs do container (`docker logs access-control`) devem aparecer, em ordem: 1. `Local database ready` — migrations aplicadas no banco local; 2. `Paired as access control edge` — token aceito pelo core; 3. `Local replica synced` — primeira cópia dos dados da organização; 4. `Connected to MQTT broker` e `Access control worker ready`. No dashboard, o edge aparece **online** em **Edges**, com a contagem da fila. Na aba **Sincronização** do Controle de Acesso dá para acompanhar, reprocessar ou cancelar cada envio. No primeiro boot o worker baixa todos os cadastros e agendamentos da organização e já envia o que estiver faltando nas fechaduras; não há script de migração a rodar. ## Problemas comuns | Sintoma | Causa provável | | - | - | | `CORE_BASE_URL é obrigatório.` / `ACCESS_CONTROL_EDGE_TOKEN é obrigatório.` | Variável ausente no container. | | `Access control worker failed to start` logo após iniciar, com erro 401/403 | Token inválido ou rotacionado. Gere outro em **Rotacionar token** na página do edge. | | `Core request failed; retrying` repetido | Core inacessível a partir da rede do cliente; o worker tenta de novo sozinho. | | `Access control module disabled for this org; idle` | O módulo Controle de Acesso está desligado na organização; o worker espera até ser ligado. | | `Read-only file system ... /app/data` | Volume não montado ou sem permissão de escrita (o processo roda como usuário `portal`). | | Envios ficam em "aguardando" | O edge da integração da fechadura está offline. Veja o status dele em **Edges**. | | Credencial não aparece numa fechadura | O tipo não é aceito por ela (ex.: digital no Axis); a aba Credenciais omite essas fechaduras. | ## Atualizar ```bash theme={null} docker pull ghcr.io/unisec/access-control:latest docker rm -f access-control # rode de novo o docker run acima (o volume preserva a fila) ``` As migrations do banco local rodam sozinhas no boot. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.