# Despliega tareas de FlashData

Ejecuta las tareas de CLI de tu aplicación o agente en Linux o Docker. Después, comprueba que el acceso y los resultados se puedan reutilizar tras un reinicio.

Referencia canónica: https://flashdata.dev/es/docs/guides/production-deployment
Revisado: 2026-11-05 por FlashData

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

## 1. Elige el tiempo de ejecución

Utilice un host Linux con Bash y jq, y una tecla API propietario con permiso google_search. Ejecute la configuración como el usuario OS que ejecutará la tarea. Cree esta carpeta de tarea privada para los pasos 1–4; etiquetas de archivos muestren cualquier subcarpete.

### Crear la carpeta de tareas

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

### Servidor Linux

Instala el nativo CLI primero. Correr comando -v flashdata para encontrar su camino absoluto, luego establecer FLASHDATA_BIN a esa ruta en runtime.sh. Establecer el nombre de perfil y la ruta de estado persistente una vez aquí, a continuación, guardar el archivo.

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

En una Linux Docker host con curl, tar y sha256sum, descargar el pinned CLI para el host CPU. Guardar imagen/Dockerfile imagen y imagen/.dockerignore abajo, construir la imagen, luego guardar runtime.sh. El ayudante funciona como su UID/GID y monta las carpetas de estado y tarea en cada nuevo contenedor.

#### Descargar y verificar el 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
```

#### Construir la imagen local · no se necesitan credenciales

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

- [Instalar el CLI nativo](https://flashdata.dev/es/docs/guides/flashdata-cli/reference.md#install)
- [Propietario clave y permisos](https://flashdata.dev/es/docs/guides/api-keys-and-permissions/reference.md)

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

### Compruebe el tiempo de ejecución seleccionado

run_flashdata es el ayudante guardado en runtime.sh; todos los comandos posteriores utilizan su perfil y directorio estatal. Ignora FLASHDATA_API_KEY por lo que una clave ambiental no puede reemplazar el perfil guardado. Espere las versiones CLI y jq.

#### Preparación de estado persistente · no 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. Instalar el acceso del propietario una vez

Si el perfil ya tiene acceso al propietario, salta la importación y ejecute el cheque a continuación. De lo contrario, monta un archivo secreto propietario-key legible por el usuario del servicio y reemplaza la ruta del ejemplo con su ubicación. La importación lo lee a través de stdin; Docker no lo copia en la imagen.

### Punto al archivo secreto desplegado

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

### Importar y verificar en el tiempo de ejecución seleccionado

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

- [Claim a trial before recurring use](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md#claim)

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

### Confirme la cuenta y el permiso

El cheque imprime la cuenta ID, las fuentes permitidas y la protección credencial, entonces es cierto. Confirme la cuenta ID es el propietario indicado antes de continuar. access.json se queda en la carpeta de tareas para la inspección.

#### Acceso al propietario guardado · cheque 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>

### Almacenamiento creíble y archivos persistentes

Inspeccione data.credentialProtection en estado de austeridad. Linux puede utilizar un servicio secreto desbloqueado; un host sin cabeza o el contenedor anterior puede utilizar un archivo de texto solo propietario. Mantenga el directorio estatal privado y persistente. Proporcione al usuario desplegado separadamente del perfil cifrado de su computadora portátil.

| Mantente quieto. | Ubicación |
| --- | --- |
| Credenciales y diario de ejecución | FLASHDATA_STATE_DIR |
| Entrada, recibos y resultados | La carpeta de tarea; montada como /work en Docker. |

- [Suministro y acceso en movimiento](https://flashdata.dev/es/docs/guides/agent-access/reference.md)

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

## 3. Validar la solicitud y el costo

Guardar request.json junto a runtime.sh. El siguiente cheque valida el acceso recurrente y la solicitud, lee los precios actuales y lo compara con el saldo disponible. No presenta ninguna búsqueda y no reserva créditos. Continúe sólo cuando el filtro imprima verdad.

### request.json

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

### Compruebe antes de la primera tarea pagada

```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. Correr una vez y verificar la reutilización

Guardar deployment-check.sh a continuación. Con un nuevo ID de la primera ejecución, la primera ejecución presenta una búsqueda pagada; el segundo comienza un nuevo proceso y lee el resultado guardado. Si este ID ya se ha completado en el mismo perfil, ambos intentos reutilizarlo.


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

### Guardar deployment-check.sh

Cree deployment-check.sh junto a runtime.sh y request.json en la carpeta de tareas privada en el host. Copia el script completo a continuación y guárdalo.

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

### Corre el cheque guardado dos veces

Ejecutar desde esa carpeta de tareas de host como el mismo usuario de servicio. Ambos procesos cargan el runtime.sh guardado en el paso 1.

#### Corre, luego reinicia el proceso

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

### Verificar el segundo recibo

