سناریوی رخداد

پایگاه داده‌ی فقط‌خواندنی روی یک مانت خواندنی-نوشتنی

A read-only database on a read-write mount

  • سطح ۳: ارشد
  • سناریوی رخداد
  • ۲۵ دقیقه

وضعیت

تیمی ایجنت کدنویسی خود را با فلگ --sandbox اجرا می‌کند تا ابزارهای shell و filesystem آن درون یک microVM کار کنند، در حالی که مدل روی هاست باقی می‌ماند. نخستین اجرای ساندباکس‌شده روی مکِ یکی از توسعه‌دهندگان، خلاصه‌ی راه‌اندازی را چاپ می‌کند، ایمیج قالب (template image) را دریافت می‌کند، ساندباکس را می‌سازد و پیش از آنکه ایجنت پاسخی بدهد با کد خروج 1 خارج می‌شود. متن خطا به ذخیره‌ساز نشست (session store) اشاره دارد: مایگریشن (migration) آن نتوانسته جدولی بسازد، چرا که پایگاه داده فقط‌خواندنی بوده است. وضعیت ساندباکس هنوز در حال اجرا گزارش می‌شود.

تیم در کانال گفتگو به سه دسته تقسیم می‌شود. یک مهندس می‌گوید ایمیج قالب خراب است و می‌خواهد یک تگ قدیمی‌تر را پین کند. دیگری می‌گوید فضای کاری (workspace) حتماً اشتباهی به‌صورت فقط‌خواندنی مانت شده است. سومی می‌گوید SQLite روی سیستم مهمان (guest) نصب نیست. پیش از تلاش دوم، توسعه‌دهنده خروجی راه‌اندازی، اجرای دوم با پوشه‌های وضعیت (state directories) پیش‌فرض و یک شل داخل VM در حال اجرا را در اختیارتان می‌گذارد.

نسخه
sbx v0.47.0 and docker-agent v1.149.0 on the host, with the main build of docker-agent inside the template
مدل
none; the run stopped before its first model call
سخت‌افزار
one Mac with the microVM runtime

شواهد

a-data-directory-outside-the-workspace.txt
title: the same run with the state directories at their defaults
source: manuals/docker-sandboxes-101/capture/out/27-data-dir-outside.txt
lang: console
note: One line names the rule for the data directory.
---
$ docker-agent run --sandbox --exec --working-dir fixtures/repo-sandbox fixtures/agents/files-sandbox.yaml 'List the files in the working directory and count the lines of README.md.'
Error: --data-dir must be inside the sandbox's writable workspace $CAPTURE/fixtures/repo-sandbox
[exit 1]
a-sqlite-write-and-the-mounts.txt
title: a plain SQLite write inside the VM, then the mounts of the workspace
source: manuals/docker-sandboxes-101/capture/out/27-sqlite-probe.txt
lang: console
note: Compare the error with the mode letters of the first mount.
---
$ sbx exec docker-agent-<hash> sh -c 'cd "$PWD" && mkdir -p .m101/probe && python3 -c '"'"'import sqlite3; c = sqlite3.connect(".m101/probe/x.db"); c.execute("create table t(a)"); c.execute("insert into t values (1)"); c.commit(); print("sqlite write ok")'"'"' 2>&1 | tail -1; mount | grep repo-sandbox'
sqlite3.OperationalError: attempt to write a readonly database
host on $CAPTURE/fixtures/repo-sandbox type virtiofs (rw,nosuid,nodev,relatime)
host on $CAPTURE/fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash> type virtiofs (ro,nosuid,nodev,relatime)
host on $CAPTURE/fixtures/repo-sandbox/.m101/cfg type virtiofs (ro,nosuid,nodev,relatime)
[exit 0]
the-agent-binary-inside.txt
title: the version of the agent binary inside the VM
source: manuals/docker-sandboxes-101/capture/out/27-inside.txt
lines: 1-3
lang: console
note: The template does not run the release that the host runs.
---
$ sbx exec docker-agent-<hash> sh -c 'docker-agent version; echo; env | grep -iE '"'"'proxy|gateway|models|safety|yolo'"'"' | sort; echo; docker-agent sandbox list'
docker-agent version main
Commit: 154b78f2d517dae1397866dfb7586c4a302a3151
the-command-and-its-mounts.txt
title: the sandboxed run, its state flags and the launch summary
source: manuals/docker-sandboxes-101/capture/out/27-sandbox-run.txt
lines: 1-15
lang: console
note: Read the note after the command for where the three state directories sit, then the four workspace lines and their modes.
---
$ docker-agent run --sandbox --exec --working-dir fixtures/repo-sandbox fixtures/agents/files-sandbox.yaml 'List the files in the working directory and count the lines of README.md.'  (--config-dir, --data-dir, --cache-dir under fixtures/repo-sandbox/.m101, inside the workspace)
Models gateway: none configured
Models catalog: allowlisting models.dev in the sandbox proxy
User sandbox allowlist: allowlisting 1 host(s) from `docker agent sandbox allow`:
  - localhost:12434

