> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/finger/installation/installation_instructions.md). # 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 ```bash 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 ```bash docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.1.0 ``` ### Preparar diretórios ```bash mkdir -p ~/facephi_finger/{license,config,logs} ``` ### Colocar o arquivo de Licença Copie seu arquivo de Licença para: ```bash 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`: ```yaml 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: ```bash docker compose up -d ``` ## Verificar a implantação ```bash # 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: ```json { "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 ` 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: ```bash 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: ```bash 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 ```bash # Baixar a versão de destino docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service: # 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.