Docs / Reference / نصب و اجرا از باینری از‌پیش‌ساخته‌شده
Documentation

نصب و اجرا از باینری از‌پیش‌ساخته‌شده

<div dir="rtl" lang="fa">

6 min read Updated Jun 4, 2026 Source Edit History
linivek devwithmj

نصب و اجرا از باینری از‌پیش‌ساخته‌شده#

برای وقتی که فقط باینری opendray را می‌خواهید — بدون wizard نصب‌کننده که دست به تنظیمات ماشین شما بزند. این مسیر مناسب است برای:

  • npm install -g opendray / npx opendray — پکیج npm باینری رسمی Go release را شامل می‌شود (ببینید README → npm / npx).
  • دانلود Release — فایل opendray_*_<os>_<arch>.tar.gz را از صفحه Releases بردارید.
  • محیط‌های scripted / ephemeral — CI runnerها، golden imageها، config management (Ansible، Nix، Docker)، یا هر hostی که Postgres و process supervisor خودتان را دارید.

باینری همان کل gateway است — web admin SPA داخلش embed شده، پس نه Node runtime لازم است، نه static server جداگانه، و نه چیزی برای build کردن. آنچه نمی‌کند این است که چیزی را برای شما setup نکند. این همان معامله است: شما یک دیتابیس PostgreSQL و روشی برای نگه‌داشتن فرایند می‌آورید، و در عوض هیچ‌چیزی بدون اطلاع شما نصب، تنظیم، یا ثبت نمی‌شود.

می‌خواهید همه‌چیز برایتان انجام شود؟ روی یک Linux / macOS تازه، installer تک‌خطی Postgres را provision می‌کند، AI CLIها را نصب می‌کند، config را می‌نویسد، و یک service را در ۵ تا ۱۰ دقیقه ثبت می‌کند. ببینید README → نصب‌کننده تک‌خطی یا راهنمای دستی getting-started.fa.md.

این راهنما شما را از «باینری روی PATH» به «gateway در حال اجرا» در پنج گام می‌رساند، سپس نشان می‌دهد چطور آن را به‌صورت یک service اجرا کنید.

گام ۱ — باینری را بگیرید#

از طریق npm (هر OS با Node ≥ 18)#

[object Promise]

باینری پلتفرم متناظر (opendray-{linux,darwin}-{x64,arm64}) به‌صورت خودکار از طریق optionalDependencies انتخاب می‌شود — هیچ postinstall hookی وجود ندارد و هیچ network call هنگام نصب زده نمی‌شود. از دادن --no-optional خودداری کنید: این پکیج پلتفرم را رد می‌کند و launcher را بدون باینری‌ای که exec کند رها می‌کند.

از طریق آرشیو release#

[object Promise]

تأیید#

[object Promise]

پلتفرم‌های پشتیبانی‌شده: Linux (x64, arm64) و macOS (x64, arm64). Windows بومی بسته‌بندی نشده — از WSL2 استفاده کنید و مسیر Linux را دنبال کنید.

گام ۲ — PostgreSQL 15+ با pgvector را فراهم کنید#

opendray همه‌چیز (سشن‌ها، حافظه، audit log) را در PostgreSQL ذخیره می‌کند، و زیرسیستم حافظه‌اش به extension pgvector نیاز دارد. نسخه‌های server پشتیبانی‌شده: 15، 16، 17.

اگر از قبل Postgres دارید، یک دیتابیس و یک نقش CRUD-only بسازید، سپس extension را یک بار با superuser فعال کنید:

[object Promise]

وقتی extension موجود باشد، نقش CRUD-only opendray بدون هیچ دسترسی superuser بیشتری migration اجرا می‌کند. هرگز opendray را به یک نقش superuser در زمان اجرا وصل نکنید — به آن یک حساب scoped به پروژه بدهید و رمز عبورش را جداگانه rotate کنید.

گام ۳ — تنظیم کنید#

opendray config خود را از یک فایل TOML یا صرفاً از متغیرهای محیط (12-factor) می‌خواند — env همیشه بر فایل ارجحیت دارد. تنها نیاز اجباری database URL است؛ بقیه مقادیر پیش‌فرض دارند.

گزینه الف — متغیرهای محیط (مناسب برای containerها / hostهای ephemeral)#

[object Promise]
متغیر اجباری پیش‌فرض هدف
OPENDRAY_DATABASE_URL بله — Postgres DSN
OPENDRAY_ADMIN_PASSWORD توصیه می‌شود — رمز ادمین وب/موبایل
OPENDRAY_ADMIN_USER خیر admin نام کاربری ادمین
OPENDRAY_LISTEN خیر 127.0.0.1:8770 آدرس bind
OPENDRAY_LOG_LEVEL خیر info debug/info/warn/error
OPENDRAY_LOG_FORMAT خیر text text/json

opendray serve را بدون flag مربوط به -config اجرا کنید و کاملاً از محیط بارگذاری می‌شود.

