> 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

## Pré-requisitos

Antes de instalar o Finger Service, certifique-se de ter:

* Docker instalado e em execução
* Um arquivo de Licença válido da Facephi
* Acesso ao registro Docker da Facephi

## Acesso ao registro Docker

Faça login no registro Docker da Facephi:

```bash
docker login facephicorp.jfrog.io
```

Você precisará das credenciais fornecidas pela Facephi.

## Instalação

{% hint style="danger" %}
**Aviso de alteração incompatível (2.0.0)** A partir da versão 2.0.0, o contrato de payload REST dos endpoints de operações de Impressão Digital mudou e não é compatível com clientes 1.x.x. As rotas legadas `POST /api/v1/finger/create-template` e `POST /api/v1/finger/verify` não estão mais disponíveis. Planeje a migração do cliente antes de atualizar as imagens do serviço.
{% endhint %}

A imagem Docker já inclui os componentes internos de processamento de Impressão Digital, portanto não é necessário montar arquivos adicionais em tempo de execução.

### Baixar a imagem Docker

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.1
```

Substitua `2.2.1` pela Versão desejada.

### Preparar os diretórios

Crie os diretórios para a licença, a configuração e os logs:

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

### Colocar o arquivo de licença

Copie seu arquivo de licença para o diretório de licença:

```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 `docker-compose.yml`:

```yaml
services:
  finger-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.1
    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
```

Os valores de `FACEPHI_FINGER_ENGINE_*` do exemplo são os usados por padrão pela imagem em uma implantação de nó único: você pode omiti-los.

### Iniciar o serviço

```bash
docker compose up -d
```

### Verificar a implantação

```bash
# Check container status
docker ps | grep finger-service

# Check service health
curl http://localhost:6982/api/v1/finger/health

# Check version
curl http://localhost:6982/api/v1/finger/version

# Check operational metrics
curl http://localhost:6982/api/v1/finger/metrics

# View logs
docker logs facephi-finger-service
```

Ao iniciar, o serviço obtém a licença, inicializa os componentes internos de processamento de impressões digitais e aguarda que estejam prontos antes de começar a aceitar solicitações na porta `6982`:

* Em um nó `master`, aguarda 60 segundos e depois verifica até 6 vezes, a cada 10 segundos, se todos os componentes de processamento foram registrados.
* Em um nó `worker`, aguarda 30 segundos e depois verifica até 6 vezes, a cada 10 segundos, se os serviços de processamento locais aceitam conexões.

Enquanto isso, as solicitações à porta não recebem resposta, embora o contêiner apareça como `Up`. Quando o serviço está pronto, o log mostra estas linhas:

```
License initialized successfully from: /app/license/license.lic
Finger service 2.2.1 started (role: master)
```

Se os componentes de processamento de um nó `master` não estiverem prontos após as 6 verificações, o serviço registra `Engine failed to become healthy after 6 attempts` e inicia mesmo assim; nesse caso, `GET /api/v1/finger/health` responde `Unhealthy` com `engine.healthy` igual a `false` até que estejam disponíveis. Se não for possível obter a licença, o serviço não chega a iniciar e o contêiner é interrompido (consulte «Solução de problemas»).

## Implantação em cluster

Para escalar o processamento, o Finger Service oferece suporte a uma topologia multinó com um nó `master` e vários nós `worker`:

* O nó `master` (`FACEPHI_FINGER_ENGINE_ROLE=master`) recebe as solicitações dos clientes: expõe a API completa e distribui o processamento de impressões digitais entre os nós do cluster.
* Os nós `worker` (`FACEPHI_FINGER_ENGINE_ROLE=worker`) fornecem capacidade de processamento e expõem apenas os endpoints de gerenciamento (`health`, `version`, `metrics`, `metrics/prometheus` e `config`). Neles, `POST /api/v1/finger/extract` e `POST /api/v1/finger/authenticate` respondem com HTTP `404`.
* Todos os nós devem apontar para o nó `master` com `FACEPHI_FINGER_ENGINE_MASTER` e poder se comunicar entre si pelas portas TCP `47500`-`47509`, que são usadas para se descobrir e formar o cluster.
* Todos os nós precisam ter acesso a um arquivo de licença válido.

