Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

11.9 KB
Raw Blame

SQLite Runtime Resolution (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW


OmniRoute در زمان راهاندازی، درایور SQLite خود را از طریق یک زنجیرهٔ بازگشتی ۵ مرحلهای پیدا میکند:

  1. better-sqlite3 همراه بسته (از طریق dependencies در package.json) — سریعترین گزینه، دارای باینری بومی، که وقتی ابزارهای ساخت موجود باشند با npm install نصب میشود.

  2. better-sqlite3 نصبشده در زمان اجرا (در ~/.omniroute/runtime/) — در اولین اجرا بهصورت تنبل نصب میشود یا توسط scripts/build/postinstall.mjs → scripts/postinstall.mjs. پیش از بارگذاری، بایتهای جادویی فایل بومی .node ‏(ELF / Mach-O / PE) را اعتبارسنجی میکند تا از بارگذاری باینریهای خراب یا متعلق به پلتفرم اشتباه جلوگیری شود.

  3. node:sqlite (کتابخانهٔ استاندارد Node ≥22.5) — به ساخت بومی نیاز ندارد؛ زمانی استفاده میشود که هر دو مسیر better-sqlite3 ناموفق باشند. مجموعه قابلیتهای محدودی دارد.

  4. sql.js (WASM) — آخرین گزینهٔ جایگزین. همهجا کار میکند، اما کندتر است و دادهها را بهجای نوشتن همگام، در بازههای زمانی مشخص مینویسد.

دلیل این پیچیدگی چیست؟

  • EBUSY در Windows: اگر better_sqlite3.node نسخهٔ قبلی توسط یک فرایند در حال اجرا قفل شده باشد، ممکن است npm install -g omniroute@latest ناموفق شود. نصب در زمان اجرا در ~/.omniroute/runtime/ حافظهٔ نهان سراسری npm را دور میزند.
  • نبود ابزارهای ساخت: بعضی محیطها (Windows سازمانی بدون VS Build Tools، ایمیجهای حداقلی Docker) نمیتوانند better-sqlite3 را کامپایل کنند. نصبکنندهٔ زمان اجرا یک باینری ازپیشساختهشده را از رجیستری npm دریافت میکند؛ درایورهای جایگزین تضمین میکنند که OmniRoute حتی در صورت شکست آن نیز راهاندازی شود.
  • سامانههای جدا از شبکه: اگر رجیستری npm در دسترس نباشد، node:sqlite یا sql.js قابلیتهای پایه را تضمین میکنند.

اعتبارسنجی بایتهای جادویی

پیش از بارگذاری فایل .node نصبشده در زمان اجرا، OmniRoute نخستین ۸ بایت را میخواند و با امضاهای جادویی شناختهشدهٔ پلتفرمها مطابقت میدهد:

پلتفرم بایتها (هگز) برچسب
Linux 7F 45 4C 46 elf
macOS ‏۶۴بیتی BE FE ED FA CF macho
macOS ‏۶۴بیتی LE CF FA ED FE macho-le
macOS چندمعماری (universal) CA FE BA BE macho-fat
Windows 4D 5A (MZ) pe

امضای جادویی نامطابق ← فایل نادیده گرفته میشود و فرایند جایگزینی به مرحلهٔ بعدی ادامه مییابد.

بررسی درایور فعال

import { getDriverInfo } from "@/lib/db/core";

const info = getDriverInfo();
// { source: "bundled" | "runtime" | "runtime-installed-now" | "node-sqlite" | "sql-js",
//   kind: "better-sqlite3" | "node-sqlite" | "sql-js" }

کنترل دستی

# رد کردن آمادهسازی postinstall برای نصبهای سریع CI
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute

# نصب اجباری و مجدد better-sqlite3 زمان اجرا
rm -rf ~/.omniroute/runtime
omniroute  # در راهاندازی بعدی دوباره نصب خواهد شد

# بررسی درایور فعال
omniroute config db-info  # اگر فرمان CLI وجود داشته باشد

تشخیص توقفهای همگام

هنگام استفاده از better-sqlite3، پیش از راهاندازی مقدار OMNIROUTE_SQLITE_SLOW_MS=200 را تنظیم کنید تا زمانسنجی آداپتور همگام فعال شود. این قابلیت بهطور پیشفرض غیرفعال است. هر عملیات تکمیلشدهای که حداقل به همان تعداد میلیثانیه زمان نیاز داشته باشد، یک هشدار [SQLITE-SLOW] صادر میکند؛ حداکثر یکبار در هر ده ثانیه برای هر آداپتور. این هشدار فقط شامل درایور، دستهٔ عملیات (prepare، get، all، run، exec، pragma، تراکنش یا نگهداری) و زمان سپریشده برحسب میلیثانیه است: بدون SQL، مقادیر مقیدشده، ردیفها، مسیرها یا متن استثنا.

این یک ابزار تشخیصی است، نه مهلت زمانی یا بهینهسازی کوئری. این ابزار نمیتواند عملیاتی را که هرگز بازنمیگردد گزارش کند، پردازش CPU را از انتظارهای دیسک تشخیص دهد، SQL دقیق را شناسایی کند یا عملیاتی را که از طریق هندل خام درایور انجام میشود مشاهده کند. مدتزمان پشتیبانگیری ناهمگام عمداً مستثنا شده است؛ سایر درایورهای SQLite نیز توسط این قابلیت اختیاری ابزارگذاری نمیشوند. غیرفعالکردن متغیر، آداپتور اصلی را بدون پوششهای زمانسنجی بازمیگرداند. هیچ تغییری در شِمای پایگاه داده یا پیکربندی ذخیرهشده ایجاد نمیشود.

هشدار تأخیر /healthz بیشینهٔ تأخیر حلقهٔ رویداد از زمان نمونهبرداری قبلی را گزارش میکند، نه میانگین کل دورهٔ اجرا را. پیش از نسبتدادن یک توقف به SQLite یا خرابی دیسک، مُهرهای زمانی آن را با هشدارهای عملیات کند و معیارهای میزبان/فضای ذخیرهسازی تطبیق دهید.

مرجع

پیادهسازی:

  • bin/cli/runtime/magicBytes.mjs — توابع کمکی اعتبارسنجی بایتهای جادویی باینری
  • bin/cli/runtime/sqliteRuntime.mjs — حلکنندهٔ ۵ مرحلهای زمان اجرا + نصبکنندهٔ تنبل
  • bin/cli/runtime/index.mjs — هماهنگکنندهٔ راهاندازی (warmUpRuntimes())
  • scripts/postinstall.mjs — هوک پسازنصب npm (آمادهسازی غیرکشنده)
  • src/lib/db/core.ts — خروجیهای ensureDbInitialized() / getDriverInfo()

توپولوژی تکنویسندهای (HA پشتیبانی نمیشود)

زنجیرهٔ جایگزینی درایور در بالا همچنان در یک فرایند اجرا میشود. SQLite پیشفرض در OmniRoute یک تکنویسنده است:

  • دو نمونهٔ تکراری OmniRoute را به یک فایل storage.sqlite متصل نکنید.
  • راهاندازی مجدد کانتینر، استقرار Recreate، توقف ناشی از OOM یا راهاندازی مجدد HEALTHCHECK تمام نشستهای SSE در حال اجرا را قطع میکند. در مسیر استاندارد، تخلیهٔ نشست وجود ندارد.
  • اگر بررسی زندهبودن ارکستریتور، پاسخ کند /healthz را بهمعنای ازکارافتادگی تلقی کند، تنها نمونهٔ تکراری را متوقف خواهد کرد. بررسی زندهبودن TCP بههمراه بررسی آمادگی HTTP در /healthz را ترجیح دهید. به راهنمای Docker — دسترسپذیری و توصیههای پروب Kubernetes مراجعه کنید.