# 배포 FlashData 워크로드

Linux 또는 Docker에서 앱 또는 에이전트의 CLI 작업을 실행하고 다시 시작 후 액세스 및 결과 재사용을 확인합니다.

Canonical 참고: https://flashdata.dev/ko/docs/guides/production-deployment
검토: 2026-11-05 FlashData

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

## 1. runtime을 선택하십시오

Bash 및 jq와 함께 Linux 호스트를 사용하며 google_search 권한으로 API 키 소유자. OS 사용자로 설정을 실행하여 작업을 실행합니다. 1–4 단계에 대한이 개인 작업 폴더를 작성; 파일 라벨은 어떤 하위 폴더를 보여줍니다.

### 작업 폴더 만들기

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

### Linux 서버

기본 CLI를 먼저 설치하십시오. 실행 명령 -v flashdata는 절대 경로를 찾을 수 있도록, 다음 FLASHDATA_BIN를 runtime.sh의 경로로 설정. 프로필 이름과 지속 상태 경로를 한 번 여기에 설정 한 다음 파일을 저장합니다.

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

Linux Docker 호스트에서 curl, tar 및 sha256sum, 호스트 CPU에 핀 CLI를 다운로드합니다. 아래 image/Dockerfile 및 image/.dockerignore를 저장하고 이미지를 구축하고 runtime.sh를 저장하십시오. helper는 UID/GID로 실행되며 각 새로운 컨테이너로 국가 및 작업 폴더를 마운트합니다.