### Variáveis de topologia

Essas variáveis são configuradas apenas por meio de variáveis de ambiente; não fazem parte de `config.json` nem são expostas por meio de `GET|POST /api/v1/finger/config`:

| Variável                         | Padrão                     | Descrição                                                                                                                                             |
| -------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FACEPHI_FINGER_ENGINE_ROLE`     | `master`                   | Função do nó: `master` ou `worker`. Não diferencia maiúsculas de minúsculas; um valor inválido é interpretado como `master`                           |
| `FACEPHI_FINGER_ENGINE_SERVICES` | `Master,FingerTC,Verifier` | Serviços internos de processamento iniciados pelo nó, separados por vírgulas. Valores aceitos: `Master`, `FingerTC` e `Verifier`                      |
| `FACEPHI_FINGER_ENGINE_MASTER`   | `127.0.0.1`                | Endereço do nó `master` usado pelos nós para formar o cluster. Se for indicada uma lista separada por vírgulas, apenas o primeiro endereço será usado |

Combinações comuns:

| Topologia | Nó       | `FACEPHI_FINGER_ENGINE_ROLE` | `FACEPHI_FINGER_ENGINE_SERVICES` | `FACEPHI_FINGER_ENGINE_MASTER` |
| --------- | -------- | ---------------------------- | -------------------------------- | ------------------------------ |
| Nó único  | Único    | `master`                     | `Master,FingerTC,Verifier`       | `127.0.0.1`                    |
| Cluster   | `master` | `master`                     | `Master`                         | Endereço do nó `master`        |
| Cluster   | `worker` | `worker`                     | `FingerTC,Verifier`              | Endereço do nó `master`        |

### Exemplo com Docker Compose

```yaml
services:
  master:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.1
    container_name: finger-master
    ports:
      - "6982:6982"
      - "47500-47509:47500-47509"
    volumes:
      - ~/facephi_finger/license:/app/license
      - ~/facephi_finger/config:/app/config
      - ~/facephi_finger/logs/master:/app/logs
    environment:
      - FACEPHI_FINGER_ENGINE_ROLE=master
      - FACEPHI_FINGER_ENGINE_SERVICES=Master
      - FACEPHI_FINGER_ENGINE_MASTER=master
    networks:
      - finger-cluster

  finger-worker:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.1
    volumes:
      - ~/facephi_finger/license:/app/license
      - ~/facephi_finger/config:/app/config
    environment:
      - FACEPHI_FINGER_ENGINE_ROLE=worker
      - FACEPHI_FINGER_ENGINE_SERVICES=FingerTC,Verifier
      - FACEPHI_FINGER_ENGINE_MASTER=master
    networks:
      - finger-cluster
    depends_on:
      - master
    deploy:
      replicas: 2

networks:
  finger-cluster:
    driver: bridge
