خط فرمان و پوشهٔ داده‌ها

این صفحه گزینه‌ها و متغیرهای محیطی Throne بدون رابط گرافیکی، محل نگهداری داده‌هایش، نحوهٔ راه‌اندازی دوباره‌اش و معنای کدهای خروجش را فهرست می‌کند. برای گزینه‌های خط فرمان برنامهٔ دسکتاپ، خط فرمان را ببینید.

گزینه‌ها و متغیرها

Throne --headless --help گزینه‌ها را فهرست می‌کند. یک یا دو خط تیره هر دو کار می‌کنند (-data-dir همان --data-dir است)، و مقدار پس از یک فاصله یا = می‌آید. گزینه بر متغیر متناظرش اولویت دارد. متغیری که مقدار خالی داشته باشد تنظیم‌نشده به حساب می‌آید، به‌جز THRONE_API_ALLOW.

گزینه	متغیر	کاری که انجام می‌دهد
--headless	THRONE_HEADLESS=1	بدون پنجره اجرا می‌شود. هر مقداری از متغیر به‌جز خالی، 0، false، no و off آن را روشن می‌کند.
--data-dir DIR (-appdata DIR)	THRONE_DATA_DIR	پوشهٔ داده‌ها.
--restart-mode MODE	THRONE_RESTART_MODE	auto (پیش‌فرض)، exit یا exec. حالت‌های راه‌اندازی دوباره را ببینید.
--no-resume	THRONE_RESUME=0	آخرین نمایه را هنگام شروع اجرا نمی‌کند.
--no-kill-switch	THRONE_KILL_SWITCH=0	کیل‌سوییچ را در این اجرا خاموش نگه می‌دارد، حتی وقتی تنظیم kill_switch روشن است. نمایه‌ها تا وقتی این تنظیم خاموش نشود رد می‌شوند. برای بازیابی دسترسی در نظر گرفته شده است.
--log-format FORMAT	THRONE_LOG_FORMAT	auto (پیش‌فرض)، journal یا plain. گزارش‌ها را ببینید.
--api-listen LISTEN	THRONE_API_LISTEN	جایی که Throne API روی آن گوش می‌دهد: PORT (روی 127.0.0.1)، IPv4:PORT، [IPv6]:PORT، *:PORT (همهٔ نشانی‌ها) یا off. پیش‌فرض: 127.0.0.1:9095، مگر اینکه تنظیمات ذخیره‌شده API را روشن کنند.
--api-key-file FILE	THRONE_API_KEY_FILE	کلید API را از این فایل می‌خواند که باید وجود داشته باشد. thronectl keygen -o FILE چنین فایلی می‌نویسد. پیش‌فرض: config/api.key در پوشهٔ داده‌ها که در نخستین اجرا ساخته می‌شود.
--api-admin-lan	THRONE_API_ADMIN_LAN=1	به درخواست‌های مدیریتی (وارد کردن، تنظیمات، پشتیبان‌ها، راه‌اندازی دوباره) از شبکه هم پاسخ می‌دهد، نه فقط از این دستگاه.
--api-allow LIST	THRONE_API_ALLOW	نشانی‌ها و زیرشبکه‌هایی که می‌توانند از شنونده‌ای (listener) که روی loopback نیست استفاده کنند، جداشده با ویرگول یا فاصله. فهرست خالی باعث خروج با کد 64 می‌شود. برای مجاز کردن همهٔ نشانی‌ها، متغیر را تنظیم‌نشده بگذارید.
--debug		گزارش‌گیری در سطح debug.
--service		فقط Windows: زیر Service Control Manager اجرا می‌شود، حتی بدون --headless بدون رابط گرافیکی. اگر به هر روش دیگری اجرا شود، با کد 64 خارج می‌شود.
--health		از Throne در حال اجرا می‌پرسد که در چه وضعیتی است. Throne --health را ببینید.
--print-connection		THRONE_ADDR و THRONE_KEY_FILE را برای thronectl چاپ می‌کند. اتصال thronectl به Throne را ببینید.
--check		بررسی می‌کند که آیا این رایانه می‌تواند Throne بدون رابط گرافیکی را اجرا کند. Throne --check را ببینید.
--help، --version		گزینه‌ها یا نسخه را چاپ می‌کند.

• متغیرهای بله/خیر این مقدارها را می‌پذیرند: 1، true، yes، on، 0، false، no یا off. هر مقدار دیگری باعث خروج با کد 64 می‌شود.
• گزینه‌ها و متغیرهای --api-* در هر بار شروع بر تنظیمات ذخیره‌شدهٔ API اولویت دارند و هرگز ذخیره نمی‌شوند. به این ترتیب یک تنظیم نادرستِ ذخیره‌شدهٔ API همیشه از خط فرمان قابل اصلاح است.
• --health، --print-connection و --check بدون --headless کار می‌کنند. هر بار فقط از یکی از آن‌ها استفاده کنید، و هرگز همراه با --service.
• یک لینک یا فایل در خط فرمان باعث خروج با کد 64 می‌شود. آن را با thronectl import وارد کنید.

