跳转到正文
中文
获取 API 密钥
浏览文档

指南

部署 FlashData 任务

在 Linux 或 Docker 中运行应用或智能体的 CLI 任务,验证重启后的访问与结果复用。

本页内容

1. 选择运行环境

需要配备 Bash 与 jq 的 Linux 主机,以及具有 google_search 权限的所有者 API Key。使用未来执行任务的系统用户配置环境。为第 1–4 步创建以下私有任务目录;文件标签会注明子目录。

创建任务目录
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"

先安装原生 CLI。运行 command -v flashdata 找到绝对路径,再填入 runtime.sh 的 FLASHDATA_BIN。在此一次性设置配置档名及持久状态路径,然后保存文件。

runtime.sh
# 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"
}

检查所选运行环境

在任务目录运行。run_flashdata 是 runtime.sh 中保存的辅助函数;后续命令均使用其配置档及状态目录。它忽略 FLASHDATA_API_KEY,避免环境密钥覆盖保存的配置档。预期输出 CLI 与 jq 版本。

准备持久状态 · 不提交查询
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version

2. 一次性安装所有者访问

若配置档已有所有者访问,跳过导入,直接执行下方检查。否则,挂载服务用户可读的所有者密钥文件,并将示例路径替换为其位置。导入通过 stdin 读取;Docker 不会将密钥复制到镜像中。

指向已部署的密钥文件
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-interactive

确认账户及权限

检查会输出账户 ID、可用来源及凭据保护方式,最后输出 true。继续前确认该 ID 属于预期所有者。access.json 保存在任务目录供检查。

已保存所有者访问 · 免费检查
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

凭据存储及持久文件

检查 auth status 中的 data.credentialProtection。Linux 可使用已解锁的 Secret Service;无桌面主机或上方容器可能使用仅所有者可读的明文文件。保持状态目录私有且持久;为部署用户独立配置访问,不复制开发机的加密配置档。

保留内容位置
凭据及运行日志FLASHDATA_STATE_DIR
输入、回执及结果任务目录;Docker 中挂载为 /work。

3. 验证请求与费用

将 request.json 保存在 runtime.sh 旁。下方检查验证定时访问和请求,读取当前价格,并与可用余额比较;不提交搜索,也不预留 Credits。仅在过滤器输出 true 后继续。

request.json
{
  "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.json

4. 运行一次并验证复用

保存下方 deployment-check.sh。deployment-first-task 为新运行 ID 时,第一次执行提交一次付费搜索;第二次启动新进程读取保存结果。若同一配置档中此 ID 已完成,两次尝试都会复用结果。

保存 deployment-check.sh

在主机的私有任务目录中、runtime.sh 和 request.json 旁创建 deployment-check.sh,复制下方完整脚本并保存。

deployment-check.sh
#!/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"

运行已保存的检查脚本两次

以同一服务用户在该主机任务目录运行。两个进程均加载第 1 步保存的 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

验证第二次回执

新运行应依次返回 cached: false 和 cached: true。每次尝试打印自己的 deployment-check.XXXXXX 目录,保存 request.json、receipt.json 和 error.json,成功时还保存 result.json。缓存回执报告原始用量;失败尝试保留文件供恢复。

第二次回执 · 节选
{
  "ok": true,
  "runId": "deployment-first-task",
  "cached": true
}

读取已保存搜索结果

将 ATTEMPT_DIR 设为上方打印的第二个成功目录,例如 export ATTEMPT_DIR='./deployment-check.ABC123'。以下命令只读取本地文件。

回执与来源链接
# 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"

从部署检查转为定时任务

此检查使用固定运行 ID。定时任务应为每个预期时段设置独立 ID,并保留所选运行环境、账户、输入快照及状态挂载。将定时脚本中的查询命令改为使用 run_flashdata,确保 Docker 任务始终在容器中执行。

通过 GitHub Actions 检查访问

使用可信、持久的 Linux runner,配备 Bash、jq,并在 runner 的系统用户下预先安装 CLI 配置档。将此工作流保存在应用仓库中。它检查宿主机 CLI,不运行付费任务。

  1. 为该 runner 设置 flashdata-research 标签。
  2. 将仓库变量 FLASHDATA_BIN 和 FLASHDATA_STATE_DIR 设为该 runner 上的绝对路径,将 FLASHDATA_PROFILE 设为已安装的配置档名。
.github/workflows/flashdata-check.yml
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)'

运行访问检查

将工作流保存到仓库默认分支后,打开 Actions → FlashData access check → Run workflow。预期输出 true,检查成功。缺少访问或权限时任务失败,不提交搜索。

跨任务保留执行状态

临时 runner 没有原运行日志。付费定时任务应使用持久应用状态或持久 runner。仅重新安装密钥无法识别前一任务的提交。保持状态目录及任务输出私有,不将其上传为 CI 产物。

轮换或撤销部署访问

暂停提交。在任务目录中,将 FLASHDATA_KEY_FILE 指向同一账户、具有所需来源权限的替换密钥,再运行下方命令。重复访问检查及 deployment-check.sh,应返回 cached: true。验证后撤销旧密钥,保留配置档及状态目录。

通过 stdin 替换密钥
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

停止访问

暂停调度器,在控制台撤销密钥或智能体连接,再重复免费访问检查,结果应失败。本地退出不会撤销服务端凭据;已导出文件仍保留在磁盘上。

部署检查失败时

现象修复方法
找不到命令 / CLI 版本有误检查 command -v flashdata 及 runtime.sh 中的 FLASHDATA_BIN。Docker 需重新构建并运行镜像的 --version 检查。
挂载缺失或权限不足在 Docker 主机创建由服务 UID/GID 所有的状态及任务目录,保持路径稳定。
replacement_requires_flag配置档已保存其他密钥。先验证现有访问;需要替换时使用轮换流程。
无法解密保存的访问使用原配置用户及凭据存储环境。新目标环境应单独配置访问,不复制开发机的加密配置档。
费用检查返回 false检查 balance.json 和 preflight.json。提交前需具备可用价格、来源权限及足够余额。
run_account_mismatch检查所选账户和 API 地址,恢复原访问;不要通过更改运行名绕过恢复。
run_id_input_conflict从尝试目录中的 request.json 恢复原请求。仅为明确的新付费任务使用新运行 ID。
CI 一直排队检查 runner 是否在线且具备所有 runs-on 标签。此工作流需要持久的自托管 Linux runner。