```

Para alterar o número de nós `worker`:

```bash
docker compose up -d --scale finger-worker=3
```

Em cada nó, `GET /api/v1/finger/health` e `GET /api/v1/finger/metrics` informam a função (`engine.role`, `service.role`) e os serviços de processamento configurados (`engine.servicesConfigured`). Nos nós `worker`, a verificação de integridade confirma que cada serviço de processamento local aceita conexões.

## Configuração da licença

O arquivo de licença deve estar localizado em `/app/license/license.lic` dentro do contêiner.

### Formato do arquivo de licença

```ini
LICENSE_TYPE=         # MACHINE, SHARED, or LOCAL
LICENSE_BEHAVIOUR=    # ONLINE or OFFLINE
LICENSE_KEY=          # Your license key
```

Se `LICENSE_TYPE`estiver ausente, o serviço usa `SHARED`, e se estiver ausente `LICENSE_BEHAVIOUR`, usa `ONLINE`. A combinação `SHARED` + `OFFLINE` não é compatível: com ela, o serviço não inicia.

**Campos opcionais:**

* `LICENSE_URLS=` — URLs dos servidores de licença separadas por vírgulas (obrigatório para o tipo `LOCAL`; consulte [Licenciamento offline com servidor local](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/finger/installation/offline_licensing.md))
* `LICENSE_OFFLINE_CODE=` — Conteúdo do arquivo de resposta de ativação offline fornecido pela Facephi (obrigatório para `MACHINE` + `OFFLINE`)
* `LICENSE_ADDRS=` — Endereços MAC, separados por vírgulas, usados para calcular a impressão digital do equipamento nas licenças `MACHINE`

`LICENSE_ID` e `LICENSE_DATA`, se estiverem presentes, são ignorados pelo serviço, que registra um aviso no log. As credenciais do produto Finger Service são incorporadas no momento da compilação; por isso, esses campos devem ser omitidos dos modelos de implantação.

### Conectividade da licença

* Com as licenças `ONLINE`, o servidor deve ter acesso HTTPS de saída aos servidores de licença atribuídos à implantação. Se o tráfego de saída for restrito, solicite à Facephi a lista de permissões exata para sua implantação antes da instalação.
* Para instalações sem acesso à Internet, use um servidor local de licenças (consulte [Licenciamento offline com servidor local](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/finger/installation/offline_licensing.md)).

## Visão geral da API pública

{% hint style="danger" %}
**Nota de compatibilidade** As rotas a seguir correspondem ao contrato público 2.x. Os clientes desenvolvidos para 1.x.x devem ser migrados antes de poder chamar esta versão corretamente.
{% endhint %}

Endpoints expostos pelo serviço:

* `POST /api/v1/finger/extract` (somente em nós `master`)
* `POST /api/v1/finger/authenticate` (somente em nós `master`)
* `GET /api/v1/finger/version`
* `GET /api/v1/finger/health`
* `GET /api/v1/finger/metrics`
* `GET /api/v1/finger/metrics/prometheus`
* `GET|POST /api/v1/finger/config`

## Autenticação JWT

A autenticação JWT é opcional e vem desabilitada por padrão.

* Configure-a na inicialização em `/app/config/config.json` com `auth_enabled`, `auth_jwt_secret`, `auth_accept_authorization_header`, `auth_accept_api_key_header` e `auth_api_key_header_name`
* Substitua esses valores pelas variáveis de ambiente `FACEPHI_FINGER_REST_AUTH_*`
* Com a autenticação habilitada, todos os endpoints, exceto `/health`, `/version`, `/metrics`, `/metrics/prometheus` e as requisições `OPTIONS` exigem um JWT assinado com HS256 usando `auth_jwt_secret` e com a claim `exp`
* Sempre defina `auth_jwt_secret` ao habilitar a autenticação: se estiver vazio, todos os endpoints protegidos respondem com HTTP `401` com `Authentication secret is not configured`
* `GET /api/v1/finger/config` nunca retorna as chaves de autenticação JWT
* `POST /api/v1/finger/config` rejeita as chaves de autenticação JWT; gerencie-as apenas na inicialização e reinicie o serviço para alterá-las

Os detalhes sobre como enviar o token e sobre as respostas `401` estão na seção «Autenticação JWT» da [visão geral do serviço](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/finger.md).

Exemplo de configuração de inicialização:

```json
{
  "auth_enabled": true,
  "auth_jwt_secret": "replace-with-secret",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key"
}
```

Exemplo de variáveis de ambiente:

```bash
export FACEPHI_FINGER_REST_AUTH_ENABLED=true
export FACEPHI_FINGER_REST_AUTH_JWT_SECRET=replace-with-secret
export FACEPHI_FINGER_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
export FACEPHI_FINGER_REST_AUTH_ACCEPT_API_KEY_HEADER=true
export FACEPHI_FINGER_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
```

## Configuração do serviço

Crie `/app/config/config.json` para personalizar o comportamento do serviço. O arquivo é opcional: se não existir, o serviço será iniciado com os valores padrão. Os parâmetros que você não incluir manterão seus valores padrão.

### Localização do arquivo de configuração

* **Localização padrão:** `/app/config/config.json` (dentro do contêiner)
* **Montar um arquivo externo:** Use o mapeamento de volumes no docker-compose

### Exemplo de configuração completa (valores padrão atuais)

```json
{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "",
  "logger_file_prefix": "app",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "metrics_enabled": true,
  "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",
  "metrics_saturation_queue_p95_ms": 250,
  "metrics_saturation_min_inflight_ratio": 1.0,
  "metrics_error_rate_warning": 0.05,
  "metrics_idle_rps_threshold": 0.01,
  "metrics_quality_alert_window_seconds": 900
}
```

### Parâmetros do serviço

| Parâmetro                          | Tipo    | Padrão      | Descrição                                                                                                                                                                              |
| ---------------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`                             | inteiro | 6982        | Porta de escuta do serviço                                                                                                                                                             |
| `number_of_threads`                | inteiro | 1           | Threads de trabalho para o processamento de solicitações                                                                                                                               |
| `connection_timeout`               | inteiro | 60          | Tempo máximo, em segundos, que uma conexão inativa permanece aberta                                                                                                                    |
| `keep_alive_request_number`        | inteiro | 0           | Número máximo de solicitações por conexão keep-alive (0 = sem limite)                                                                                                                  |
| `client_max_body_size`             | inteiro | 100         | Tamanho máximo do corpo da solicitação em MB. Solicitações maiores recebem HTTP `413`                                                                                                  |
| `logger_path`                      | string  | ""          | Diretório onde os arquivos de log são gravados. Vazio desativa o log em arquivo; os logs continuam sendo enviados pela saída padrão do contêiner                                       |
| `logger_file_prefix`               | string  | "app"       | Prefixo da pasta diária de logs dentro de `logger_path` (`<prefijo>-<AAAA-MM-DD>`, com a data em UTC). Os caracteres que não sejam letras, números, `-` e `_` são substituídos por `_` |
| `logger_level`                     | string  | "info"      | Nível de log: `trace`, `debug`, `info`, `warning`, `error`, `critical` ou `off`. Um valor não reconhecido é interpretado como `off`                                                    |
| `logger_rotation`                  | string  | "daily"     | Rotação dos arquivos de log: `daily` ou `hourly`. Qualquer outro valor é interpretado como `daily`                                                                                     |
| `logger_max_files`                 | inteiro | 7           | Número máximo de arquivos de log a serem mantidos (0 = sem limite)                                                                                                                     |
| `metrics_enabled`                  | boolean | true        | Coleta os contadores de tráfego, saturação e latência publicados por `GET /api/v1/finger/metrics` e `GET /api/v1/finger/metrics/prometheus`. Com `false`, esses blocos ficam zerados   |
| `auth_enabled`                     | boolean | false       | Exige autenticação JWT para os endpoints protegidos                                                                                                                                    |
| `auth_jwt_secret`                  | string  | ""          | Segredo compartilhado HS256 usado para validar os JWTs                                                                                                                                 |
| `auth_accept_authorization_header` | boolean | true        | Aceita `Authorization: Bearer <jwt>`                                                                                                                                                   |
| `auth_accept_api_key_header`       | boolean | true        | Aceita JWT no cabeçalho de API Key configurado                                                                                                                                         |
| `auth_api_key_header_name`         | string  | "x-api-key" | Nome do cabeçalho usado quando a extração de Token por API Key está habilitada                                                                                                         |

