# Rozlokuj ładunki robocze FlashData

Uruchom swoje zadania CLI aplikacji lub agenta na Linux lub Docker, a następnie zweryfikuj dostęp i ponowne użycie wyników po ponownym uruchomieniu.

Odniesienie kanoniczne: https://flashdata.dev/pl/docs/guides/production-deployment
Przegląd: 2026-11-05 przez FlashData

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

## 1. Wybierz runtime

Użyj hosta Linux z Bash i jq, a także właściciela klucza API za pozwoleniem google_search. Uruchom konfigurację jako użytkownik OS, który będzie wykonywał zadanie. Utwórz ten prywatny folder zadań dla kroków 1–4; etykiety plików pokazują podfoldery.

### Utwórz folder zadań

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

### Serwer Linux

Zainstaluj najpierw natywny CLI. Uruchom polecenie -v flashdata, aby znaleźć jego ścieżkę bezwzględną, a następnie ustaw FLASHDATA_BIN na tę ścieżkę w runtime.sh. Ustaw tu nazwę profilu i ścieżkę stanu uporczywego, a następnie zapisz plik.

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

Na komputerze Linux Docker z curl, smołą i sha256sum, pobierz przypinany CLI dla procesora hosta. Zapisz image/Dockerfile i image/.dockerignore poniżej, zbuduj obraz, a następnie zapisz runtime.sh. Pomocnik działa jako Twój UID/GID i montuje stan i foldery zadań do każdego nowego pojemnika.

