浏览文档
指南
在 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 — 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"
}在安装了 curl、tar 和 sha256sum 的 Linux Docker 主机上,按主机 CPU 下载固定版本 CLI。保存下方 image/Dockerfile 和 image/.dockerignore,构建镜像后再保存 runtime.sh。辅助函数以当前 UID/GID 运行,并为每个新容器挂载状态及任务目录。
(
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
}检查所选运行环境
在任务目录运行。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 --version2. 一次性安装所有者访问
若配置档已有所有者访问,跳过导入,直接执行下方检查。否则,挂载服务用户可读的所有者密钥文件,并将示例路径替换为其位置。导入通过 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 后继续。
{
"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. 运行一次并验证复用
保存下方 deployment-check.sh。deployment-first-task 为新运行 ID 时,第一次执行提交一次付费搜索;第二次启动新进程读取保存结果。若同一配置档中此 ID 已完成,两次尝试都会复用结果。
保存 deployment-check.sh
在主机的私有任务目录中、runtime.sh 和 request.json 旁创建 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,不运行付费任务。
- 为该 runner 设置 flashdata-research 标签。
- 将仓库变量 FLASHDATA_BIN 和 FLASHDATA_STATE_DIR 设为该 runner 上的绝对路径,将 FLASHDATA_PROFILE 设为已安装的配置档名。
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。验证后撤销旧密钥,保留配置档及状态目录。
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。 |