# Carico di lavoro di distribuzione FlashData

Eseguire le attività CLI dell'applicazione o dell'agente su Linux o Docker, quindi verificare l'accesso e il riutilizzo dei risultati dopo un riavvio.

Riferimento canonico: https://flashdata.dev/it/docs/guides/production-deployment
Recensito: 2026-11-05 da FlashData

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

## 1. Scegli il runtime

Utilizzare un host Linux con Bash e jq e una chiave API con autorizzazione google_search. Eseguire la configurazione come utente OS che eseguirà l'attività. Creare questa cartella di attività privata per i passaggi 1–4; le etichette dei file mostrano qualsiasi sottocartelle.

### Creare la cartella di attività

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

### Server Linux

Installare il nativo CLI prima. Eseguire il comando -v flashdata per trovare il suo percorso assoluto, quindi impostare FLASHDATA_BIN su quel percorso in runtime.sh. Impostare il nome del profilo e il percorso di stato persistente una volta qui, quindi salvare il file.

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

Su un host Linux Docker con curl, tar e sha256sum, scarica il pinned CLI per la CPU host. Salvare image/Dockerfile e image/.dockerignore di seguito, costruire l'immagine, quindi salvare runtime.sh. L'aiutante viene eseguito come UID/GID e monta le cartelle di stato e di attività in ogni nuovo contenitore.