#### 다운로드 및 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
```

#### 로컬 이미지 구축 · 필요 자격 없음

```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 릴리스 1.2.1](https://github.com/flashdatadev/flashdata-cli/releases/tag/v1.2.1)
- [Docker 바인드 마운트](https://docs.docker.com/engine/storage/bind-mounts/)

- [기본 CLI 설치](https://flashdata.dev/ko/docs/guides/flashdata-cli/reference.md#install)
- [소유자 키 및 권한](https://flashdata.dev/ko/docs/guides/api-keys-and-permissions/reference.md)

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

### 선택된 실행 시간 확인

작업 폴더에서 실행합니다. run_flashdata는 runtime.sh에 저장 된 돕기입니다. 나중에 명령은 프로필 및 상태 디렉토리를 사용합니다. 그것은 FLASHDATA_API_KEY를 무시하므로 환경 키는 저장된 프로필을 대체 할 수 없습니다. CLI 및 jq 버전 기대.

#### 지속 상태 유지 · 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. 한 번에 소유자 액세스 설치

프로파일이 이미 소유자 액세스가 있다면, 수입을 건너 아래 체크를 실행하십시오. 그렇지 않으면, 서비스 사용자에 의해 읽을 수있는 소유자 키 비밀 파일을 마운트하고 그 위치에 예를 들어 경로를 대체합니다. 수입은 stdin를 통해 그것을 읽습니다; Docker는 이미지를 복사하지 않습니다.

### 배포된 비밀 파일에 포인트

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

### 선택된 실행 시간에서 가져 오기 및 검증

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

- [recurring 사용의 앞에 시험에 찬성하십시오](https://flashdata.dev/ko/docs/guides/agent-onboarding/reference.md#claim)

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

### 계정 및 권한 확인

검사는 계정 ID, 허용된 소스 및 자격 보호, 그 후에 true를 인쇄합니다. 계정을 확인 ID는 계속하기 전에 의도한 소유자입니다. access.json는 검사를 위한 작업 폴더에 체재합니다.

#### Saved 소유자 액세스 · 무료 체크

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

### Credential 스토리지 및 영구 파일

auth status에서 data.credentialProtection를 검사하십시오. Linux는 잠금 해제된 비밀 서비스를 사용할 수 있습니다; 위 헤드리스 호스트 또는 컨테이너는 소유자 전용 일반 텍스트 파일을 사용할 수 있습니다. state 디렉토리를 개인 및 영구 유지하십시오. 배포된 사용자를 노트북의 암호화된 프로필에서 별도로 감독합니다.

| 보관 | 위치 |
| --- | --- |
| Credentials 및 실행 저널 | FLASHDATA_STATE_DIR |
| 입력, 영수증 및 결과 | 작업 폴더; Docker에 /work로 장착. |

- [계획 및 이동 접근](https://flashdata.dev/ko/docs/guides/agent-access/reference.md)

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

## 3. 요청 및 비용 검증

runtime.sh 옆에 request.json를 저장하십시오. 다음의 체크는 재커링 액세스 및 요청을 유효성 검사하고 현재 가격을 읽고 사용 가능한 균형과 비교합니다. 검색을 하지 않고 신용을 예약 하지 않습니다. 필터가 true를 인쇄할 때만 계속하십시오.

### request.json

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

### 첫 번째 유료 작업 전에 확인

```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. 한 번 실행하고 재사용 확인

아래 deployment-check.sh를 저장하십시오. 새로운 배포-First-task 실행 ID, 첫 번째 실행은 하나의 유료 검색을 제출; 두 번째는 새로운 프로세스를 시작하고 저장된 결과를 읽습니다. 이 ID가 이미 동일한 프로파일에서 완료되면 두 시도가 재사용됩니다.


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

### 저장 deployment-check.sh

runtime.sh 및 request.json 외에 deployment-check.sh를 호스트의 개인 작업 폴더에 생성합니다. 아래 전체 스크립트를 복사하여 저장합니다.

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

### 저장된 체크를 두 번 실행하십시오

같은 서비스 사용자와 같은 작업 폴더에서 실행. 두 프로세스는 단계 1에서 저장 runtime.sh를로드합니다.

#### 실행, 다음 프로세스를 다시 시작

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

### 두 번째 영수증을 검증

새로운 실행을 위해, cached: false를 기대, 그 다음 cached: true. 각 시도는 deployment-check.XXXXXX 폴더를 인쇄하고 request.json, receipt.json 및 error.json, result.json를 성공에 저장합니다. 캐시된 영수증은 본래 사용법을 보고합니다. 실패한 시도는 복구에 대한 파일을 유지합니다.

#### 두 번째 영수증 · 발췌

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

- [중단된 실행을 복구](https://flashdata.dev/ko/docs/guides/agent-recovery/reference.md)

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

### 저장된 검색 결과를 읽으십시오

위의 두 번째 성공적인 폴더에 ATTEMPT_DIR를 설정, 예를 들어 내보내기 ATTEMPT_DIR='./deployment-check.ABC123'. 이 명령은 로컬 파일만 읽습니다.

#### 영수증 및 소스 링크

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

### 배포 체크에서 반복 작업으로 이동

이 체크에는 고정 실행 ID가 있습니다. 반복 작업을 위해, 각각의 의도한 발생을 자신의 ID 유지하고 선택한 실행 시간, 계정, 입력 스냅 샷 및 상태 마운트를 유지. run_flashdata를 사용하려면 재커링 러너의 쿼리 명령을 Adapt so Docker 작업은 컨테이너 내부에 유지됩니다.

- [IDs, 영수증 및 스케줄링을 처리](https://flashdata.dev/ko/docs/guides/recurring-tasks/reference.md)

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

## GitHub Actions에서 액세스 확인

Bash, jq 및 CLI 프로필이 이미 런너의 OS 사용자 아래에 설치된 신뢰할 수 있는, 지속적인 Linux 런너를 사용하십시오. 응용 프로그램의 저장소에 이 작업 흐름을 저장합니다. 유료 작업을 실행하지 않고 호스트 CLI를 확인합니다.

1. flashdata-research 레이블을 runner에 할당합니다.
2. 저장소 변수를 설정 FLASHDATA_BIN 및 FLASHDATA_STATE_DIR는 절대 경로에, 그리고 FLASHDATA_PROFILE는 설치 프로필 이름에.

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

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

### 액세스 체크를 실행

저장소의 기본 지점에서 작업 흐름을 저장 한 후, 열린 동작 → FlashData 액세스 체크 → 실행 워크플로우를 엽니다. true 및 성공적인 체크를 기대합니다. 액세스 또는 권한은 검색을 제출하지 않고 작업을 실패.


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

### 업무 전반에 걸쳐 실행 상태를 유지

ephemeral runner는 원래 저널없이 시작합니다. 튼튼한 신청 국가 또는 pay recurring 일을 위한 지속적인 주자 사용하십시오. 키만 제거하면 이전 작업의 제출을 확인할 수 없습니다. state 디렉토리 및 작업 출력을 개인 유지; CI artifacts로 업로드하지 마십시오.


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

## Rotate 또는 revoke 배포된 접근

일시정지. 작업 폴더에서 FLASHDATA_KEY_FILE를 동일한 계정 및 필수 소스에 대한 교체 키에서 포인트로 실행하면 아래 명령을 실행합니다. 액세스 체크 및 deployment-check.sh를 반복; cached: true를 기대합니다. 검증 후 오래된 키를 다시하고 프로필 및 상태 디렉토리를 유지하십시오.

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

- [API 키 관리](https://flashdata.dev/ko/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Connected apps](https://flashdata.dev/app/settings/connections)

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

### 접속을 완전히 멈추십시오

스케줄러를 일시 중지, 콘솔의 키 또는 에이전트 연결을 수정, 다음 무료 액세스 체크를 반복. 실패해야 합니다. 로컬 로그 아웃은 서버 자격 증명을 수정하지 않습니다. 이미 파일을 디스크에 남아 있습니다.


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

## 실패한 수정 체크

| 학회소개 | 해결 |
| --- | --- |
| 명령을 찾을 수 없습니다 / 잘못된 CLI 버전 | runtime.sh에서 명령 -v flashdata 및 FLASHDATA_BIN를 확인하십시오. Docker의 경우, 이미지를 다시 만들고 --version 체크를 실행합니다. |
| 마운트 또는 권한 거부 | Docker 호스트의 상태 및 작업 폴더를 생성, 서비스 UID/GID. 소유 안정된 길을 유지하십시오. |
| replacement_requires_flag | 프로필에는 다른 저장된 키가 있습니다. 기존의 액세스를 먼저 검증; 목적의 교체 절차를 사용합니다. |
| 저장된 접근을 해독할 수 없습니다 | 동일한 자격 증명 환경에서 그것을 제공 한 사용자로 실행하십시오. 암호화 된 노트북 프로파일을 복사 대신 새로운 목적지에 대한 Provision 액세스. |
| false를 반환하는 비용 검사 | balance.json 및 preflight.json를 검사하십시오. 제출하기 전에 사용 가능한 가격, 소스 권한 및 충분한 균형이 필요합니다. |
| run_account_mismatch | 선택된 계정과 API 원산지를 확인하십시오. 원래의 액세스를 복원; 우회 복구에 실행 이름을 변경하지 마십시오. |
| run_id_input_conflict | 시도의 request.json에서 원래 요청을 복원합니다. 새로운 유료 작업을 위해 ID 만 새로운 실행을 사용합니다. |
| CI는 | 런너가 온라인이며 모든 실행 라벨이 있습니다. 이 워크플로우는 지속적인 자체 호스팅 Linux 런너가 필요합니다. |

- [저장된 실행을 복구](https://flashdata.dev/ko/docs/guides/agent-recovery/reference.md)
