سرویس API — sing-box

سرویس api یک سرور gRPC برای مشاهده و کنترل نمونهٔ در حال اجرای sing-box است: وضعیت سرویس، گزارش‌ها، گروه‌های خروجی (انتخاب و آزمون URL)، حالت Clash، ردیابی اتصال‌ها، و ابزارهایی مانند آزمون کیفیت شبکه و STUN یا عملیات Tailscale. همان رابطی را ارائه می‌کند که کلاینت‌های گرافیکی به‌صورت محلی استفاده می‌کنند؛ بنابراین قابلیت کنترل از راه دور کلاینت‌های گرافیکی، کلاینت وب sing-box Dashboard و فرمان sing-box api همگی می‌توانند یک نمونهٔ راه‌دور را کنترل کنند. شنونده gRPC-Web را نیز می‌پذیرد (از جمله ترابرد WebSocket کلاینت gRPC-Web از improbable-eng برای فراخوانی‌های جریانی)، پس مرورگر می‌تواند مستقیماً با آن گفتگو کند.

گزینه‌ها

type: "api" زیر services[]:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`secret`	`string`	`(empty)`	`<string>`	رمز مشترک. کلاینت‌ها آن را به‌صورت سرآیند متادیتای gRPC ‏`authorization: Bearer <secret>` می‌فرستند. خالی بودن آن احراز هویت را کاملاً غیرفعال می‌کند؛ پس روی شنونده‌ای که میزبان‌های دیگر به آن دسترسی دارند حتماً مقداری تنظیم کنید.
`access_control_allow_origin`	`badoption.Listable[string]`	`*`	`<origin> \| …`	مبداهای مجاز CORS برای کلاینت‌های مرورگری (gRPC-Web) مانند sing-box Dashboard. خالی یعنی `*`.
`access_control_allow_private_network`	`bool`	`false`	`true \| false`	پاسخ به پیش‌درخواست‌های Private Network Access ‏(`Access-Control-Allow-Private-Network`)، تا صفحه‌ای که از یک مبدأ عمومی ارائه می‌شود — مانند Dashboard میزبانی‌شده — بتواند APIای را که روی آدرس خصوصی یا loopback گوش می‌دهد فراخوانی کند.
`dashboard`	`*APIDashboardOptions`	`(disabled)`	`true \| false \| <directory path> \| APIDashboardOptions`	ارائهٔ sing-box Dashboard در `/dashboard/` روی همان شنونده؛ دیگر درخواست‌های مرورگر به آنجا هدایت می‌شوند. `true` معادل `{ "enabled": true }` است و رشته کوتاه‌نوشت `{ "enabled": true, "path": "<string>" }` است.

منبع: option/api.go:11-18 · ثابت‌شده در v1.14.2 (af6e64c)

این سرویس همچنین ListenOptions (listen، listen_port و … — ورودی‌ها را ببینید) و یک بلوک tls ورودی (TLS را ببینید) را جاسازی می‌کند. پورت پیش‌فرضی وجود ندارد؛ listen_port را صریحاً تنظیم کنید.

`dashboard`

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
`enabled`	`bool`	`false`	`true \| false`	فعال‌کردن داشبورد.
`path`	`string`	`dashboard`	`<directory path>`	دایرکتوری فایل‌های داشبورد، نسبت به دایرکتوری کاری. دایرکتوری خالی با دانلود پر می‌شود و با فایل `.etag` پیگیری می‌شود؛ دایرکتوری غیرخالی بدون `.etag` همان‌طور که هست ارائه می‌شود و هرگز به‌روزرسانی نمی‌شود.
`download_url`	`string`	`(gh-pages archive)`	`<URL>`	آرشیو zip که داشبورد از آن دانلود می‌شود. پیش‌فرض، آرشیو شاخهٔ gh-pages مخزن sing-box-dashboard در GitHub است.
`http_client`	`*HTTPClientOptions`	`(default client)`	`<http_clients tag> \| HTTPClientOptions`	کلاینت HTTP برای دانلود: یک شیء درون‌خطی یا tag یکی از مدخل‌های `http_clients`. وقتی دایرکتوری فایل‌های فراهم‌شده توسط کاربر دارد استفاده نمی‌شود.
`update_interval`	`badoption.Duration`	`1d`	`<duration>`	هر چند وقت یک‌بار نشانی دانلود برای آرشیو جدیدتر داشبورد بررسی شود.

منبع: option/api.go:20-26 · ثابت‌شده در v1.14.2 (af6e64c)

فرمان `sing-box api`

sing-box api کلاینت خط فرمان این سرویس است و همان عملیاتی را دارد که کلاینت‌های گرافیکی ارائه می‌دهند — وضعیت، گزارش‌ها، گروه‌های خروجی، حالت Clash، اتصال‌ها، آزمون‌های کیفیت شبکه و STUN،‏ Tailscale، احراز هویت OpenVPN / OpenConnect،‏ USB/IP و موارد دیگر. با --url (یا $BOX_API_URL؛ اگر طرحی داده نشود http:// فرض می‌شود) و --secret (یا $BOX_API_SECRET) آن را به سرویس متصل کنید.

مثال حداقلی

json

{
  "services": [
    {
      "type": "api",
      "tag": "api",
      "listen": "127.0.0.1",
      "listen_port": 9091,
      "secret": "change-me",
      "dashboard": true
    }
  ]
}

sing-box api --url 127.0.0.1:9091 --secret change-me status

با dashboard: true، باز کردن http://127.0.0.1:9091/ در مرورگر به Dashboard هدایت می‌شود.

نکات

خالی بودن secret یعنی هر کسی که به پورت دسترسی دارد می‌تواند گزارش‌ها را بخواند، گروه‌های خروجی را عوض کند و اتصال‌ها را ببندد. شنونده را روی loopback نگه دارید، یا پیش از در معرض قرار دادن آن secret (و tls) را تنظیم کنید.
بدون tls، شنونده HTTP/1.1 و HTTP/2 متن‌آشکار (h2c) را پشتیبانی می‌کند؛ با tls، ‏h2 و http/1.1 خودکار به فهرست ALPN افزوده می‌شوند.
داشبورد هنگام شروع سرویس دانلود می‌شود و هر update_interval دوباره بررسی می‌شود. دایرکتوری‌ای که فایل دارد ولی .etag ندارد، فراهم‌شده توسط کاربر به شمار می‌آید: همان‌طور که هست ارائه می‌شود و هرگز بازنویسی نمی‌شود.
این سرویس به هیچ برچسب ساختی نیاز ندارد.
API ‏REST سازگار با Clash قابلیتی جداگانه است، یعنی experimental.clash_api؛ آزمایشی را ببینید.

نکات بین‌هسته‌ای

Xray-core یک API مبتنی بر gRPC ارائه می‌کند (api.services مانند HandlerService و StatsService) که از طریق یک ورودی اختصاصی به‌همراه یک قاعدهٔ مسیریابی در دسترس است. داشبورد همراه ندارد.
mihomo از کنترل‌گر خارجی REST سازگار با Clash استفاده می‌کند، با رابط وب اختیاری — همان خانوادهٔ API که experimental.clash_api در sing-box است، نه این سرویس gRPC.

منبع: option/api.go:11-26 · v1.14.2 (af6e64c)

سرویس API — sing-box ​

گزینه‌ها ​

dashboard ​

فرمان sing-box api ​

مثال حداقلی ​

نکات ​

نکات بین‌هسته‌ای ​