Para una nueva ejecución, espere caché: falso, luego caché: cierto. Cada intento imprime su carpeta deployment-check.XXXXXX y guarda request.json, receipt.json y error.json, más result.json sobre el éxito. La recepción caché informa el uso original. Un intento fallido mantiene sus archivos para la recuperación.

#### Segundo recibo · extracto

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

- [Recuperar una carrera interrumpida](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)

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

### Lea el resultado de la búsqueda guardada

Establecer ATTEMPT_DIR a la segunda carpeta exitosa impresa anteriormente, por ejemplo exportar ATTEMPT_DIR='./deployment-check.ABC123'. Estos comandos leen solamente los archivos locales.

#### Enlaces de recepción y fuente

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

### Mover de un cheque de implementación a una tarea recurrente

Este cheque tiene una ejecución fija ID. Para el trabajo recurrente, da a cada ocurrencia prevista su propio ID y retiene el tiempo de ejecución seleccionado, cuenta, instantáneas de entrada y montajes estatales. Adapte el comando de consulta del corredor recurrente para utilizar run_flashdata así que las tareas Docker permanecen dentro del contenedor.

- [Recurriendo IDs, recibos y programación](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)

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

## Compruebe el acceso desde GitHub Actions

Utilice un controlador Linux confiable y persistente con Bash, jq y el perfil CLI ya instalado bajo el usuario OS del corredor. Ahorre este flujo de trabajo en el repositorio de su aplicación. Chequea el host CLI sin ejecutar una tarea pagada.

1. Asignar la etiqueta de flashdata-research a ese corredor.
2. Establecer variables de repositorio FLASHDATA_BIN y FLASHDATA_STATE_DIR a sus caminos absolutos, y FLASHDATA_PROFILE al nombre de 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)'
```

- [Etiquetas de corredor 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>

### Ejecute el cheque de acceso

Después de guardar el flujo de trabajo en la rama predeterminada del repositorio, abra Acciones → FlashData check → Ejecute el flujo de trabajo. Espere verdadero y un cheque exitoso. Falta el acceso o permiso falla el trabajo sin enviar una búsqueda.


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

### Mantener el estado de ejecución en puestos de trabajo

Un corredor efímero comienza sin la revista original. Use el estado de aplicación durable o un corredor persistente para el trabajo recurrente pagado. Reinstalar sólo la clave no puede identificar la presentación de un trabajo anterior. Mantenga el directorio estatal y salidas de tareas privadas; no subirlos como artefactos CI.


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

## Rotar o revocar el acceso desplegado

Despacho de pausa. En la carpeta de tarea, puntee FLASHDATA_KEY_FILE en una llave de reemplazo para la misma cuenta y fuentes requeridas, luego ejecute los comandos a continuación. Repita el cheque de acceso y deployment-check.sh; espere caché: verdadero. Revuelva la llave antigua después de la verificación y mantenga el directorio de perfil y estado.

### Reemplazar la llave a través de 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
```

- [Gestión de claves API](https://flashdata.dev/es/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Aplicaciones conectadas](https://flashdata.dev/app/settings/connections)

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

### Parar el acceso completamente

Pausa el cronogramador, revoca la conexión de clave o agente en la consola, luego repite el cheque de acceso gratuito. Debe fallar. El logo local por sí solo no revoca el servidor credencial; los archivos ya exportados permanecen en disco.


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

## Controles de despliegue que fallan

| Síntoma | Arreglos |
| --- | --- |
| Comando no encontrado / incorrecta CLI versión | Comprueba el comando -v flashdata y FLASHDATA_BIN en runtime.sh. Para Docker, reconstruye y ejecuta el cheque --version de la imagen. |
| Falta de montaje o permiso denegado | Cree las carpetas de estado y tarea en el host Docker, propiedad del servicio UID/GID. Mantenga sus caminos estables. |
| replacement_requires_flag | El perfil tiene una clave diferente guardada. Verifique primero el acceso existente; utilice el procedimiento de rotación para un reemplazo previsto. |
| No puede descifrar el acceso guardado | Ejecutar como el usuario que lo proporcionó, en el mismo entorno de plantación credencial. Facilitar el acceso a un nuevo destino en lugar de copiar un perfil portátil cifrado. |
| Cost check devuelve false | Inspeccione balance.json y preflight.json. Requiere un precio disponible, permiso de origen y suficiente equilibrio antes de enviar. |
| run_account_mismatch | Compruebe la cuenta seleccionada y los orígenes de API. Restaurar el acceso original; no vuelva a llamar la carrera a la recuperación de bypass. |
| run_id_input_conflict | Restaurar la solicitud original del request.json del intento. Utilice un nuevo ID sólo para una nueva tarea pagada. |
| CI se queda apagado | Compruebe que el corredor está en línea y tiene cada etiqueta de carreras. Este flujo de trabajo requiere un corredor Linux persistente. |

- [Recuperar una carrera salva](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)