sandbox    docker-agent-<hash>
agent      docker-agent
workspace  $CAPTURE/fixtures/repo-sandbox (rw)
           $CAPTURE/fixtures/agents (ro)
           $CAPTURE/fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash> (ro)
           $CAPTURE/fixtures/repo-sandbox/.m101/cfg (ro)
image      docker/docker-agent-sbx-templates:latest
cpu        10
memory     32 GiB
the-error-that-ended-the-run.txt
title: the last five lines of the sandboxed run
source: manuals/docker-sandboxes-101/capture/out/27-sandbox-run.txt
lines: 24-28
lang: console
note: The run ends at the session store, before any model call.
---
<ts> WARN Self-update skipped; continuing with current binary error="current version \"main\" is not a release version: invalid semantic version"
docker-agent: self-update failed (current version "main" is not a release version: invalid semantic version); continuing with current version
Error: creating session store: migration failed even after database reset: failed to create migrations table: attempt to write a readonly database (1032)
Error: 
[exit 1]
the-run-that-worked-inside.txt
title: the same agent file started by hand inside the VM
source: manuals/docker-sandboxes-101/capture/out/27-inside-run.txt
lang: console
note: Read the three state flags in the command, then the answer.
---
$ sbx exec docker-agent-<hash> sh -c 'docker-agent --config-dir /tmp/m101 --data-dir /tmp/m101 --cache-dir /tmp/m101 run --exec --last --working-dir $CAPTURE/fixtures/repo-sandbox $CAPTURE/fixtures/agents/files-sandbox.yaml '"'"'List the files in the working directory and count the lines of README.md.'"'"''
<ts> WARN Self-update skipped; continuing with current binary error="current version \"main\" is not a release version: invalid semantic version"
docker-agent: self-update failed (current version "main" is not a release version: invalid semantic version); continuing with current version
The working directory contains README.md with 1 line.
[exit 0]
what-the-staged-kit-holds.txt
title: the auto-kit that docker-agent staged under the workspace
source: manuals/docker-sandboxes-101/capture/out/27-kit-cache.txt
lang: console
note: The manifest has two fields and nothing about a database.
---
$ find fixtures/repo-sandbox/.m101/cache/sandbox-kits -maxdepth 3 | sort
fixtures/repo-sandbox/.m101/cache/sandbox-kits
fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash>
fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash>/manifest.json
fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash>/prompt_files
fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash>/skills

$ cat fixtures/repo-sandbox/.m101/cache/sandbox-kits/<hash>/manifest.json
{
  "agent_ref": "$CAPTURE/fixtures/agents/files-sandbox.yaml",
  "built_at": "<ts>"
}