با یونیت systemd، متغیرها را در /etc/throne/throne.env و گزینه‌ها را با یک drop-in تنظیم کنید. Debian، Ubuntu، Raspberry Pi OS، Fedora، openSUSE را ببینید.

پوشهٔ داده‌ها

Throne بدون رابط گرافیکی از نخستین موردی از این فهرست که صدق کند استفاده می‌کند:

1. --data-dir، سپس THRONE_DATA_DIR. مسیر نسبی از پوشه‌ای که Throne در آن شروع می‌شود حساب می‌شود.
2. STATE_DIRECTORY که systemd آن را برای StateDirectory= تنظیم می‌کند.
3. با root: /var/lib/throne در Linux، /Library/Application Support/Throne در macOS. در Windows، با --service یا با LocalSystem: C:\ProgramData\Throne.
4. پوشهٔ پیکربندی کاربر که برنامهٔ دسکتاپ هم از آن استفاده می‌کند: ~/.config/Throne در Linux، ~/Library/Preferences/Throne در macOS، %LOCALAPPDATA%\Throne در Windows. در Linux و macOS بدون HOME، Throne با کد 78 خارج می‌شود؛ پوشه را با --data-dir مشخص کنید.

Throne بدون رابط گرافیکی هرگز داده‌هایش را کنار برنامه نگه نمی‌دارد، آن‌طور که یک نصب قابل‌حمل دسکتاپ این کار را می‌کند. برای استفادهٔ مشترک از داده‌های چنین نصبی، --data-dir را با پوشهٔ برنامه بدهید.

در Linux و macOS، پوشه‌های ناموجود را طوری می‌سازد که فقط کاربر خودش بتواند آن‌ها را بخواند. وقتی با root اجرا شود، پوشهٔ داده‌هایی را که کاربران دیگر می‌توانند در آن بنویسند رد می‌کند (کد 78)، چون تنظیمات، برنامه‌هایی را نام می‌برند که Throne اجرا می‌کند. در Windows، C:\ProgramData\Throne فقط برای SYSTEM و Administrators نگه داشته می‌شود (پوشهٔ داده‌ها را ببینید)؛ برای پوشهٔ دیگری که کاربران عادی می‌توانند در آن بنویسند، فقط یک هشدار در گزارش نوشته می‌شود.

محتوای آن:

مسیر	محتوا
config/throne.db	نمایه‌ها، گروه‌ها، نمایه‌های مسیریابی و تنظیمات، مانند برنامهٔ دسکتاپ
config/api.key	کلید API که فقط کاربر Throne می‌تواند آن را بخواند
config/logs/throne.log	گزارش این اجرا. crashed-<time>.log گزارش اجرایی را نگه می‌دارد که به‌درستی پایان نیافته است.
config/crashes/	گزارش‌های کرش
config/headless-state.json	شمارنده‌هایی برای اجرای دوبارهٔ نمایه و برای کرش‌ها، و اینکه آخرین اجرا چگونه پایان یافته است
config/hwid	شناسهٔ دستگاه، وقتی سیستم شناسه‌ای ندارد
config/.lock، config/.instance	قفل پوشهٔ داده‌ها، و سوکتی که --health از طریق آن می‌پرسد. در Windows این نمونه (instance) یک named pipe است، نه یک فایل.

حالت‌های راه‌اندازی دوباره

thronectl restart، بازیابی پشتیبان و سیگنال SIGHUP، Throne را دوباره راه‌اندازی می‌کنند. --restart-mode تعیین می‌کند چگونه:

حالت	چه اتفاقی می‌افتد
exit	Throne با کد 75 خارج می‌شود و مدیر سرویس آن را دوباره شروع می‌کند.
exec	Throne در همان پردازه دوباره شروع می‌شود (Linux و macOS؛ شناسهٔ پردازه تغییر نمی‌کند). در Windows یک پردازهٔ جدید Throne شروع می‌کند و با کد 0 خارج می‌شود. سرویس Windows همیشه از exit استفاده می‌کند.
auto	exit وقتی systemd (سوکت notify آن، یا user manager)، launchd یا init یک کانتینر، Throne را شروع کرده باشد، یا وقتی Throne به‌صورت سرویس Windows اجرا شود. در غیر این صورت exec، برای مثال از ترمینال.

یونیت‌های عرضه‌شده، فایل plist و ایمیج Docker به auto یا exit نیاز دارند. Throne --check نشان می‌دهد auto کدام را انتخاب می‌کند. در ترمینال، بستن ترمینال (hang-up) به‌جای راه‌اندازی دوباره، Throne را با کد 0 متوقف می‌کند.

کدهای خروج

Throne پیش از خروج EXIT <code>: <reason> را در گزارش می‌نویسد. کاری که فایل‌های سرویس عرضه‌شده با هر کد انجام می‌دهند:

