# Implantar cargas de trabalho FlashData

Execute as tarefas CLI do seu aplicativo ou agente em Linux ou Docker, então verifique o acesso e a reutilização do resultado após um reinício.

Referência canônica: https://flashdata.dev/pt/docs/guides/production-deployment
2026-11-05 por FlashData

<a id="prepare"></a>

## 1. Escolha o tempo de execução

Use um host Linux com Bash e jq, e uma chave API proprietária com permissão google_search. Executar configuração como o usuário OS que irá executar a tarefa. Crie esta pasta de tarefas privada para os passos 1–4; as etiquetas de arquivos mostram qualquer subpasta.

### Crie a pasta de tarefas

```bash
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"
```

### Servidor Linux

Instale o CLI nativo primeiro. Executar comando -v flashdata para encontrar seu caminho absoluto, em seguida, definir FLASHDATA_BIN para esse caminho em runtime.sh. Defina o nome do perfil e o caminho do estado persistente uma vez aqui, e então salve o arquivo.

#### runtime.sh

```bash
# runtime.sh — edit the executable and persistent state paths.
export FLASHDATA_BIN=/usr/local/bin/flashdata
export FLASHDATA_PROFILE=research
export FLASHDATA_STATE_DIR="$HOME/.local/state/flashdata-research"

run_flashdata() {
  env -u FLASHDATA_API_KEY "$FLASHDATA_BIN" "$@" \
    --profile "$FLASHDATA_PROFILE" \
    --state-dir "$FLASHDATA_STATE_DIR"
}
```


### Docker

Em um host Linux Docker com curl, tar e sha256sum, baixe o CLI para a CPU do host. Salve image/Dockerfile e image/.dockerignore abaixo, construa a imagem e salve runtime.sh. O ajudante corre como seu UID/GID e monta as pastas de estado e tarefa em cada novo contêiner.

#### Baixe e verifique o Linux CLI

```bash
(
  set -euo pipefail
  case "$(uname -m)" in
    x86_64) arch=amd64 ;;
    aarch64|arm64) arch=arm64 ;;
    *) echo 'Use a Linux amd64 or arm64 host.' >&2; exit 1 ;;
  esac
  mkdir -p image
  cd image
  archive="flashdata_1.2.1_linux_$arch.tar.gz"
  base='https://github.com/flashdatadev/flashdata-cli/releases/download/v1.2.1'
  curl --fail --show-error --location "$base/$archive" -o "$archive"
  curl --fail --show-error --location "$base/SHA256SUMS" -o SHA256SUMS
  awk -v file="$archive" '$2 == file { print }' SHA256SUMS | sha256sum -c -
  tar -xzf "$archive" flashdata
)
```

#### image/Dockerfile

```dockerfile
FROM debian:bookworm-slim
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates \
    && rm -rf /var/lib/apt/lists/*
COPY --chmod=0755 flashdata /usr/local/bin/flashdata
USER 10001:10001
ENTRYPOINT ["/usr/local/bin/flashdata"]
```

#### image/.dockerignore

```text
*
!Dockerfile
!flashdata
```

#### Construa a imagem local, sem credenciais

```bash
docker build --tag flashdata-runtime:1.2.1 ./image
docker run --rm flashdata-runtime:1.2.1 --version
```

#### runtime.sh

```bash
# runtime.sh — use the local image built above.
export FLASHDATA_IMAGE='flashdata-runtime:1.2.1'
export FLASHDATA_PROFILE=research
export FLASHDATA_STATE_DIR="$HOME/.local/state/flashdata-research"

run_flashdata() {
  docker run --rm -i --user "$(id -u):$(id -g)" \
    --env FLASHDATA_API_KEY= \
    --mount "type=bind,src=$FLASHDATA_STATE_DIR,dst=/state" \
    --mount "type=bind,src=$PWD,dst=/work" --workdir /work \
    --entrypoint /usr/local/bin/flashdata "$FLASHDATA_IMAGE" \
    "$@" --profile "$FLASHDATA_PROFILE" --state-dir /state
}
```

