# Sebarkan loading kerja FlashData

Jalankan aplikasi atau agen Anda CLI tugas pada Linux atau Docker, kemudian verifikasi akses dan hasil menggunakan ulang setelah restart.

Referensi kanonikal: https://flashdata.dev/id/docs/guides/production-deployment
Diulang: 2026-11-05 oleh FlashData

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

## 1. Pilih waktu jalan

Gunakan Linux host dengan Bash dan jq, dan pemilik API kunci dengan google_search izin. Jalankan setup sebagai pengguna OS yang akan menjalankan tugas tersebut. Buat folder tugas pribadi ini untuk langkah 1–4; label berkas menampilkan subfolder apapun.

### Membuat folder tugas

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

### Server Linux

Instal asli CLI pertama. Jalankan perintah -v flashdata untuk menemukan lokasi absolut, kemudian set FLASHDATA_BIN ke jalur tersebut dalam runtime.sh. Atur nama profil dan persisten path keadaan sekali di sini, kemudian simpan berkas.

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

Pada Linux Docker host dengan curl, tar dan sha256sum, download disematkan CLI untuk host CPU. Simpan image/Dockerfile dan image/.dockerignore di bawah ini, buat gambar itu, lalu selamatkan runtime.sh. Pembantu berjalan sebagai UID/GID Anda dan mount negara dan tugas folder ke setiap wadah baru.

#### Unduh dan verifikasi 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
```

#### Bangun gambar lokal yang diperlukan

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

- [Instal asli CLI](https://flashdata.dev/id/docs/guides/flashdata-cli/reference.md#install)
- [Kunci dan perizinan pemilik](https://flashdata.dev/id/docs/guides/api-keys-and-permissions/reference.md)

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

### Periksa waktu-jalan yang dipilih

Jalankan dari folder tugas. run_flashdata adalah pembantu disimpan dalam runtime.sh; semua perintah kemudian menggunakan profil dan direktori negara. Ini mengabaikan FLASHDATA_API_KEY sehingga kunci lingkungan tidak dapat menggantikan profil yang disimpan. Mengharapkan CLI dan versi jq.

#### Mempersiapkan kondisi persisten permintaan 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. Pasang akses pemilik sekali

Bila profil sudah memiliki akses pemilik, lewati impor dan jalankan pemeriksaan di bawah ini. Jika tidak, kait sebuah owner-key berkas rahasia dapat dibaca oleh pengguna layanan dan mengganti path contoh dengan lokasinya. Impor membacanya melalui stdin; Docker tidak menyalin ke dalam gambar.

### Arahkan ke berkas rahasia yang telah dikerahkan

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

### Impor dan verifikasi pada waktu-jalan yang dipilih

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

- [Klaim percobaan sebelum berulang gunakan](https://flashdata.dev/id/docs/guides/agent-onboarding/reference.md#claim)

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

### Konfirmasikan akun dan ijin

Cek sidik jari akun ID, diizinkan sumber dan perlindungan kredensial, kemudian true. Konfirmasi akun ID adalah pemilik yang dimaksudkan sebelum melanjutkan. access.json tetap dalam folder tugas untuk inspeksi.

#### Akses bebas pemilik tersimpan

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

### Penyimpanan kredensial dan berkas persisten

Inspeksi data.credentialProtection dalam auth status. Linux dapat menggunakan sebuah Secret Service terkunci; host tanpa kepala atau kontainer di atas dapat menggunakan sebuah owner- hanya berkas plaintext. Jaga direktori negara swasta dan gigih. Provisi pengguna dikerahkan secara terpisah dari profil terenkripsi laptop Anda.

| Simpan | Lokasi |
| --- | --- |
| Kredensial dan jalankan jurnal | FLASHDATA_STATE_DIR |
| Masukan, penerimaan dan hasil | Folder tugas; dikait sebagai /work dalam Docker. |

- [Menyediakan dan memindah akses](https://flashdata.dev/id/docs/guides/agent-access/reference.md)

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

## 3. Validasi permintaan dan biaya

Simpan request.json di samping runtime.sh. Pemeriksaan berikut memvalidasi akses berulang dan permintaan, membaca harga sekarang dan membandingkannya dengan keseimbangan yang tersedia. Ini menyerahkan tidak ada pencarian dan tidak reserve kredit. Lanjutkan hanya ketika sidik jari filter true.

### request.json

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

### Periksa sebelum tugas pertama yang dibayar

```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. Jalankan sekali dan verifikasi penggunaan ulang

Simpan deployment-check.sh di bawah ini. Dengan penyewaan baru - tugas pertama - ID, eksekusi pertama yang mengajukan satu pencarian dibayar; yang kedua memulai proses baru dan membaca hasil yang disimpan. Jika ID ini sudah selesai dalam profil yang sama, keduanya mencoba menggunakannya kembali.


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

### Simpan deployment-check.sh

Buat deployment-check.sh di samping runtime.sh dan request.json dalam folder tugas pribadi pada host. Salin skrip lengkap di bawah ini dan simpan.

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

### Jalankan pemeriksaan tersimpan dua kali

Jalankan dari folder tugas host sebagai pengguna layanan yang sama. Kedua proses tersebut memuat runtime.sh disimpan dalam langkah 1.

#### Jalankan, lalu jalankan ulang proses

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

### Verifikasi tanda terima kedua