کد	معنی	یونیت systemd	Docker unless-stopped	plist در launchd	سرویس Windows
0	متوقف شد: SIGTERM، SIGINT، thronectl shutdown؛ در Windows همچنین توقف سرویس، Ctrl+C، بستن کنسول، خروج از حساب کاربری یا taskkill بدون /F. همچنین راه‌اندازی دوباره در Windows بیرون از سرویس، که یک Throne جدید را شروع کرده است.	خاموش می‌ماند	دوباره شروع می‌شود، مگر با docker stop	خاموش می‌ماند	متوقف می‌ماند
1	شروع به دلیلی ناموفق بود که ممکن است برطرف شود: قفل، سوکت نمونه (instance)، پایگاه‌داده، شنوندهٔ IPC هسته، یا نشانی --api-listen که در 30 ثانیه ظاهر نشد	پس از 3 ثانیه دوباره شروع می‌شود	دوباره شروع می‌شود	پس از 10 ثانیه دوباره شروع می‌شود	بازیابی
3	Throne دیگری از پوشهٔ داده‌ها استفاده می‌کند	خاموش می‌ماند	دوباره شروع می‌شود	هر 10 ثانیه دوباره امتحان می‌شود	بازیابی
64	یک گزینه، مقدار گزینه یا متغیر نادرست، یا --service که Service Control Manager آن را اجرا نکرده است	خاموش می‌ماند	دوباره شروع می‌شود	هر 10 ثانیه دوباره امتحان می‌شود	بازیابی
70	هسته پشت سر هم شکست خورد و Throne از آن دست کشید، یا هسته 60 ثانیه قابل استفاده نبود	دوباره شروع می‌شود	دوباره شروع می‌شود	دوباره شروع می‌شود	بازیابی
71	یک نمایه 180 ثانیه در حال اتصال یا 90 ثانیه در حال توقف بود	دوباره شروع می‌شود	دوباره شروع می‌شود	دوباره شروع می‌شود	بازیابی
75	راه‌اندازی دوباره درخواست شد، با --restart-mode exit یا به‌صورت سرویس Windows، یا راه‌اندازی دوبارهٔ exec که انجام‌پذیر نبود	دوباره شروع می‌شود	دوباره شروع می‌شود	دوباره شروع می‌شود	بازیابی
78	خطای پیکربندی: پوشهٔ داده‌ها (همچنین نبود HOME برای پیدا کردن آن، یا در Windows پوشهٔ C:\ProgramData\Throne که کاربر دیگری مالک آن است، کاربران دیگر می‌توانند در آن بنویسند یا یک link است)، فایل کلید API، شنوندهٔ --api-listen، یا فایل پایگاه‌داده‌ای که قابل استفاده نیست	خاموش می‌ماند	دوباره شروع می‌شود	هر 10 ثانیه دوباره امتحان می‌شود	بازیابی

«بازیابی» یعنی اقدامات بازیابی (recovery actions) سرویس Windows: سرویس Windows را ببینید.

• یونیت systemd هیچ محدودیت شروعی ندارد (StartLimitIntervalSec=0). هر thronectl restart، بازیابی پشتیبان و SIGHUP یک شروع جدید است، و یک محدودیت می‌توانست Throne را بدون API خاموش رها کند.
• Docker پیش از هر راه‌اندازی دوبارهٔ پیاپی، مدت بیشتری صبر می‌کند.
• پس از سه شروع پیاپی بدون هستهٔ کارا، Throne دیگر با کدهای 70 و 71 خارج نمی‌شود و به‌جای آن روشن می‌ماند.
• برای کد 78 مربوط به پایگاه‌داده، در گزارش آمده است که چه باید کرد: یک config/throne.db آسیب‌دیده را همراه با فایل‌های -wal و -shm آن به جای دیگری منتقل کنید، یا یک نسخهٔ کپی را برگردانید. فایل‌های فقط‌خواندنی را برای کاربر Throne قابل نوشتن کنید.

فرمان‌های بررسی، کدهای خروج خودشان را دارند:

فرمان	0	1	2	64
--health	سالم	ناسالم، یا هنوز در حال شروع	هیچ Throne‌ای پاسخ نداد، یا سرویس Windows خط فرمانی را که دسترسی مدیر ندارد رد کرد	گزینهٔ نادرست
--check	هیچ خط [FAIL] وجود ندارد	یک خط [FAIL]		گزینهٔ نادرست
--print-connection	هر دو خط را چاپ کرد		API خاموش است یا گوش نمی‌دهد، یا کلید آن در یک فایل نیست؛ یا سرویس Windows خط فرمان را رد کرد	گزینهٔ نادرست

--health و --print-connection وقتی هیچ پوشهٔ داده‌ای پیدا نکنند (بدون HOME)، با کد 78 خارج می‌شوند؛ پوشه را با --data-dir مشخص کنید.