### Parâmetros de processamento

Configuram a comunicação do serviço com seus componentes internos de processamento de Impressão Digital. São usados apenas nos nós `master`.

| Parâmetro                   | Tipo    | Padrão                  | Descrição                                                                                                                                      |
| --------------------------- | ------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine_connection_timeout` | inteiro | 10000                   | Timeout de conexão (ms)                                                                                                                        |
| `engine_request_timeout`    | inteiro | 60000                   | Timeout da solicitação (ms)                                                                                                                    |
| `engine_max_retries`        | inteiro | 3                       | Número máximo de novas tentativas para uma solicitação que não recebe resposta (erro de conexão ou timeout) ou recebe um `5xx`, `408` ou `429` |
| `engine_retry_delay`        | inteiro | 1000                    | Atraso inicial entre novas tentativas (ms); o valor é dobrado a cada nova tentativa                                                            |
| `engine_verify_ssl`         | boolean | false                   | Verifica os certificados SSL da comunicação com os componentes de processamento                                                                |
| `engine_verbose`            | boolean | false                   | Habilita o registro HTTP detalhado da comunicação com os componentes de processamento                                                          |
| `engine_pool_size`          | inteiro | 4                       | Tamanho do pool de conexões                                                                                                                    |
| `engine_url`                | string  | `http://localhost:8080` | URL base dos componentes internos de processamento                                                                                             |