- [CLI libera 1.2.1](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.2.1)
- [Docker ligar montagens](https://docs.docker.com/engine/storage/bind-mounts/)

- [Instale o CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)
- [Chave do proprietário e permissões](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md)

<a id="runtime-check"></a>

### Verifique o tempo de execução selecionado

run_flashdata é o ajudante salvo no runtime.sh; todos os comandos posteriores usam seu perfil e diretório de estado. Ele ignora FLASHDATA_API_KEY para que uma chave de ambiente não possa substituir o perfil salvo. Espere as versões CLI e jq.

#### Prepare o estado persistente sem consulta API

```bash
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version
```


<a id="secrets"></a>

## 2. Instale o acesso do proprietário uma vez

Se o perfil já tiver acesso ao proprietário, pule a importação e execute a verificação abaixo. Caso contrário, monte um arquivo secreto legível pelo usuário do serviço e substitua o caminho do exemplo por sua localização. A importação lê através de stdin; Docker não copia para a imagem.

### Aponte para o arquivo secreto implantado

```bash
export FLASHDATA_KEY_FILE='/run/secrets/flashdata_api_key'
```

### Importar e verificar no tempo de execução selecionado

```bash
set -euo pipefail
. ./runtime.sh
: "${FLASHDATA_KEY_FILE:?Set the path to your mounted owner-key secret}"
run_flashdata auth login --api-key-stdin --non-interactive \
  < "$FLASHDATA_KEY_FILE"
run_flashdata auth status --json --non-interactive
```

- [Reclame um teste antes do uso recorrente](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#claim)

<a id="access-check"></a>

### Confirme a conta e permissão

O verificação imprime a conta ID, fontes permitidas e proteção credencial, e depois true. Confirmar a conta ID é o proprietário pretendido antes de continuar access.json permanece na pasta de tarefas para inspeção.

#### Acesso do proprietário salvo. verificação grátis

```bash
set -euo pipefail
umask 077
. ./runtime.sh
run_flashdata auth status --json --non-interactive > access.json
jq '{accountId: .data.identity.identity.accountId,
     sources: .data.identity.permittedSources,
     credentialProtection: .data.credentialProtection}' access.json
jq -e '.ok and .data.accessVerified
  and (.data.identity.identity.recurringAllowed == true)
  and (.data.identity.permittedSources | index("google_search") != null)' access.json
```


<a id="protection"></a>

### Armazenamento de credenciais e arquivos persistentes

Inspecione data.credentialProtection em auth status. Linux pode usar um Serviço Secreto destrancado, um hospedeiro sem cabeça ou o recipiente acima podem usar um arquivo de texto simples. Mantenha o diretório estadual privado e persistente. Providencie o usuário implantado separadamente do perfil criptografado do seu laptop.

| Continue | Localização |
| --- | --- |
| Credenciais e revistas | FLASHDATA_STATE_DIR |
| Entrada, recibos e resultados | A pasta de tarefas, montada como /work em Docker. |

- [Providenciando e movendo o acesso](https://flashdata.dev/pt/docs/guides/agent-access/reference.md)

<a id="operate"></a>

## 3. Validar o pedido e o custo

Salve request.json ao lado de runtime.sh. O seguinte verificação valida o acesso recorrente e o pedido, lê os preços atuais e compara com o saldo disponível. Ele não envia nenhuma busca e não reserva créditos. Continue apenas quando o filtro imprime true.

### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```

### Verifique antes da primeira tarefa paga

```bash
set -euo pipefail
umask 077
. ./runtime.sh
run_flashdata account balance --json --non-interactive > balance.json
run_flashdata query --input request.json --mode realtime --dry-run --recurring \
  --run-id deployment-first-task --json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
  .ok and .data.dryRun and .data.estimateAvailable
  and ($balance[0].ok == true)
  and any(.data.estimate.prices[]?;
    .source == "google_search" and .available == true
    and (.estimatedCredits | type == "number")
    and ($balance[0].data.availableCredits | type == "number")
    and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json
```


<a id="restart-check"></a>

## 4. Execute uma vez e verifique a reutilização

Salve deployment-check.sh abaixo. Com uma nova execução ID, a primeira execução envia uma busca paga; a segunda inicia um novo processo e lê o resultado salvo. Se este ID já estiver completo no mesmo perfil, ambas as tentativas de reutilizá-lo.


<a id="check-script"></a>

### Salve deployment-check.sh

Criar deployment-check.sh ao lado de runtime.sh e request.json na pasta de tarefas privada no host. Copie o script completo abaixo e guarde-o.

#### deployment-check.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./runtime.sh
attempt=$(mktemp -d ./deployment-check.XXXXXX)
printf 'Attempt files: %s\n' "$attempt" >&2
cp -- request.json "$attempt/request.json"
if ! run_flashdata query --input "$attempt/request.json" --mode realtime --recurring \
  --run-id deployment-first-task --timeout 2m --json --non-interactive \
  --output "$attempt/result.json" \
  > "$attempt/receipt.json" 2> "$attempt/error.json"; then
  cat "$attempt/error.json" >&2
  exit 1
fi
jq -e '.ok == true' "$attempt/receipt.json" >/dev/null
jq -e '.source == "google_search" and .status == "done"
  and (.results[0].organic | type == "array")' "$attempt/result.json" >/dev/null
jq '{runId, cached, usage}' "$attempt/receipt.json"
printf 'Saved result: %s\n' "$attempt/result.json"
```


<a id="run-check"></a>

### Faça o verificação salvo duas vezes

Corra da pasta de tarefas do host como o mesmo usuário de serviço. Ambos os processos carregam o runtime.sh salvo no passo 1.

#### Corra, então reinicie o processo

```bash
# A new run ID submits one paid search; a completed ID reuses its result.
bash deployment-check.sh

# New process; Docker uses a new container with the same mounts.
# Same account, input and state: cached: true, no new search.
bash deployment-check.sh
```


<a id="restart-result"></a>

### Verifique o segundo recibo

Para uma nova corrida, espere cached: false, então cached: true. Cada tentativa imprime sua pasta deployment-check.XXXXXX e salva request.json, receipt.json e error.json, além de result.json no sucesso. O recibo em cache relata o uso original. Uma tentativa fracassada mantém seus arquivos para recuperação.

#### Segundo recibo · Excerto

```json
{
  "ok": true,
  "runId": "deployment-first-task",
  "cached": true
}
```

- [Recupere uma corrida interrompida](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

<a id="read-result"></a>

### Leia o resultado da busca salva

Defina ATTEMPT_DIR para a segunda pasta de sucesso impressa acima, por exemplo, exportar ATTEMPT_DIR='./deployment-check.ABC123'. Esses comandos só lêem arquivos locais.

#### Recibo e links de origem

```bash
# Use one attempt folder printed by deployment-check.sh.
: "${ATTEMPT_DIR:?Set a saved deployment-check.XXXXXX folder}"
jq '{runId, cached, usage}' "$ATTEMPT_DIR/receipt.json"
jq '.results[0].organic[] | {title, link, snippet}' "$ATTEMPT_DIR/result.json"
```


<a id="schedule"></a>

### Passe de uma verificação de implantação para uma tarefa recorrente.

Este verificação tem um ID fixo. Para o trabalho recorrente, dê a cada ocorrência pretendida seu próprio ID e mantenha o tempo de execução selecionado, conta, instantâneos de entrada e montagens de estado. Adapte o comando de busca do corredor recorrente para usar run_flashdata para que as tarefas Docker permaneçam dentro do contêiner.

- [Recorrendo IDs, recibos e agendamento](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)

<a id="ci"></a>

## Verifique o acesso das ações GitHub

Use um corredor Linux confiável e persistente com Bash, jq e o perfil CLI já instalado sob o usuário OS do corredor. Guarde esse fluxo de trabalho no repositório da sua aplicação. Verifica o CLI sem executar uma tarefa paga.

1. Atribua o rótulo de pesquisa de dados para aquele corredor.
2. Defina variáveis de repositório FLASHDATA_BIN e FLASHDATA_STATE_DIR para seus caminhos absolutos, e FLASHDATA_PROFILE para o nome do perfil instalado.

### .github/workflows/flashdata-check.yml

```yaml
name: FlashData access check
on: workflow_dispatch
permissions: {}
concurrency:
  group: flashdata-research
  cancel-in-progress: false
jobs:
  verify:
    runs-on: [self-hosted, linux, flashdata-research]
    timeout-minutes: 5
    steps:
      - name: Verify the installed profile without a paid query
        shell: bash
        env:
          FLASHDATA_BIN: ${{ vars.FLASHDATA_BIN }}
          FLASHDATA_STATE_DIR: ${{ vars.FLASHDATA_STATE_DIR }}
          FLASHDATA_PROFILE: ${{ vars.FLASHDATA_PROFILE }}
          FLASHDATA_API_KEY: ""
        run: |
          set -euo pipefail
          : "${FLASHDATA_BIN:?Set the absolute CLI path}"
          : "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
          : "${FLASHDATA_PROFILE:?Set the installed profile name}"
          test -d "$FLASHDATA_STATE_DIR"
          "$FLASHDATA_BIN" auth status --profile "$FLASHDATA_PROFILE" \
            --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
            jq -e '.ok and .data.accessVerified
              and (.data.identity.identity.recurringAllowed == true)
              and (.data.identity.permittedSources | index("google_search") != null)'
```

- [GitHub rótulos de corredor](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job)

<a id="ci-run"></a>

### Faça a verificação de acesso

Após salvar o fluxo de trabalho no ramo padrão do repositório, abra Ações → verificação o acesso FlashData → Execute o fluxo de trabalho. Espere true e um verificação de sucesso. Falta de acesso ou permissão falha o trabalho sem enviar uma busca.


<a id="ci-state"></a>

### Mantenha o estado de execução em todos os trabalhos

Um corredor efêmero começa sem o diário original. Use o estado de aplicação durável ou um corredor persistente para trabalho recorrente pago. Reinstalar apenas a chave não pode identificar a submissão de um trabalho anterior. Mantenha o diretório estadual e saídas de tarefas privadas, não os carregue como artefatos de IC.


<a id="maintain"></a>

## Rodar ou revogar o acesso implantado

Pause o despacho. Na pasta de tarefas, aponte FLASHDATA_KEY_FILE em uma chave de substituição para a mesma conta e fontes necessárias, e execute os comandos abaixo. Repita a verificação de acesso e deployment-check.sh, espere cached: true. Revogar a velha chave após a verificação e manter o perfil e o diretório do estado.

### Substitua a chave por Stdin

```bash
set -euo pipefail
. ./runtime.sh
: "${FLASHDATA_KEY_FILE:?Point to the mounted replacement key for the same account}"
run_flashdata auth login --replace --api-key-stdin --non-interactive \
  < "$FLASHDATA_KEY_FILE"
run_flashdata auth status --json --non-interactive
```

- [Gerenciar chaves de API](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Connected apps](https://flashdata.dev/app/settings/connections)

<a id="revoke"></a>

### Parar o acesso completamente

Pause o agendador, revogue a chave ou a conexão do agente no console, e repita a verificação de acesso livre. Deve falhar. O logout local sozinho não revoga a credencial do servidor; os arquivos já exportados permanecem no disco.


<a id="help"></a>

## Verificações de implantação que falham

| Sintoma | Consertar |
| --- | --- |
| Comando não encontrado / versão errada do CLI | Verifique o comando -v flashdata e FLASHDATA_BIN em runtime.sh. Para Docker, reconstrua e execute a verificação --version da imagem. |
| Faltando montagem ou permissão negada | Crie as pastas de estado e tarefa no host Docker, propriedade do serviço UID/GID. Mantenha seus caminhos estáveis. |
| replacement_requires_flag | O perfil tem uma chave diferente. Verifique o acesso existente primeiro, use o procedimento de rotação para uma substituição pretendida. |
| Não foi possível descodificar o acesso salvo | Corra como o usuário que providenciou, no mesmo ambiente de loja de credenciais. Acesso de provisão em um novo destino em vez de copiar um perfil criptografado de laptop. |
| A verificação de custos devolve falso | Examine balance.json e preflight.json. Antes de enviar a requisição, confirme um preço disponível, a permissão para a fonte e saldo suficiente. |
| run_account_mismatch | Verifique a conta selecionada e as origens do API. Restaure o acesso original, não mude o nome da corrida para evitar a recuperação. |
| run_id_input_conflict | Restaure o pedido original do request.json. Use uma nova corrida ID apenas para uma nova tarefa paga. |
| O informante fica na fila | Verifique se o corredor está online e tem todas as etiquetas. Este fluxo de trabalho requer um persistente corredor Linux. |

- [Recupere uma corrida salva](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)