سؤال‌ها

  1. پوشه‌ی داده (data directory) کجا قرار داشت و روی کدام مانت بود؟
  2. در خلاصه، سه مانت به‌صورت فقط‌خواندنی آمده‌اند. آیا هیچ‌کدام علت خطا را توضیح می‌دهند؟
  3. آزمون ارزیابی (probe) با SQLite چه چیزی را نشان می‌دهد که در پیام خطا نیست؟
  4. چرا اجرای دوم پیش از ساخت هر چیزی شکست خورد؟
  5. آخرین گزارش مربوط به اجرایی است که کامل شده. این اجرا چه چیزی را ثابت می‌کند و چه چیزی را ثابت نمی‌کند؟
  6. امروز چگونه این ایجنت را در ساندباکس روی این هاست اجرا می‌کردید و چه مواردی را گزارش می‌کردید؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. ابتدا فلگ‌های وضعیت را بررسی کنید. یادداشت پس از دستور می‌گوید که پوشه‌های پیکربندی، داده و کش زیر مسیر .m101/ داخل فضای کاری قرار دارند. خطا از ذخیره‌ساز نشست می‌آید که در پوشه‌ی داده قرار دارد؛ بنابراین فایل پایگاه داده روی مانتِ فضای کاری است.
  2. چهار خط مربوط به فضای کاری را بخوانید. فضای کاری به‌صورت (rw) است. پوشه‌ی فایل‌های ایجنت، کیت مستقرشده زیر مسیر .m101/cache/sandbox-kits/<hash> و مسیر .m101/cfg همگی (ro) هستند. پوشه‌ی داده هیچ‌کدام از این سه مسیر نیست؛ پس حالت‌های مانت علت شکست را توضیح نمی‌دهند.
  3. با آزمون ارزیابی، احتمال مشکل از فلگ‌های مانت را رد کنید. داخل VM، یک نوشتن ساده با کتابخانه‌ی پایتونی sqlite3 زیر مسیر .m101/probe/ با همان پیام attempt to write a readonly database شکست می‌خورد. جدول مانت در خطوط پایینی، فضای کاری را یک مانت virtiofs با دسترسی rw نشان می‌دهد. کرنل (kernel) مانت را قابل نوشتن گزارش می‌کند، اما با این حال SQLite نمی‌تواند پایگاه داده‌ای روی آن بنویسد. مشکل بین SQLite و این مانت است، نه در تنظیمات ساندباکس و نه از نبود پکیج؛ چرا که آزمون ارزیابی توانست sqlite3 را ایمپورت کند و بدون خطا به آن متصل شود.
  4. ببینید چرا مقادیر پیش‌فرض راه نجاتی نیستند. اجرای برنامه با پوشه‌های وضعیت پیش‌فرض، پیش از آنکه اصلاً ساندباکسی بسازد رد شد: مسیر --data-dir باید حتماً داخل فضای کاری قابل نوشتن باشد. بنابراین لانچر پایگاه داده را به همان مانتی تحمیل می‌کند که روی این هاست، SQLite نمی‌تواند روی آن بنویسد.
  5. کیت مستقرشده را از ذخیره‌ساز نشست جدا کنید. کیت خودکار مستقرشده شامل یک manifest.json با فیلدهای agent_ref و built_at، به‌همراه prompt_files و skills است. هیچ بخشی از آن پایگاه داده‌ای را پیکربندی نمی‌کند. ایمیج قالب از نسخه‌ی docker-agent version main استفاده می‌کند، نه نسخه‌ی رسمی و پایداری که روی هاست اجرا می‌شود؛ بنابراین تگ ایمیج دومین یافته‌ای است که باید ثبت شود. با این حال، چون آزمون ارزیابی برای هر برنامه‌ای شکست می‌خورد، بیلد متفاوتی از ایجنت هم نتیجه را تغییر نمی‌داد.
  6. مسیر ارتباط با مدل را با اجرای دستی اثبات کنید. وقتی همان فایل ایجنت داخل VM با سه پوشه‌ی وضعیت خود در /tmp/m101 (سیستم فایل خود مهمان و نه یک مانت) اجرا شد، با کد خروج 0 پاسخ داد: فایل README تنها 1 خط دارد. ارائه‌دهنده‌ی مدل روی host.docker.internal:12434 نیز از طریق پروکسی در دسترس بود. پس مسیر مدل، فهرست مجاز (allowlist) و فایل ایجنت همگی درست کار می‌کنند؛ تنها محل ذخیره‌ساز نشست است که با مشکل مواجه می‌شود.
نتیجه

