Dokumentation durchsuchen
Anleitungen
Führen Sie die CLI-Aufgaben Ihrer App oder Ihres Agenten auf Linux oder Docker aus, überprüfen Sie dann den Zugriff und die Wiederverwendung der Ergebnisse nach einem Neustart.
Auf dieser Seite
1. Wählen Sie die Runtime
Verwenden Sie einen Linux-Host mit Bash und jq und einen Besitzer-API-Schlüssel mit google_search-Berechtigung. Führen Sie die Einrichtung als OS-Benutzer aus, der die Aufgabe ausführt. Erstellen Sie diesen privaten Aufgabenordner für die Schritte 1–4; Dateietiketten zeigen alle Unterordner an.
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"Installieren Sie zuerst das native CLI. Führen Sie den Befehl -v flashdata aus, um seinen absoluten Pfad zu finden, und setzen Sie dann FLASHDATA_BIN auf diesen Pfad in runtime.sh. Legen Sie den Profilnamen und den persistenten Statuspfad einmal hier fest und speichern Sie dann die Datei.
# 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"
}Laden Sie auf einem Linux Docker-Host mit curl, tar und sha256sum das angeheftete CLI für die Host-CPU herunter. Speichern Sie image/Dockerfile und image/.dockerignore unten, erstellen Sie das Bild und speichern Sie dann runtime.sh. Der Helfer wird als Ihr UID/GID ausgeführt und fügt die Status- und Aufgabenordner in jeden neuen Container ein.
(
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
)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"]*
!Dockerfile
!flashdatadocker build --tag flashdata-runtime:1.2.1 ./image
docker run --rm flashdata-runtime:1.2.1 --version# 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
}Überprüfen Sie die ausgewählte Laufzeit
Aus dem Aufgabenordner ausführen. run_flashdata ist der in runtime.sh gespeicherte Helfer; alle späteren Befehle verwenden das Profil und das Zustandsverzeichnis. Es ignoriert FLASHDATA_API_KEY, so dass ein Umgebungsschlüssel das gespeicherte Profil nicht ersetzen kann. Erwarten Sie die Versionen CLI und jq.
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version2. Besitzerzugriff einmal installieren
Wenn das profil bereits besitzerzugriff hat, überspringen sie den import und führen sie den check unten aus. Andernfalls montieren Sie eine vom Dienstbenutzer lesbare geheime Besitzerschlüsseldatei und ersetzen Sie den Beispielpfad durch seinen Standort. Der Import liest es durch stdin; Docker kopiert es nicht in das Bild.
export FLASHDATA_KEY_FILE='/run/secrets/flashdata_api_key'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-interactiveBestätigen Sie das Konto und die Erlaubnis
Der Scheck druckt das Konto ID, die zulässigen Quellen und den Anmeldeschutz, dann true. Bestätigen Sie, dass das Konto ID der vorgesehene Eigentümer ist, bevor Sie fortfahren. access.json bleibt im Aufgabenordner zur Inspektion.
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.jsonCredential Storage und persistente Dateien
data.credentialProtection in auth status untersuchen. Linux kann einen entsperrten Secret Service verwenden; ein Headless-Host oder der Container oben kann eine reine Klartextdatei verwenden. Halten sie das staatsverzeichnis privat und persistent. Stellen Sie den bereitgestellten Benutzer separat vom verschlüsselten Profil Ihres Laptops zur Verfügung.
| Bleiben | Standort |
|---|---|
| Credentials und Run Journal | FLASHDATA_STATE_DIR |
| Input, Einnahmen und Ergebnisse | Der Aufgabenordner; als /work in Docker montiert. |
3. Validierung des Antrags und der Kosten
Speichern Sie request.json neben runtime.sh. Der folgende Check validiert den wiederkehrenden Zugriff und die Anfrage, liest die aktuelle Preisgestaltung und vergleicht sie mit dem verfügbaren Saldo. Es stellt keine Suche und keine Reserve Credits. Fahren Sie nur fort, wenn der Filter true druckt.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}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.json4. Einmal laufen und Wiederverwendung überprüfen
Speichern Sie deployment-check.sh unten. Mit einem neuen Deployment-First-Task-Lauf ID sendet die erste Ausführung eine bezahlte Suche, die zweite startet einen neuen Prozess und liest das gespeicherte Ergebnis. Wenn dieses ID bereits im selben Profil abgeschlossen ist, versuchen beide, es wiederzuverwenden.
Speichern Sie deployment-check.sh
Erstellen Sie deployment-check.sh neben runtime.sh und request.json im privaten Aufgabenordner auf dem Host. Kopieren Sie das komplette Skript unten und speichern Sie es.
#!/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"Führen Sie den gespeicherten Scheck zweimal aus
Führen Sie aus diesem Host-Aufgabenordner als derselbe Dienstbenutzer aus. Beide Prozesse laden das in Schritt 1 gespeicherte runtime.sh.
# 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Überprüfen Sie die zweite Quittung
Für einen neuen Lauf, erwarten Sie cached: false, dann cached: true. Jeder Versuch druckt seinen deployment-check.XXXXXX-Ordner und speichert request.json, receipt.json und error.json sowie result.json bei Erfolg. Die zwischengespeicherte Quittung meldet die ursprüngliche Nutzung. Ein fehlgeschlagener Versuch bewahrt seine Dateien zur Wiederherstellung auf.
{
"ok": true,
"runId": "deployment-first-task",
"cached": true
}Lesen Sie das gespeicherte Suchergebnis
Setzen Sie ATTEMPT_DIR auf den zweiten erfolgreichen Ordner, der oben gedruckt wurde, z. B. Exportieren ATTEMPT_DIR='./deployment-check.ABC123'. Diese Befehle lesen nur lokale Dateien.
# 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"Wechseln Sie von einer Bereitstellungsprüfung zu einer wiederkehrenden Aufgabe
Dieser Check hat einen festen Lauf ID. Geben Sie für wiederkehrende Arbeiten jedem beabsichtigten Ereignis ein eigenes ID und behalten Sie die ausgewählte Laufzeit, das Konto, die Eingabe-Snapshots und die Status-Mounts bei. Passen Sie den Abfragebefehl des wiederkehrenden Läufers an, um run_flashdata zu verwenden, damit Docker-Aufgaben im Container verbleiben.
Überprüfen Sie den Zugriff von GitHub Aktionen
Verwenden Sie einen vertrauenswürdigen, persistenten Linux-Läufer mit Bash, jq und dem CLI-Profil, das bereits unter dem OS-Benutzer des Läufers installiert ist. Speichern Sie diesen Workflow im Repository Ihrer Anwendung. Es überprüft den Host CLI, ohne eine bezahlte Aufgabe auszuführen.
- Weisen Sie das Flashdata-Research-Label diesem Läufer zu.
- Setzen Sie die Repository-Variablen FLASHDATA_BIN und FLASHDATA_STATE_DIR auf ihre absoluten Pfade und FLASHDATA_PROFILE auf den installierten Profilnamen.
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)'Führen Sie die Zugangsprüfung durch
Nachdem Sie den Workflow im Standardzweig des Repositorys gespeichert haben, öffnen Sie Aktionen → FlashData-Zugriffsprüfung → Workflow ausführen. Erwarten Sie true und eine erfolgreiche Prüfung. Fehlender Zugriff oder fehlende Berechtigung schlägt den Job fehl, ohne eine Suche einzureichen.
Halten Sie den Ausführungszustand über Jobs hinweg
Ein ephemerer Läufer beginnt ohne das ursprüngliche Journal. Verwenden Sie einen dauerhaften Anwendungszustand oder einen persistenten Läufer für bezahlte wiederkehrende Arbeit. Durch die Neuinstallation nur des Schlüssels kann die Einreichung eines früheren Auftrags nicht identifiziert werden. Halten Sie das Verzeichnis und die Aufgabenausgaben privat; laden Sie sie nicht als CI-Artefakte hoch.
Rotieren oder Entziehen des bereitgestellten Zugriffs
Versandpause. Zeigen Sie im Aufgabenordner FLASHDATA_KEY_FILE auf einen Ersatzschlüssel für dasselbe Konto und die erforderlichen Quellen und führen Sie dann die folgenden Befehle aus. Wiederholen Sie die Zugriffsprüfung und deployment-check.sh; erwarten Sie cached: true. Widerrufen Sie den alten Schlüssel nach der Verifizierung und behalten Sie das Profil und das Statusverzeichnis bei.
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-interactiveZugriff vollständig stoppen
Unterbrechen Sie den Scheduler, widerrufen Sie den Schlüssel oder die Agentenverbindung in der Konsole und wiederholen Sie dann die Überprüfung des freien Zugriffs. Sie muss scheitern. Lokale Anmeldung allein widerruft nicht die Server-Anmeldeinformationen; bereits exportierte Dateien bleiben auf der Festplatte.
Deployment-Checks, die fehlschlagen
| Symptom | Fixpunkt |
|---|---|
| Befehl nicht gefunden / falsche CLI Version | Prüfen Sie den Befehl -v flashdata und FLASHDATA_BIN in runtime.sh. Für Docker erstellen und führen Sie den --version-Check des Bildes aus. |
| Fehlendes Reittier oder Verweigerung der Erlaubnis | Erstellen Sie den Status und die Aufgabenordner auf dem Docker-Host, der dem Dienst UID/GID. gehört Halten Sie Ihre Wege stabil. |
| replacement_requires_flag | Das Profil hat einen anderen gespeicherten Schlüssel. Verifizieren Sie zuerst den vorhandenen Zugriff; Verwenden Sie das Rotationsverfahren für einen beabsichtigten Ersatz. |
| Kann den gespeicherten Zugriff nicht entschlüsseln | Führen Sie als Benutzer, der es bereitgestellt hat, in der gleichen Credential-Store-Umgebung aus. Bereitstellen von Zugriff auf ein neues Ziel, anstatt ein verschlüsseltes Laptop-Profil zu kopieren. |
| Kostenkontrolle kehrt zurück false | Untersuchen Sie balance.json und preflight.json. Benötigen Sie einen verfügbaren Preis, eine Quellberechtigung und genügend Saldo, bevor Sie einreichen. |
| run_account_mismatch | Überprüfen Sie das ausgewählte Konto und die API-Ursprünge. Stellen Sie den ursprünglichen Zugriff wieder her; Benennen Sie den Lauf nicht um, um die Wiederherstellung zu umgehen. |
| run_id_input_conflict | Stellen Sie die ursprüngliche Anforderung aus dem request.json des Versuchs wieder her. Verwenden Sie eine neue Ausführung ID nur für eine beabsichtigte neue bezahlte Aufgabe. |
| CI bleibt in der Schlange | Überprüfen Sie, ob der Läufer online ist und jedes Run-on-Label hat. Dieser Workflow erfordert einen persistenten selbst gehosteten Linux-Läufer. |