Especificações técnicas

Aviso de compatibilidade

IMPORTANTE - ALTERAÇÃO INCOMPATÍVEL (BREAKING CHANGE) (2.0.0)

O contrato de payload REST para as operações de Impressão Digital mudou na versão 2.0.0 e não é compatível com os payloads de cliente 1.x.x.

Requisitos mínimos

Componente	Requisito
SO	Linux x86_64
CPU	4 núcleos
Memória	4 GB de RAM
Disco	2 GB de espaço livre

Recomendado para produção

Componente	Recomendação
SO	Ubuntu LTS
CPU	8 ou mais núcleos
Memória	8 GB ou mais de RAM
Armazenamento	SSD para logs e camadas do contêiner
Rede	Conectividade de baixa latência com os serviços de processamento de Impressão Digital exigidos

Restrições de runtime e compilação

• Arquitetura compatível: x86_64

• Sistema operacional de destino compatível: Linux

• Runtime base do contêiner: Ubuntu 20.04

Arquitetura do serviço

O serviço atua como uma camada de adaptação de API Rest sem estado:

Aplicação cliente -> Facephi Finger Service -> Processamento de Impressão Digital de Facephi

Características:

• Não é armazenado estado de sessão na camada de API

• As requisições públicas são validadas e normalizadas antes de serem processadas

• As respostas de processamento são traduzidas de volta para o contrato público

• Adequado para escalonamento horizontal atrás de um balanceador de carga

Disponibilidade de endpoints por função

Função	Endpoints
master	extract, authenticate, health, version, metrics, config
worker	health, version, metrics, config

Formatos de imagem suportados (endpoints públicos de Impressão Digital)

Para requisições baseadas em imagem em:

• POST /api/v1/finger/extract (image)

• POST /api/v1/finger/authenticate (image1, image2)

os formatos de imagem de Impressão Digital suportados são:

• WSQ

• bmp

• png

• jpg

• jp2

Modelo de configuração

Ordem de precedência

Do maior para o menor nível de prioridade:

1. Variáveis de ambiente

2. config.json

3. Valores padrão do serviço

Grupos de configuração em tempo de execução

• Configurações do gerenciador REST: porta de escuta, threads, Timeout, tamanho do body, logging

• Configurações de autenticação REST: habilitação de JWT, segredo HS256, cabeçalhos de Token aceitos

• Configurações de processamento: URL, Timeout de conexão/requisição, retries, tamanho do pool, verificação SSL

• Configurações de topologia: função (master/worker), lista de serviços de processamento, endereço de descoberta do nó mestre

• Contadores de uso de Licença: habilitados por meio da chave de metadados de Licença ActivateUsageCounters

As configurações de autenticação JWT são aplicadas durante a inicialização do serviço. Alterá-las requer reiniciar o serviço.

Contadores de uso

• GET /api/v1/finger/metrics expõe os contadores de uso das operações extract e authenticate concluídas com sucesso.

• Os campos da resposta são: usageCountersEnabled, extractCount, authenticateCount, totalCount.

• Os atributos de medição de Licença utilizados pelo serviço são FingerExtractCounter e FingerAuthenticateCounter.

• totalCount é calculado como extractCount + authenticateCount.

Considerações de desempenho

Dimensão	Guia
Desempenho (throughput)	Escala com a capacidade do engine e o tamanho do pool de conexões
Latência	Afetada pelo Timeout de requisição do engine e pelas tentativas
Concorrência	Influenciada por number_of_threads e engine_pool_size
Tamanho do payload	Controlado por client_max_body_size

Notas operacionais

• Durante a inicialização do contêiner, os serviços de processamento podem requerer um tempo de aquecimento.

• As verificações de saúde validam o contexto do serviço, a Licença e a disponibilidade do processamento.

• Em implantações orientadas a cluster, garanta uma configuração de descoberta consistente entre os nós.

Recomendações de segurança

• Implante atrás de um proxy reverso ou de uma API gateway.

• Restrinja o acesso de entrada a redes confiáveis.

• Use terminação TLS na gateway ou no balanceador de carga.

• Proteja os arquivos de Licença e configuração montados com permissões de privilégio mínimo.

• Mantenha auth_jwt_secret em um cofre de segredos ou injetado como variável de ambiente em vez de incluí-lo diretamente nas imagens.

• Quando JWT estiver habilitado, use tokens HS256 com um claim exp válido e proteja todos os endpoints não públicos.

• Habilite a verificação SSL para a comunicação com o backend de processamento quando a infraestrutura permitir.

Os endpoints públicos que permanecem sem autenticação são GET /api/v1/finger/health, GET /api/v1/finger/version e as solicitações de preflight OPTIONS.

Logging e monitoramento

Use estes endpoints para verificações de disponibilidade (Liveness):

• GET /api/v1/finger/health

• GET /api/v1/finger/version

• GET /api/v1/finger/metrics

Configure os logs com:

• logger_level

• logger_path

• logger_rotation

• logger_max_files

Notas de compatibilidade

• Os payloads da API para operações de Impressão Digital utilizam o contrato público 2.0.0.

• Os nomes de campo internos não são expostos nas respostas públicas.

• Os payloads dos endpoints de gestão são estáveis e estão documentados no OpenAPI.