ذخیره‌ساز نشست نتوانست بنویسد زیرا SQLite روی این هاست نمی‌تواند از طریق مانت فضای کاری virtiofs روی پایگاه داده بنویسد، هرچند mount آن را به‌صورت rw نشان می‌دهد. لانچر الزام دارد که پوشه‌ی داده حتماً درون آن فضای کاری باشد، بنابراین اجرای --sandbox هیچ محل پشتیبانی‌شده‌ای برای ذخیره‌ساز روی این سیستم ندارد. خود ساندباکس کار می‌کرد: اجرایی که به‌صورت دستی درون VM با پوشه‌ی وضعیت در /tmp/m101 انجام شد با پاسخ درست به پایان رسید و همان فایل ایجنت از طریق پروکسی به مدل متصل شد.

اقدامات لازم:

  1. روی هر هاست جدید، پیش از استفاده از لانچر با فلگ --sandbox، نوشتن SQLite درون فضای کاری را از داخل شلِ VM تست کنید؛ همان‌طور که در چک‌لیست راهنما آمده است.
  2. تا زمان تغییر قاعده‌ی پوشه‌ی داده، ایجنت را دستی از داخل VM با sbx exec اجرا کنید، به‌طوری که --data-dir روی سیستم فایل مهمان قرار گیرد؛ و لانچر هاست را برای سیستم‌هایی نگه دارید که آزمون ارزیابی روی آن‌ها موفق است.
  3. پس از پایان کار ساندباکس را با sbx rm حذف کنید، چون لانچر بعد از بروز خطا آن را در حال اجرا رها می‌کند.
  4. دو تیکت باز ثبت کنید: اول اینکه قالب به‌جای نسخه‌ی پین‌شده از بیلد main استفاده می‌کند، و دوم اینکه اجرا هیچ حالت امنیتی‌ای (safety mode) را چاپ نکرده است؛ در نتیجه حالت مورداستفاده در اجرای ساندباکس‌شده نامشخص می‌ماند که تعارض C62 در راهنماست.
مسیرهای اشتباه رایج
  • «فضای کاری فقط‌خواندنی مانت شده بود.» خلاصه آن را rw نشان می‌دهد و جدول مانت درون VM هم همین را تأیید می‌کند. سه مانتِ فقط‌خواندنی شامل پوشه‌ی فایل ایجنت، کیت مستقرشده و پوشه‌ی پیکربندی هستند و پایگاه داده زیرمجموعه‌ی هیچ‌کدام از آن‌ها نیست.
  • «تگ قالب قدیمی‌تری را پین کنید.» آزمون ارزیابی حتی برای یک اسکریپت ساده‌ی پایتون بدون حضور ایجنت هم شکست می‌خورد؛ بنابراین بیلد ایجنت علت ماجرا نیست. استفاده از بیلد main ارزش ثبت تیکت را دارد، اما مشکل را حل نمی‌کند.
  • «پوشه‌ی داده را به مقدار پیش‌فرض هاست منتقل کنید.» لانچر پیش از ساخت هر چیزی، پوشه‌ی داده‌ی خارج از فضای کاریِ قابل نوشتن را رد می‌کند.
  • «SQLite روی سیستم مهمان نصب نیست.» آزمون ارزیابی ماژول را ایمپورت کرد و پایگاه داده را باز کرد. خطا صرفاً هنگام نخستین نوشتن رخ داد.
درس کلی

وقتی برنامه‌ای روی مسیری که سیستم آن را قابل نوشتن اعلام کرده خطای دسترسی می‌دهد، همان عملیات را با کوچک‌ترین برنامه‌ی ممکن، خارج از محصول و روی همان مسیر تکرار کنید. اگر آنجا هم شکست بخورد، مشکل از تنظیمات محصول نیست و به لایه‌ی زیرین آن برمی‌گردد؛ و اگر موفق شود، مشکل به خود محصول محدود است. سپس بررسی کنید که آیا محصول راهی برای دور زدن آن لایه در اختیارتان می‌گذارد یا خیر؛ اگر راهی نبود، قاعده‌ی دقیقی را که مانع شما شده است یادداشت کنید.

کجای دوره آموزش داده می‌شود

بخش اجرای سرتاسری در راهنما این خطا و آزمون ارزیابی را ثبت کرده است، صفحه‌ی run فلگ‌های وضعیت را توضیح می‌دهد، و دفتر ثبت تعارض‌ها تعارض C62 را باز نگه می‌دارد.