گزینه ب — config.toml#

[object Promise]

حداقل چیزی که باید ویرایش کنید:

[object Promise]

فایل کاملاً annotated را در config.example.toml ببینید (logging، session idle detection، backupها، vault، MCP). آن را با -config config.toml به دستورات زیر بدهید. secretها را روی hostهای shared داخل TOML نگذارید — OPENDRAY_DATABASE_URL / OPENDRAY_ADMIN_PASSWORD را از طریق env تنظیم کنید و فایل را non-secret نگه دارید.

گام ۴ — schema را اعمال کنید#

[object Promise]

Idempotent است — اجرای مجدد وقتی schema جاری است no-op می‌شود. این باید قبل از اولین serve با موفقیت اجرا شود.

گام ۵ — اجرا کنید#

[object Promise]

این در foreground اجرا می‌شود (Ctrl-C آن را متوقف می‌کند). حالا باید داشته باشید:

آدرس کاربرد
http://127.0.0.1:8770/admin/ ادمین وب — با admin + رمز عبورتان وارد شوید
http://127.0.0.1:8770/api/v1/... REST + WebSocket API

این یک gateway کامل و در حال اجرا است. برای هر چیزی فراتر از یک تست سریع، آن را زیر یک supervisor اجرا کنید تا از reboots جان سالم به در ببرد و در صورت crash دوباره راه‌اندازی شود — ادامه می‌دهیم.

اجرا به‌عنوان service#

opendray serve دقیقاً همان دستوری است که start command یک service unit باید فراخوانی کند. opendray unitهای hardened و آماده‌به‌استفاده ارائه می‌کند؛ مراحل زیر همان README → انتشار عملیاتی است که مرجع اصلی است (bootstrap کامل، نکات sandboxing، reverse-proxy/TLS).

Linux — systemd#

این repo یک unit hardened در deploy/systemd/opendray.service ارائه می‌کند (اجرای migrate به‌عنوان ExecStartPre، secretها از طریق EnvironmentFile، restart با on-failure، syscall/filesystem sandboxing).

[object Promise]

systemd ندارید؟ (LXC بدون آن، OpenRC، runit، s6، supervisord…) supervisor خودتان را به opendray serve -config /etc/opendray/config.toml اشاره دهید و opendray migrate را یک بار به‌عنوان pre-start step اجرا کنید. ببینید README → انتشار عملیاتی §B.

macOS — launchd#

این repo یک LaunchDaemon در deploy/launchd/com.opendray.opendray.plist ارائه می‌کند (در boot شروع می‌شود، در صورت crash دوباره راه‌اندازی می‌شود، در /usr/local/var/log/opendray/ لاگ می‌نویسد).

[object Promise]

Restart: sudo launchctl kickstart -k system/com.opendray.opendray. Unload: sudo launchctl bootout system/com.opendray.opendray.

هر دو unit به‌طور کامل — شامل چیدمان secretها و دلیل خاموش گذاشتن MemoryDenyWriteExecute — در deploy/README.md مستند شده‌اند.

به‌روز نگه داشتن#

نحوه به‌روزرسانی به روش نصب بستگی دارد:

  • از طریق npm نصب شده — با package manager خود به‌روز کنید. opendray update باینری را داخل node_modules پشت npm جایگزین می‌کند و با اجرای بعدی install بازنویسی می‌شود؛ پس اینجا از آن استفاده نکنید.
[object Promise]
  • دانلود release / نصب wizard — باینری خودش را in-place به‌روز می‌کند (آخرین release را دانلود می‌کند، SHA-256 آن را تأیید می‌کند، به‌صورت atomic خودش را swap می‌کند):
[object Promise]

عیب‌یابی#

the matching platform package "opendray-…" was not installed npm با --no-optional اجرا شده، یا نصب قطع شده است. npm install -g opendray را دوباره اجرا کنید (بدون --no-optional).

unsupported platform پکیج npm فقط Linux/macOS روی x64/arm64 را پوشش می‌دهد. روی targetهای دیگر، از source بسازید — ببینید quickstart.md.

config: database.url is empty نه OPENDRAY_DATABASE_URL و نه [database].url تنظیم نشده‌اند. یکی را تنظیم کنید (گام ۳).

connection refused هنگام migrate/serve Postgres اجرا نمی‌شود یا DSN اشتباه است. مطمئن شوید server up است و host/port/credentials داخل DSN شما درست هستند.

pgvector / extension "vector" is not available Extension روی server نصب نشده، یا داخل دیتابیس opendray فعال نشده است. گام ۲ را دوباره انجام دهید (پکیج OS را نصب کنید، سپس CREATE EXTENSION vector را به‌عنوان superuser اجرا کنید).

Port در حال استفاده است OPENDRAY_LISTEN (یا listen در config.toml) را به یک port آزاد تغییر دهید.

گام‌های بعدی#