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
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
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 necessários
Restrições de runtime e compilação
Arquitetura compatível: x86_64
Sistema operacional alvo 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 da Facephi
Características:
Nenhum estado de sessão é armazenado 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 escalabilidade horizontal por trás de um balanceador de carga
Disponibilidade de endpoints por função
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:
wsqbmppngjpgjp2
Modelo de configuração
Ordem de precedência
Da maior para a menor prioridade:
Variáveis de ambiente
config.jsonValores padrão do serviço
Grupos de configuração em tempo de execução
Configurações do gerenciador REST: porta de escuta, threads, tempo limite, 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, tempo limite de conexão/requisição, tentativas, 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ó masterContadores 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 exige reiniciar o serviço.
Contadores de uso
GET /api/v1/finger/metricsexpõe os contadores de uso das operaçõesextracteauthenticateconcluídas com sucesso.Os campos da resposta são:
usageCountersEnabled,extractCount,authenticateCount,totalCount.Os atributos de medição de licença usados pelo serviço são
FingerExtractCountereFingerAuthenticateCounter.totalCounté calculado comoextractCount + authenticateCount.
Considerações de desempenho
Desempenho (throughput)
Escala de acordo com a capacidade do engine e o tamanho do pool de conexões
Latência
Afetada pelo tempo limite 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 exigir 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, assegure 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 gateway de API.
Restrinja o acesso de entrada a redes confiáveis.
Use terminação TLS na gateway de API 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_secretem um cofre de segredos ou injetado como variável de ambiente em vez de incluí-lo diretamente nas imagens.Quando JWT estiver habilitado, utilize tokens HS256 com um claim
expvá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/healthGET /api/v1/finger/versionGET /api/v1/finger/metrics
Configure os logs com:
logger_levellogger_pathlogger_rotationlogger_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 internos dos campos não são expostos nas respostas públicas.
Os payloads dos endpoints de gerenciamento são estáveis e estão documentados em OpenAPI.
Atualizado