### Limiares das métricas operacionais

Estes parâmetros alteram apenas a forma como `GET /api/v1/finger/metrics` classifica o estado do serviço (`state.classification`) e quais alertas publica; eles não alteram o processamento das impressões digitais.

| Parâmetro                               | Tipo    | Padrão | Descrição                                                                                                                                            |
| --------------------------------------- | ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metrics_saturation_queue_p95_ms`       | inteiro | 250    | Percentil 95 da latência da fila (1 minuto, ms) a partir do qual a fila é considerada saturada                                                       |
| `metrics_saturation_min_inflight_ratio` | número  | 1.0    | Fração de `number_of_threads` que as solicitações em andamento devem exceder para que o serviço seja considerado saturado                            |
| `metrics_error_rate_warning`            | número  | 0.05   | Taxa de erro de 5 minutos (respostas `4xx` e `5xx`) a partir da qual o serviço é classificado como `degraded` e o alerta é ativado `HIGH_ERROR_RATE` |
| `metrics_idle_rps_threshold`            | número  | 0.01   | Solicitações por segundo durante 15 minutos abaixo das quais o serviço é classificado como `idle`                                                    |
| `metrics_quality_alert_window_seconds`  | inteiro | 900    | Intervalo, em segundos, durante o qual uma extração de baixa qualidade mantém o alerta ativo `LOW_QUALITY`. Com `0`, o alerta é desativado           |

Um valor que não possa ser interpretado ou que seja negativo é descartado com um aviso no log: se vier de uma variável de ambiente, usa-se o valor de `config.json`; se esse valor também for inválido, usa-se o valor padrão.

### Variáveis de ambiente

As variáveis de ambiente têm prioridade sobre `config.json`:

* Os parâmetros do serviço, os de autenticação JWT e os limites `metrics_*` são substituídos por `FACEPHI_FINGER_REST_<PARÁMETRO EN MAYÚSCULAS>`, por exemplo `FACEPHI_FINGER_REST_NUMBER_OF_THREADS` ou `FACEPHI_FINGER_REST_METRICS_ERROR_RATE_WARNING`.
* Os parâmetros de processamento são substituídos por estas variáveis:

| Parâmetro                   | Variável de ambiente                 |
| --------------------------- | ------------------------------------ |
| `engine_url`                | `FACEPHI_FINGER_ENGINE_URL`          |
| `engine_connection_timeout` | `FACEPHI_FINGER_ENGINE_CONN_TIMEOUT` |
| `engine_request_timeout`    | `FACEPHI_FINGER_ENGINE_REQ_TIMEOUT`  |
| `engine_max_retries`        | `FACEPHI_FINGER_ENGINE_MAX_RETRIES`  |
| `engine_retry_delay`        | `FACEPHI_FINGER_ENGINE_RETRY_DELAY`  |
| `engine_verify_ssl`         | `FACEPHI_FINGER_ENGINE_VERIFY_SSL`   |
| `engine_verbose`            | `FACEPHI_FINGER_ENGINE_VERBOSE`      |
| `engine_pool_size`          | `FACEPHI_FINGER_ENGINE_POOL_SIZE`    |

* A topologia do cluster é configurada com `FACEPHI_FINGER_ENGINE_ROLE`, `FACEPHI_FINGER_ENGINE_SERVICES` e `FACEPHI_FINGER_ENGINE_MASTER` (consulte “Variáveis de topologia”).

As variáveis booleanas de processamento aceitam `true`, `TRUE`, `yes`, `YES` ou `1`, e `false`, `FALSE`, `no`, `NO` ou `0`. Um valor inválido em uma variável `FACEPHI_FINGER_ENGINE_*` é ignorado, com um aviso no log, e o valor de `config.json` ou o valor padrão é mantido.

`GET /api/v1/finger/config` não reflete os valores definidos por meio de variáveis de ambiente: mostra os de `config.json` e os valores padrão.

### Atualizações dinâmicas da configuração

Alguns parâmetros podem ser atualizados sem reiniciar o serviço:

```bash
# Update configuration
curl -X POST http://localhost:6982/api/v1/finger/config \
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"engine_request_timeout\":45000,\"metrics_error_rate_warning\":0.1}"}'

