For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 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

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

Da maior para a menor 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, 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ó master

  • 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 exige 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 usados pelo serviço são FingerExtractCounter e FingerAuthenticateCounter.

  • totalCount é calculado como extractCount + authenticateCount.

Considerações de desempenho

Dimensão
Guia

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_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, utilize 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 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