#### Scaricare e verificare la 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
```

#### Costruisci l'immagine locale · nessuna credenziali necessaria

```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 rilascio 1.2.1](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.2.1)
- [Supporti di legatura Docker](https://docs.docker.com/engine/storage/bind-mounts/)

- [Installare il nativo CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#install)
- [Chiave del proprietario e autorizzazioni](https://flashdata.dev/it/docs/guides/api-keys-and-permissions/reference.md)

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

### Controllare l'orario di esecuzione selezionato

run_flashdata è l'aiutante salvato in runtime.sh; tutti i comandi successivi utilizzano il suo profilo e la directory di stato. Ignora FLASHDATA_API_KEY in modo che una chiave ambiente non possa sostituire il profilo salvato. Aspettatevi le versioni CLI e jq.

#### Preparare lo stato persistente · no API query

```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. Installare l'accesso del proprietario una volta

Se il profilo ha già accesso proprietario, saltare l'importazione e eseguire il controllo qui sotto. In caso contrario, montare un file segreto chiave proprietario leggibile dall'utente del servizio e sostituire il percorso di esempio con la sua posizione. L'importazione lo legge attraverso stdin; Docker non lo copia nell'immagine.

### Punta al file segreto distribuito

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

### Importa e verifica nel runtime selezionato

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

- [Pretendiamo una prova prima dell'uso ricorrente](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md#claim)

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

### Confermare l'account e il permesso

Il controllo stampa l'account ID, le fonti consentite e la protezione delle credenziali, quindi true. Confermare l'account ID è il proprietario previsto prima di continuare. access.json rimane nella cartella di compito per l'ispezione.

#### Salvataggio dell'accesso del proprietario · controllo gratuito

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

### Archiviazione Credenziale e file persistenti

Ispezionare data.credentialProtection in auth status. Linux può utilizzare un servizio segreto sbloccato; un host senza testa o il contenitore sopra può utilizzare un file di testo semplice proprietario. Tenere la directory statale privata e persistente. Fornire l'utente distribuito separatamente dal profilo crittografato del computer portatile.

| Continua | Località |
| --- | --- |
| Credenziali e diario di esecuzione | FLASHDATA_STATE_DIR |
| Input, ricevute e risultati | La cartella delle attività; montata come /work in Docker. |

- [Fornitura e spostamento dell'accesso](https://flashdata.dev/it/docs/guides/agent-access/reference.md)

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

## 3. Convalida la richiesta e il costo

Salvare request.json accanto a runtime.sh. Il seguente controllo convalida l'accesso ricorrente e la richiesta, legge i prezzi correnti e lo confronta con il saldo disponibile. Non invia ricerca e non riserva crediti. Continuare solo quando il filtro stampa true.

### request.json

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

### Controllare prima del primo compito pagato

```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. Esegui una volta e verifica il riutilizzo

Salva deployment-check.sh qui sotto. Con una nuova esecuzione ID, la prima esecuzione presenta una ricerca a pagamento; la seconda avvia un nuovo processo e legge il risultato salvato. Se questo ID già completato nello stesso profilo, entrambi tenta di riutilizzarlo.


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

### Salvare deployment-check.sh

Creare deployment-check.sh accanto a runtime.sh e request.json nella cartella di attività privata sull'host. Copia lo script completo qui sotto e salvalo.

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

### Eseguire il controllo salvato due volte

Eseguire da quella cartella di attività host come lo stesso utente di servizio. Entrambi i processi caricano lo runtime.sh salvato nella fase 1.

#### Eseguire, quindi riavviare il 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>

### Verificare la seconda ricevuta

Per una nuova esecuzione, aspettatevi cache: false, quindi cache: true. Ogni tentativo stampa la sua cartella deployment-check.XXXXXX e salva request.json, receipt.json e error.json, più result.json sul successo. La ricevuta della cache riporta l'utilizzo originale. Un tentativo fallito mantiene i suoi file per il recupero.

#### Seconda ricevuta · estrattore

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

- [Recuperare una corsa interrotta](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)

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

### Leggi il risultato di ricerca salvato

Impostare ATTEMPT_DIR alla seconda cartella di successo stampata sopra, ad esempio esportare ATTEMPT_DIR='./deployment-check.ABC123'. Questi comandi leggono solo i file locali.

#### Collegamenti di ricezione e di origine

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

### Spostarsi da un controllo di distribuzione a un'attività ricorrente

Questo assegno ha un funzionamento fisso ID. Per il lavoro ricorrente, dare ad ogni evento previsto il proprio ID e mantenere il tempo di esecuzione selezionato, account, snapshot di input e supporti di stato. Adapt il comando di query del corridore ricorrente per utilizzare run_flashdata in modo che le attività Docker rimangano all'interno del contenitore.

- [Ricorrente IDs, ricevute e pianificazione](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)

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

## Controllare l'accesso da GitHub Azioni

Utilizzare un corridore Linux affidabile e persistente con Bash, jq e il profilo CLI già installato sotto l'utente OS del runner. Salvare questo flusso di lavoro nel repository della tua applicazione. Controlla l'host CLI senza eseguire un'attività pagata.

1. Assegna l'etichetta flashdata-research a quel corridore.
2. Impostare le variabili di repository FLASHDATA_BIN e FLASHDATA_STATE_DIR ai suoi percorsi assoluti e FLASHDATA_PROFILE al nome del profilo installato.

### .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)'
```

- [Etichette runner GitHub](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>

### Eseguire il controllo di accesso

Dopo aver salvato il flusso di lavoro sul ramo predefinito del repository, aprire Azioni → FlashData controllo di accesso → Esegui flusso di lavoro. Aspettatevi true e un controllo di successo. L'accesso mancante o il permesso fallisce il lavoro senza presentare una ricerca.


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

### Mantenere lo stato dell'esecuzione attraverso i lavori

Un corridore effimero inizia senza il diario originale. Utilizzare lo stato di applicazione durevole o un corridore persistente per il lavoro ricorrente retribuito. Reinstallare solo la chiave non può identificare la presentazione di un lavoro precedente. Mantenere la directory di stato e le uscite di attività private; non caricarle come artefatti CI.


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

## Ruotare o revocare l'accesso dispiegato

La polizia di Pause. Nella cartella delle attività, punta FLASHDATA_KEY_FILE in una chiave di sostituzione per lo stesso account e le fonti richieste, quindi eseguire i comandi qui sotto. Ripetere il controllo di accesso e deployment-check.sh; aspettatevi cache: true. Rivolgere la vecchia chiave dopo la verifica e mantenere il profilo e la directory di stato.

### Sostituire la chiave tramite 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
```

- [Gestione delle chiavi API](https://flashdata.dev/it/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Connected apps](https://flashdata.dev/app/settings/connections)

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

### Smettere di accedere completamente

Utilizzare il programmatore, revocare la connessione chiave o agente nella console, quindi ripetere il controllo di accesso gratuito. Deve fallire. Il logout locale da solo non revoca le credenziali del server; i file già esportati rimangono sul disco.


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

## Controlli di distribuzione che falliscono

| Sintomo | Risolto |
| --- | --- |
| Comando non trovato / sbagliato CLI versione | Controllare il comando -v flashdata e FLASHDATA_BIN in runtime.sh. Per Docker, ricostruire ed eseguire il controllo --version dell'immagine. |
| Supporto mancante o il permesso negato | Creare le cartelle di stato e di attività sull'host Docker, di proprietà del servizio UID/GID. Mantenere i loro sentieri stabili. |
| replacement_requires_flag | Il profilo ha una chiave salvata diversa. Verificare prima l'accesso esistente; utilizzare la procedura di rotazione per una sostituzione prevista. |
| Non può decifrare l'accesso salvato | Esegui come utente che l'ha fornito, nello stesso ambiente credenzialial-store. Fornire l'accesso su una nuova destinazione invece di copiare un profilo crittografato del computer portatile. |
| Risultato della verifica dei costi false | Ispezionare balance.json e preflight.json. Richiedere un prezzo disponibile, il permesso di origine e abbastanza equilibrio prima di presentare. |
| run_account_mismatch | Controllare l'account selezionato e le origini API. Ripristinare l'accesso originale; non rinominare la corsa per bypassare il recupero. |
| run_id_input_conflict | Ripristinare la richiesta originale dal tentativo request.json. Utilizzare un nuovo run ID solo per un nuovo compito pagato. |
| CI rimane in coda | Controlla che il corridore sia online e abbia ogni etichetta run-on. Questo flusso di lavoro richiede un persistente corridore Linux. |

- [Recuperare una corsa salvata](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)