# Verificar a configuração atual
curl http://localhost:6982/api/v1/finger/config
```

`POST /api/v1/finger/config` espera um objeto JSON com o campo `config_json_string`, que contém os parâmetros que se deseja modificar serializados como uma string JSON; os parâmetros que não forem incluídos mantêm seus valores.

* São aplicados somente em tempo de execução `engine_url`, `engine_connection_timeout`, `engine_request_timeout`, `engine_max_retries`, `engine_retry_delay`, `engine_verify_ssl` e `engine_verbose` (somente nos nós `master`), e os limites `metrics_*` com os quais `GET /api/v1/finger/metrics` classifica o estado do serviço.
* Os demais parâmetros, incluindo `engine_pool_size`, são somente para leitura: o endpoint os aceita, mas eles não alteram o comportamento do serviço até serem atualizados em `config.json` ou nas variáveis de ambiente e o serviço ser reiniciado. A referência da operação `POST /api/v1/finger/config` inclui a tabela completa de parâmetros.
* Se a variável de ambiente equivalente estiver definida (`FACEPHI_FINGER_ENGINE_*` ou `FACEPHI_FINGER_REST_METRICS_*`), seu valor prevalece sobre o enviado ao endpoint.
* `GET /api/v1/finger/config` retorna todos os valores como strings (por exemplo, `"metrics_error_rate_warning": "0.1"`).
* Se `config_json_string` não contiver um objeto JSON válido, a solicitação retornará HTTP `500` com `exception` igual a `Failed to load configuration from config_json_string` e a configuração não será alterada.
* A configuração de autenticação JWT é definida na inicialização: o endpoint rejeita com HTTP `400` as solicitações que a incluem, com `message` igual a `JWT auth settings are not accessible from the config endpoint`. Atualize `config.json` ou as variáveis de ambiente e reinicie o serviço.

**Observação:** As atualizações em tempo de execução são feitas na memória e não são persistidas automaticamente em `config.json`. Para manter as alterações após uma reinicialização, atualize o arquivo montado em `/app/config/config.json`.

## Contadores de uso

`GET /api/v1/finger/metrics` informa, no bloco `usage` (e nos campos `usageCountersEnabled`, `extractCount`, `authenticateCount` e `totalCount`), os contadores de uso da licença para as operações `POST /api/v1/finger/extract` e `POST /api/v1/finger/authenticate` concluídas com sucesso.

* Os contadores dependem da licença. Se a sua licença não tiver os contadores habilitados, `usage.enabled` será `false` e os contadores serão `0`: consulte a Facephi se precisar habilitá-los.
* São contadas apenas as operações concluídas com sucesso (HTTP `200`). Solicitações inválidas e erros de processamento não são contabilizados.
* Os valores são acumulados pela licença e incluem os incrementos desta instância que ainda não foram sincronizados com o servidor de licenças; por isso, não são reiniciados quando o serviço é reiniciado.
* `usage.total` (e `totalCount`) é sempre a soma das duas operações.

## Solução de problemas

### O serviço não inicia

**Verifique o arquivo de licença:**

```bash
docker exec facephi-finger-service ls -la /app/license/
```

**Verifique os logs:**

```bash
docker logs facephi-finger-service
```

Se não for possível obter a licença durante a inicialização, o serviço é encerrado e o contêiner para. O log informa o motivo com linhas como estas:

| Linha do log                                                                    | Causa                                                                                         |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `Failed to open license file: /app/license/license.lic`                         | O arquivo de licença não está na pasta montada ou não pode ser lido                           |
| `SHARED licenses with OFFLINE behaviour are not supported`                      | `license.lic` combina `LICENSE_TYPE=SHARED` com `LICENSE_BEHAVIOUR=OFFLINE`                   |
| `License validation failed [License initialization]: <motivo> (code: <código>)` | A licença é inválida ou não foi possível validá-la (consulte “Falha na validação da licença”) |

### O serviço não responde logo após a inicialização

O serviço aguarda até que os componentes internos de processamento estejam prontos antes de abrir a porta `6982`: pelo menos 60 segundos em um nó `master` e 30 segundos em um nó `worker`. Aguarde até ver `Finger service 2.2.1 started` no log antes de enviar solicitações ou considerar uma sonda de inicialização como falha.

### `GET /api/v1/finger/health` responde `Unhealthy`

Verifique os campos da resposta:

* `license.valid` igual a `false`: a licença é inválida; `license.statusMessage` indica o motivo (consulte “Falha na validação da licença”).
* `license.valid` igual a `true` e `engine.healthy` igual a `false`: os componentes internos de processamento não estão prontos. Isso costuma ocorrer enquanto ainda estão sendo inicializados, com `engine.lastError` igual a `Engine nodes not yet fully registered`; consulte novamente após alguns segundos. Se o problema persistir:
  * Verifique se há `Engine failed to become healthy after 6 attempts`.
  * Verifique os recursos disponíveis do contêiner com `docker stats facephi-finger-service`.
  * Em um cluster, verifique os valores de `FACEPHI_FINGER_ENGINE_ROLE`, `FACEPHI_FINGER_ENGINE_SERVICES` e `FACEPHI_FINGER_ENGINE_MASTER` de cada nó e se os nós podem ser acessados pelas portas `47500`-`47509`.
  * Enquanto os componentes de processamento não respondem, `POST /api/v1/finger/extract` e `POST /api/v1/finger/authenticate` retornam HTTP `400` com `message` igual a `Fingerprint processing communication error: <detalle>`.

### Os endpoints de Impressão Digital respondem `404`

`POST /api/v1/finger/extract` e `POST /api/v1/finger/authenticate` só existem nos nós `master`. Verifique se `FACEPHI_FINGER_ENGINE_ROLE` está definido como `master` (ou não está definido) no nó que recebe as solicitações, e se o cliente não usa as rotas legadas da versão 1.x.x (`/create-template`, `/verify`).

### Falha na validação da licença

* Verifique as permissões do arquivo de licença: `chmod 644 license.lic`
* Certifique-se de que o firewall permite tráfego HTTPS de saída para os servidores de licença
* Verifique a data de vencimento da licença
* Confirme se a licença corresponde ao produto Finger Service

Se a licença deixar de ser válida com o serviço já em execução, `GET /api/v1/finger/health` responde `Unhealthy` com `license.valid` igual a `false`, `GET /api/v1/finger/version` adiciona `Invalid license: <motivo> (code: <código>)` à mensagem, e `GET /api/v1/finger/metrics` classifica o serviço como `unhealthy` com o alerta `LICENSE_EXPIRED`.

### Os contadores de uso não mudam

* Confirme se `GET /api/v1/finger/metrics` retorna `usage.enabled: true`. Se retornar `false`, sua licença não tem os contadores de uso habilitados: consulte a Facephi.
* Lembre-se de que somente as operações concluídas com sucesso são contabilizadas.

### Problemas de desempenho

* Aumente `engine_pool_size` para processar mais solicitações simultâneas
* Ajuste `number_of_threads` conforme aos núcleos de CPU disponíveis
* Adicione nós `worker` ao cluster para distribuir o processamento
* Monitore o uso de recursos: `docker stats facephi-finger-service`
* Verifique `state.classification`, `saturation` e `latency` em `GET /api/v1/finger/metrics`

## Atualização

Para atualizar para uma nova versão:

{% hint style="warning" %}
**Importante** A atualização da versão 1.x.x para a 2.x é uma migração de API com alterações incompatíveis, não uma substituição direta. Valide todas as chamadas do cliente em relação ao contrato público da versão 2.x antes de promover a implantação.
{% endhint %}

```bash
# Pull new version
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:<new_version>

# Update docker-compose.yml with new version
# Stop current service
docker compose down

# Start new version
docker compose up -d

# Verify upgrade
curl http://localhost:6982/api/v1/finger/version
```

**Sempre consulte as notas da versão antes de atualizar.**
