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.

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

No dashboard, abra Edges e clique em Novo edge.
Escolha Controle de Acesso e dê um nome (ex.: controle-de-acesso).
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

docker run -d \
  --name access-control \
  --restart unless-stopped \
  --network host \
  -e CORE_BASE_URL=https://api.portal.unisec.com.br \
  -e EMQX_HOST=<host-do-broker> \
  -e ACCESS_CONTROL_EDGE_TOKEN=<token> \
  -v access-control-data:/app/data \
  ghcr.io/unisec/access-control:latest

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: <host-do-broker>
      ACCESS_CONTROL_EDGE_TOKEN: <token>
      # Opcional: Postgres em vez do SQLite local
      # ACCESS_CONTROL_DATABASE_URL: postgres://user:pass@host:5432/access_control
    volumes:
      - ./data:/app/data

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-<so>-<arch>. As variáveis são as mesmas; defina ACCESS_CONTROL_SQLITE_PATH para um caminho gravável:

CORE_BASE_URL=https://api.portal.unisec.com.br \
EMQX_HOST=<host-do-broker> \
ACCESS_CONTROL_EDGE_TOKEN=<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:

Local database ready — migrations aplicadas no banco local;
Paired as access control edge — token aceito pelo core;
Local replica synced — primeira cópia dos dados da organização;
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

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.

Começando

Painel de Controle

Dispositivos

Automações

Scripts

Assistente IA

Assistentes de Voz

Organização

Planos e Cobrança

Tags

Aplicativo Móvel

Registro de Atividade

Perfil e Segurança

Auto-hospedagem

Manual do Integrador

Legal

Worker do Controle de Acesso

Worker do Controle de Acesso

Requisitos

1. Criar o edge e pegar o token

2. Subir o worker

Binário nativo

Variáveis de ambiente

3. Conferir

Problemas comuns

Atualizar

​Worker do Controle de Acesso

​Requisitos

​1. Criar o edge e pegar o token

​2. Subir o worker

​Binário nativo

​Variáveis de ambiente

​3. Conferir

​Problemas comuns

​Atualizar

Worker do Controle de Acesso

Requisitos

1. Criar o edge e pegar o token

2. Subir o worker

Binário nativo

Variáveis de ambiente

3. Conferir

Problemas comuns

Atualizar