Instalação e implantação do serviço

Aviso de compatibilidade

IMPORTANTE - MUDANÇA INCOMPATÍVEL (BREAKING CHANGE) (2.0.0)

A partir da Versão 2.0.0, o contrato de payload REST para os endpoints de operações de Impressão Digital foi alterado e não é compatível com clientes 1.x.x. Planeje a migração do cliente antes de atualizar as imagens do serviço.

As rotas públicas herdadas POST /api/v1/finger/create-template e POST /api/v1/finger/verify já não estão expostas na Versão 2.0.0.

Pré-requisitos

Antes de instalar Facephi Finger Service, certifique-se de que:

• Docker está instalado e em execução

• Você possui um arquivo de Licença Facephi válido

• Você tem acesso ao registro Docker da Facephi

Acesso ao registro Docker

docker login facephicorp.jfrog.io

Use as credenciais fornecidas pela Facephi.

Requisitos de conectividade de Licença

Ativação online

A ativação online está disponível apenas em ambientes conectados.

A imagem de implantação já inclui os componentes de processamento de Impressão Digital necessários por meio do empacotamento Conan, portanto não é necessário montar manualmente arquivos adicionais em tempo de execução.

• O servidor deve ter conectividade com a Internet.

• É necessário acesso HTTPS de saída aos endpoints de Licença atribuídos à implantação.

Configuração do firewall

Se o tráfego de saída estiver restrito, solicite à Facephi a lista de acesso exata para sua implantação antes da instalação.

Instalação

Baixar a imagem Docker

docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.1.0

Preparar diretórios

mkdir -p ~/facephi_finger/{license,config,logs}

Colocar o arquivo de Licença

Copie seu arquivo de Licença para:

cp your-license.lic ~/facephi_finger/license/license.lic
chmod 644 ~/facephi_finger/license/license.lic

O caminho padrão da Licença do serviço é /app/license/license.lic.

Implantação com Docker Compose

Crie um arquivo docker-compose.yml:

services:
  finger-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.1.0
    container_name: facephi-finger-service
    ports:
      - "6982:6982"
    volumes:
      - ~/facephi_finger/license:/app/license
      - ~/facephi_finger/config:/app/config
      - ~/facephi_finger/logs:/app/logs
    environment:
      - FACEPHI_FINGER_ENGINE_ROLE=master
      - FACEPHI_FINGER_ENGINE_SERVICES=Master,FingerTC,Verifier
      - FACEPHI_FINGER_ENGINE_MASTER=127.0.0.1
      # Proteção JWT opcional
      # - FACEPHI_FINGER_REST_AUTH_ENABLED=true
      # - FACEPHI_FINGER_REST_AUTH_JWT_SECRET=shared-secret
      # - FACEPHI_FINGER_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
      # - FACEPHI_FINGER_REST_AUTH_ACCEPT_API_KEY_HEADER=true
      # - FACEPHI_FINGER_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
    restart: unless-stopped

Inicie o serviço:

docker compose up -d

Verificar a implantação

# Verificar o status do contêiner
docker ps | grep finger-service

# Verificar o endpoint de saúde
curl http://localhost:6982/api/v1/finger/health

# Verificar o endpoint de Versão
curl http://localhost:6982/api/v1/finger/version

# Verificar o endpoint de métricas
curl http://localhost:6982/api/v1/finger/metrics

Arquivo de configuração

Caminho padrão do arquivo de configuração dentro do contêiner:

• /app/config/config.json

Exemplo:

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_path": "/app/logs",
  "logger_level": "info",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}

Variáveis de ambiente

Variáveis de tempo de execução do serviço

Prefixo: FACEPHI_FINGER_REST_

Variáveis comuns:

• FACEPHI_FINGER_REST_PORT

• FACEPHI_FINGER_REST_NUMBER_OF_THREADS

• FACEPHI_FINGER_REST_CONNECTION_TIMEOUT

• FACEPHI_FINGER_REST_KEEP_ALIVE_REQUEST_NUMBER

• FACEPHI_FINGER_REST_CLIENT_MAX_BODY_SIZE

• FACEPHI_FINGER_REST_LOGGER_PATH

• FACEPHI_FINGER_REST_LOGGER_LEVEL

• FACEPHI_FINGER_REST_LOGGER_ROTATION

• FACEPHI_FINGER_REST_LOGGER_MAX_FILES

• FACEPHI_FINGER_REST_AUTH_ENABLED

• FACEPHI_FINGER_REST_AUTH_JWT_SECRET