Untuk lari baru, diharapkan cached: false, kemudian cached: true. Setiap upaya sidik jari nya deployment-check.XXXXXX folder dan simpan request.json, receipt.json dan error.json, plus result.json sukses. Tanda terima cache melaporkan penggunaan asli. Usaha yang gagal menyimpan berkas untuk pemulihan.

#### Tanda terima kedua

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

- [Pulihkan suatu run yang terganggu](https://flashdata.dev/id/docs/guides/agent-recovery/reference.md)

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

### Baca hasil pencarian yang disimpan

Atur ATTEMPT_DIR ke folder kedua yang sukses dicetak di atas, sebagai contoh ekspor ATTEMPT_DIR = './deployment-check.ABC123'. Perintah-perintah ini hanya membaca berkas lokal.

#### Menerima dan sumber taut

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

### Pindah dari pemeriksaan penyebaran ke tugas yang berulang

Cek ini telah tetap berjalan ID. Untuk pekerjaan berulang, memberikan setiap kejadian yang dimaksudkan sendiri ID dan mempertahankan yang dipilih waktu-jalan, akun, snapshot input dan mount negara bagian. Tambahkan perintah pencarian pelari yang berulang untuk menggunakan run_flashdata sehingga tugas Docker tetap di dalam kontainer.

- [Recurring IDs, penerimaan dan penjadwalan](https://flashdata.dev/id/docs/guides/recurring-tasks/reference.md)

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

## Periksa akses dari Aksi GitHub

Gunakan kepercayaan, gigih Linux runner dengan Bash, jq dan CLI profil telah terpasang di bawah pelari 's OS pengguna. Simpan alur kerja ini di repositori aplikasi Anda. Ini memeriksa host CLI tanpa menjalankan tugas yang dibayar.

1. Atur flashdat- label penelitian untuk pelari itu.
2. Set variabel repositori FLASHDATA_BIN dan FLASHDATA_STATE_DIR ke lokasi absolut, dan FLASHDATA_PROFILE ke nama profil terpasang.

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

- [Label 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>

### Jalankan pemeriksaan akses

Setelah menyimpan alur kerja pada branch baku repositori, buka Aksi GNU FlashData cek lasflow kerja Engkau. Mengharapkan true dan cek sukses. Kehilangan akses atau izin gagal pekerjaan tanpa mengirimkan pencarian.


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

### Menjaga kondisi eksekusi di seluruh tugas

Seorang pelari fana dimulai tanpa jurnal asli. Gunakan kondisi aplikasi tahan lama atau runner persisten untuk pekerjaan berulang yang dibayar. Hanya memasang ulang kunci yang tak dapat mengidentifikasi pengajuan tugas sebelumnya. Pertahankan direktori negara dan keluaran tugas pribadi; jangan upload mereka sebagai artefak CI.


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

## Putar atau batalkan akses yang telah dikerahkan

Pause pengiriman. Dalam folder tugas, titik FLASHDATA_KEY_FILE di kunci pengganti untuk akun yang sama dan sumber yang diperlukan, kemudian jalankan perintah di bawah. Ulangi pemeriksaan akses dan deployment-check.sh; diduga cached: true. Mundurkan kunci lama setelah verifikasi dan simpan profil dan direktori negara.

### Ganti kunci melalui 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
```

- [Pengelolaan kunci API](https://flashdata.dev/id/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Connected apps](https://flashdata.dev/app/settings/connections)

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

### Hentikan akses sepenuhnya

Jeda penjadwalan, batalkan kunci atau koneksi agen dalam konsol, lalu ulangi pemeriksaan akses bebas. Ini harus gagal. Logout lokal sendiri tidak mencabut kredensial server; telah diekspor berkas tetap pada disk.


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

## Penyebaran cek yang gagal

| Symptom | Perbaiki |
| --- | --- |
| Perintah tidak ditemukan / salah CLI versi | Periksa perintah -v flashdata dan FLASHDATA_BIN dalam runtime.sh. Untuk Docker, bangun kembali dan menjalankan cek gambar --version. |
| Kehilangan mount atau ijin ditolak | Membuat folder status dan tugas pada host Docker, yang dimiliki oleh layanan UID/GID. Jaga jalan mereka tetap stabil. |
| replacement_requires_flag | Profil ini memiliki kunci lain yang disimpan. Verifikasi akses yang ada pertama; gunakan prosedur rotasi untuk pengganti yang dimaksudkan. |
| Tidak dapat mendekripsi akses tersimpan | Jalankan sebagai pengguna yang mengaturnya, dalam lingkungan yang sama. Akses provisi pada tujuan baru daripada menyalin profil laptop terenkripsi. |
| Pemeriksaan biaya mengembalikan false | Inspeksi balance.json dan preflight.json. Perlu harga yang tersedia, ijin sumber dan saldo yang cukup sebelum mengirimkan. |
| run_account_mismatch | Periksa akun yang dipilih dan asal API. Kembalikan akses asli; jangan ubah nama jalankan ke bypass pemulihan. |
| run_id_input_conflict | Kembalikan permintaan asli dari percobaan request.json. Gunakan run baru ID hanya untuk tugas baru yang dibayar. |
| CI tetap mengantri | Periksa bahwa pelari online dan memiliki setiap runs-on label. Aliran kerja ini memerlukan pelari Linux yang gigih. |

- [Mengembalikan run yang disimpan](https://flashdata.dev/id/docs/guides/agent-recovery/reference.md)