#### Pobierz i zweryfikuj 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
```

#### Zbuduj lokalny wizerunek · nie trzeba referencji

```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 wydanie 1.2.1](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.2.1)
- [Docker montuje złącza](https://docs.docker.com/engine/storage/bind-mounts/)

- [Zainstaluj natywny CLI](https://flashdata.dev/pl/docs/guides/flashdata-cli/reference.md#install)
- [Klucz właściciela i uprawnienia](https://flashdata.dev/pl/docs/guides/api-keys-and-permissions/reference.md)

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

### Zaznacz wybrany runtime

Uruchom z folderu zadań. run_flashdata jest pomocnikiem zapisanym w runtime.sh; wszystkie późniejsze polecenia używają jego profilu i katalogu stanu. Ignoruje FLASHDATA_API_KEY, więc klucz środowiskowy nie może zastąpić zapisanego profilu. Oczekuj wersji CLI i jq.

#### Przygotowanie stanu trwałego · bez zapytania 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. Zainstaluj raz dostęp właściciela

Jeśli profil ma już dostęp do właściciela, pomiń import i uruchom czek poniżej. W przeciwnym razie należy zamontować własny-klucz tajny plik do odczytu przez użytkownika usługi i zastąpić ścieżkę przykładową jego lokalizacją. Import odczytuje go przez stdin; Docker nie kopiuje go do obrazu.

### Punkt do tajnego pliku rozmieszczonego

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

### Importuj i weryfikuj w wybranym runtime

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

- [Wystąpienie z wnioskiem o przeprowadzenie badania przed ponownym użyciem](https://flashdata.dev/pl/docs/guides/agent-onboarding/reference.md#claim)

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

### Potwierdź konto i pozwolenie

Kontrola drukuje konto ID, dozwolone źródła i ochronę kredytową, a następnie true. Potwierdź konto ID jest zamierzonym właścicielem przed kontynuacją. access.json pozostaje w folderze zadań do kontroli.

#### Oszczędzony dostęp właściciela · bezpłatny czek

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

### Pliki pamięci kredytowej i plików trwałych

Sprawdzić data.credentialProtection w auth status. Linux może korzystać z odblokowanych Secret Service; host bez głowy lub kontener powyżej może korzystać z pliku tekstowego tylko dla właścicieli. Zachowaj katalog stanu prywatny i trwały. Dostarcz użytkownikowi rozmieszczonemu oddzielnie od zaszyfrowanego profilu laptopa.

| Zachowaj | Lokalizacja |
| --- | --- |
| Fundamentalne i uruchomić dziennik | FLASHDATA_STATE_DIR |
| Wpływy, wpływy i wyniki | Folder zadań; zamontowany jako /work w Docker. |

- [Zapewnianie i przenoszenie dostępu](https://flashdata.dev/pl/docs/guides/agent-access/reference.md)

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

## 3. Zatwierdzenie wniosku i kosztów

Zapisz request.json obok runtime.sh. Następująca kontrola potwierdza powtarzający się dostęp i wniosek, czyta aktualne ceny i porównuje je z dostępną równowagą. Nie przedstawia żadnych poszukiwań i nie rezerwuje kredytów. Kontynuować tylko wtedy, gdy filtr drukuje true.

### request.json

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

### Sprawdź przed pierwszym płatnym zadaniem

```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. Uruchom raz i zweryfikuj ponowne użycie

Zapisz deployment-check.sh poniżej. Z nowym wdrożeniem - pierwszy - uruchomienie zadania ID, pierwsza realizacja przedstawia jedno płatne wyszukiwanie; druga rozpoczyna nowy proces i odczytuje zapisany wynik. Jeśli ten ID został już ukończony w tym samym profilu, oba próby ponownego użycia go.


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

### Zapisz deployment-check.sh

Utwórz deployment-check.sh obok runtime.sh i request.json w prywatnym folderze zadań na hoście. Skopiuj do niego cały skrypt poniżej i zapisz go.

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

### Uruchom zapisany czek dwa razy

Uruchom z tego folderu zadań hosta jako ten sam użytkownik usług. Oba procesy ładują runtime.sh zapisane w kroku 1.

#### Uruchom, a następnie ponownie uruchom proces

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

### Weryfikacja drugiego odbioru

Na nowy bieg, oczekuj cached: false, a następnie cached: true. Każda próba drukowania folderu deployment-check.XXXXXX i zapisywania request.json, receipt.json i error.json oraz result.json po pomyślnym zakończeniu. Pokwitowanie w pamięci podręcznej podaje pierwotne zastosowanie. Nieudana próba zatrzymuje pliki do odzyskania.

#### Drugi paragon · wyciąg

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

- [Odzyskanie przerwanego biegu](https://flashdata.dev/pl/docs/guides/agent-recovery/reference.md)

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

### Przeczytaj zapisany wynik wyszukiwania

Ustaw ATTEMPT_DIR na drugi folder, który odniósł sukces, wydrukowany powyżej, na przykład wyeksportuj ATTEMPT_DIR = './deployment-check.ABC123'. Polecenia te odczytują tylko pliki lokalne.

#### Linki odbiorcze i źródłowe

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

### Przejście z kontroli rozmieszczenia do powtarzającego się zadania

Ten czek ma stały bieg ID. W przypadku powtarzających się prac, należy podać każdemu planowanemu wystąpieniu własne ID i zachować wybrany runtime, konto, migawki wejściowe i stanowe oprawy. Dostosuj powtarzające się polecenie zapytania biegacza, aby używać run_flashdata, tak aby zadania Docker pozostawały wewnątrz pojemnika.

- [Powtarzanie IDs, paragony i harmonogramy](https://flashdata.dev/pl/docs/guides/recurring-tasks/reference.md)

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

## Sprawdź dostęp z Akcji GitHub

Używaj zaufanego, trwałego biegacza Linux, Bash, jq i profilu CLI już zainstalowanego pod użytkownikiem OS. Zapisz ten przepływ pracy w repozytorium aplikacji. Sprawdza hosta CLI bez wykonywania płatnego zadania.

1. Przydziel etykietę z danymi z badań temu zawodnikowi.
2. Ustaw zmienne repozytorium FLASHDATA_BIN i FLASHDATA_STATE_DIR na jego ścieżki bezwzględne, a FLASHDATA_PROFILE na zainstalowaną nazwę profilu.

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

- [Etykiety bieżnika 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>

### Uruchom kontrolę dostępu

Po zapisaniu przepływu pracy w domyślnej gałęzi repozytorium, otwórz działania → FlashData kontroli dostępu → Uruchom przepływ pracy. Oczekuj true i udanego sprawdzenia. Brak dostępu lub zezwolenia nie udaje się bez zgłoszenia wyszukiwania.


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

### Utrzymanie stanu wykonania w różnych miejscach pracy

Efemeryczny biegacz zaczyna bez oryginalnego dziennika. Użyj trwałego stanu aplikacji lub stałego biegacza do płatnej powtarzającej się pracy. Ponowne zainstalowanie tylko klucza nie może zidentyfikować wcześniejszego zadania. Zachowaj katalog stanu i wyjście zadania prywatne; nie wysyłaj ich jako artefakty CI.


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

## Obrót lub cofnięcie rozmieszczonego dostępu

Wstrzymać dyspozycję. W folderze zadań, wskaż FLASHDATA_KEY_FILE na klucz zastępczy dla tego samego konta i wymaganych źródeł, a następnie uruchom poniższe polecenia. Powtórzyć kontrolę dostępu i deployment-check.sh; spodziewać się cached: true. Po sprawdzeniu ponownie odtworzyć stary klucz i zachować profil i katalog stanu.

### Zamień klucz przez 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
```

- [Zarządzanie kluczami API](https://flashdata.dev/pl/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Connected apps](https://flashdata.dev/app/settings/connections)

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

### Zatrzymać dostęp całkowicie

Wstrzymaj terminarz, cofnij połączenie z kluczykiem lub agentem w konsoli, a następnie powtórz kontrolę dostępu. To musi zawieść. Lokalny wylogowanie sam nie cofa serwer creditial; już eksportowane pliki pozostają na dysku.


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

## Kontrole wdrażania, które nie powiodły się

| Symptom | Napraw |
| --- | --- |
| Polecenie nie odnalezione / niepoprawna wersja CLI | Sprawdź komendę -v flashdata i FLASHDATA_BIN w runtime.sh. Dla Docker odbudować i uruchomić kontrolę obrazu --version. |
| Brak montowania lub odmowy pozwolenia | Utwórz stan i foldery zadań na hoście Docker, należącym do serwisu UID/GID. Ustabilizujcie ich ścieżki. |
| replacement_requires_flag | Profil ma inny zapisany klucz. Weryfikacja istniejącego dostępu w pierwszej kolejności; zastosowanie procedury rotacji w odniesieniu do planowanego zastąpienia. |
| Nie można odszyfrować zapisanego dostępu | Uruchom jako użytkownik, który to zapewnił, w tym samym środowisku creditial- store. Zapewnienie dostępu do nowego miejsca przeznaczenia zamiast kopiowania zaszyfrowanego profilu laptopa. |
| Kontrola kosztów zwraca false | Sprawdzić balance.json i preflight.json. Wymagane są dostępne ceny, pozwolenie na korzystanie ze źródła i wystarczająca równowaga przed złożeniem. |
| run_account_mismatch | Sprawdź wybrane konto i pochodzenie API. Przywróć oryginalny dostęp; nie zmieniaj nazwy biegu, aby obejść odzyskanie. |
| run_id_input_conflict | Przywróć oryginalną prośbę z próby request.json. Używaj nowej wersji ID tylko dla planowanego nowego zadania płatnego. |
| CI zostaje w kolejce | Sprawdź, czy biegacz jest online i ma wszystkie biegi na etykiecie. Ten strumień pracy wymaga stałego samodzielnego prowadzenia Linux. |

- [Odzyskiwanie zapisanego biegu](https://flashdata.dev/pl/docs/guides/agent-recovery/reference.md)