• FACEPHI_FINGER_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER

• FACEPHI_FINGER_REST_AUTH_ACCEPT_API_KEY_HEADER

• FACEPHI_FINGER_REST_AUTH_API_KEY_HEADER_NAME

A autenticação JWT é opcional e está desativada por padrão. Quando está habilitada, o serviço valida tokens HS256 com um claim exp não expirado.

Os endpoints públicos permanecem acessíveis sem autenticação:

• GET /api/v1/finger/health

• GET /api/v1/finger/version

• Solicitações de preflight OPTIONS

Os endpoints protegidos exigem um JWT válido, por exemplo por meio de Authorization: Bearer <jwt> ou do cabeçalho de API Key configurado.

Variáveis de processamento de Impressão Digital

Prefixo: FACEPHI_FINGER_ENGINE_

Variáveis:

• FACEPHI_FINGER_ENGINE_URL

• FACEPHI_FINGER_ENGINE_CONN_TIMEOUT

• FACEPHI_FINGER_ENGINE_REQ_TIMEOUT

• FACEPHI_FINGER_ENGINE_MAX_RETRIES

• FACEPHI_FINGER_ENGINE_RETRY_DELAY

• FACEPHI_FINGER_ENGINE_VERIFY_SSL

• FACEPHI_FINGER_ENGINE_VERBOSE

• FACEPHI_FINGER_ENGINE_POOL_SIZE

• FACEPHI_FINGER_ENGINE_ROLE

• FACEPHI_FINGER_ENGINE_SERVICES

• FACEPHI_FINGER_ENGINE_MASTER

Implantação orientada a cluster

Para uma topologia multinodo:

• Use um nó master (FACEPHI_FINGER_ENGINE_ROLE=master) com exposição da API pública.

• Use nós worker (FACEPHI_FINGER_ENGINE_ROLE=worker) para escalar a carga de processamento.

• Configure todos os nós para apontarem para o mesmo endereço FACEPHI_FINGER_ENGINE_MASTER.

No papel de worker, apenas os endpoints de gerenciamento são expostos.

Os endpoints de gerenciamento incluem health, version, metrics e config.

Contadores de uso

O endpoint GET /api/v1/finger/metrics informa os contadores de uso das operações públicas de Impressão Digital concluídas com sucesso.

Para habilitar os contadores:

• Adicione a chave de metadados ActivateUsageCounters=true na Licença usada pelo serviço.

• Defina os atributos de medição FingerExtractCounter e FingerAuthenticateCounter.

A resposta inclui:

• usageCountersEnabled

• extractCount

• authenticateCount

• totalCount

totalCount é sempre calculado como extractCount + authenticateCount.

Atualizações dinâmicas de configuração

Use o endpoint de configuração para aplicar atualizações em tempo de execução:

curl -X POST http://localhost:6982/api/v1/finger/config \\
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"engine_pool_size\":8,\"engine_request_timeout\":45000}"}'

Observações importantes:

• As atualizações em tempo de execução ficam em memória e não são persistidas automaticamente em config.json.

• Para preservar as alterações após uma reinicialização, atualize o arquivo montado em /app/config/config.json.

• A configuração de autenticação JWT são ajustes de inicialização; atualize config.json ou as variáveis de ambiente e reinicie o serviço.

Solução de problemas

O serviço não inicia

• Valide que /app/license/license.lic existe no contêiner.

• Verifique os logs do contêiner:

docker logs facephi-finger-service

O endpoint de saúde apresenta erros

• Verifique a validade da Licença.

• Verifique a conectividade e o tempo de inicialização dos componentes de processamento de Impressão Digital.

• Verifique os valores configurados de papel e serviços do engine.

Os endpoints de Impressão Digital não estão disponíveis

Se /extract o /authenticate não estiverem disponíveis, confirme o papel:

• FACEPHI_FINGER_ENGINE_ROLE deve ser master.

Validação do endpoint de métricas

Se forem esperados contadores de uso, mas os valores permanecerem sem alterações:

• Confirme que GET /api/v1/finger/metrics retorna usageCountersEnabled: true.

• Confirme que os metadados da Licença incluem ActivateUsageCounters=true.

• Confirme que os nomes de medição da Licença correspondem exatamente: FingerExtractCounter, FingerAuthenticateCounter.

Atualização

# Baixar a versão de destino
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:<new_version>

# Atualizar a etiqueta da imagem no compose
# Reiniciar o serviço
docker compose down
docker compose up -d

Revise sempre as notas de Versão antes de atualizar.