رفتن به محتوای اصلی
FA

خانه / وبلاگ / استقرار

API کنترل Clash به‌طور کامل — نقاط پایانی، پنل‌ها و اسکریپت‌های خودکارسازی

استقرار2026-06-011426 واژه3 دقیقه مطالعه
API کنترل Clash به‌طور کامل — نقاط پایانی، پنل‌ها و اسکریپت‌های خودکارسازی

هستهٔ Mihomo یک RESTful API همراه دارد. رابط خود Clash Verge هم از همین راه با هسته حرف می‌زند — نقاط پایانی را بفهمید تا بتوانید هر کاری که رابط می‌کند را با اسکریپت انجام دهید.

روشن کردنش و پیامدهای امنیتی

external-controller: 127.0.0.1:9090
secret: "یک رشتهٔ تصادفی به‌قدر کافی بلند"

ساختن یک secret تصادفی:

openssl rand -hex 24

احراز هویت

هر درخواست یک توکن bearer می‌برد:

curl -H "Authorization: Bearer secret-شما" http://127.0.0.1:9090/version

نقاط پایانی WebSocket (لاگ، ترافیک) به‌جایش پارامتر پرس‌وجو می‌پذیرند:

ws://127.0.0.1:9090/traffic?token=secret-شما

جدول کامل نقاط پایانی

روشمسیرکاربرد
GET/versionنسخهٔ هسته
GET/configsپیکربندی جاری
PATCH/configsتغییر تنظیمات در زمان اجرا (پورت، حالت و غیره)
PUT/configs?force=trueبارگذاری دوبارهٔ فایل پیکربندی
GET/proxiesهمهٔ گره‌ها و گروه‌های سیاست
GET/proxies/:nameجزئیات یک گره یا گروه
PUT/proxies/:nameعوض کردن گرهٔ انتخاب‌شدهٔ یک گروه
GET/proxies/:name/delayسنجش تأخیر یک گره
GET/group/:name/delayسنجش یک گروه سیاست کامل
GET/connectionsهمهٔ اتصال‌های جاری
DELETE/connectionsبستن همهٔ اتصال‌ها
DELETE/connections/:idبستن یک اتصال
GET/rulesفهرست قواعد در حال اجرا
GET/providers/proxiesهمهٔ proxy-providerها
PUT/providers/proxies/:nameبه‌روزرسانی دستی یک provider
GET/providers/rulesهمهٔ rule-providerها
PUT/providers/rules/:nameبه‌روزرسانی دستی یک مجموعه قاعده
GET/logsجریان لاگ (WebSocket)
GET/trafficترافیک زنده (WebSocket)
GET/memoryمصرف حافظه (WebSocket)

عملیات رایج

فهرست همهٔ گروه‌های سیاست و انتخاب فعلی‌شان

curl -s -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/proxies | jq '.proxies | to_entries[] | select(.value.type=="Selector") | {group: .key, now: .value.now}'

عوض کردن گره

curl -X PUT \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"HK-01"}' \
  http://127.0.0.1:9090/proxies/PROXY

نام گروه‌هایی که فاصله یا ایموجی دارند باید URL-encode شوند:

GROUP=$(printf '%s' "🚀 انتخاب" | jq -sRr @uri)
curl -X PUT -H "Authorization: Bearer $SECRET" \
  -d '{"name":"HK-01"}' \
  "http://127.0.0.1:9090/proxies/$GROUP"

سنجش تأخیر یک گره

curl -s -H "Authorization: Bearer $SECRET" \
  "http://127.0.0.1:9090/proxies/HK-01/delay?timeout=5000&url=http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204"
# مقدار {"delay":123} برمی‌گرداند

عوض کردن حالت پروکسی

curl -X PATCH -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"mode":"global"}' \
  http://127.0.0.1:9090/configs

مقدار mode می‌تواند rule یا global یا direct باشد. همین نقطهٔ پایانی log-level و allow-lan و دیگر فیلدها را هم عوض می‌کند.

بارگذاری دوبارهٔ پیکربندی

curl -X PUT -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"path":"/etc/mihomo/config.yaml"}' \
  "http://127.0.0.1:9090/configs?force=true"

بستن همهٔ اتصال‌ها

curl -X DELETE -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/connections

عوض کردن گره اتصال‌های موجود را جابه‌جا نمی‌کند (یک اتصال TCP برقرارشده همچنان از گرهٔ قدیمی می‌رود)؛ این دستور همه را وادار به اتصال دوباره می‌کند.

به‌روزرسانی یک provider

# تازه کردن اشتراک گره‌ها
curl -X PUT -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/providers/proxies/main

# تازه کردن یک مجموعه قاعده
curl -X PUT -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/providers/rules/cn-domain

اسکریپت‌های مفید

۱. رفتن خودکار به کم‌تأخیرترین گره

#!/bin/bash
# pick-fastest.sh — بسنج و به سریع‌ترین گره برو
set -euo pipefail
API="http://127.0.0.1:9090"
SECRET="secret-شما"
GROUP="AUTO"
TEST_URL="http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204"

# یک سنجش روی کل گروه راه بینداز
curl -s -H "Authorization: Bearer $SECRET" \
  "$API/group/$GROUP/delay?timeout=5000&url=$TEST_URL" > /dev/null

# کمترین تأخیر را پیدا کن
BEST=$(curl -s -H "Authorization: Bearer $SECRET" "$API/proxies" \
  | jq -r --arg g "$GROUP" '
    .proxies[$g].all[] as $n
    | .proxies[$n]
    | select(.history | length > 0)
    | select(.history[-1].delay > 0)
    | "\(.history[-1].delay) \(.name)"
  ' | sort -n | head -1 | cut -d' ' -f2-)

echo "سریع‌ترین گره: $BEST"
curl -s -X PUT -H "Authorization: Bearer $SECRET" \
  -d "{\"name\":\"$BEST\"}" "$API/proxies/$GROUP" > /dev/null

۲. پاییدن سلامت گره‌ها و هشدار وقتی همه افتاده‌اند

#!/bin/bash
# health-watch.sh
API="http://127.0.0.1:9090"
SECRET="secret-شما"

ALIVE=$(curl -s -H "Authorization: Bearer $SECRET" "$API/proxies" \
  | jq '[.proxies[] | select(.type != "Selector" and .type != "URLTest")
         | select(.history | length > 0)
         | select(.history[-1].delay > 0)] | length')

if [ "$ALIVE" -eq 0 ]; then
  echo "$(date '+%F %T') هیچ گرهٔ قابل استفاده‌ای نیست" >> /var/log/mihomo-alert.log
  # کانال اطلاع‌رسانی خودتان را اینجا وصل کنید
fi

۳. فهرست سنگین‌ترین اتصال‌ها

curl -s -H "Authorization: Bearer $SECRET" http://127.0.0.1:9090/connections \
  | jq -r '.connections
      | sort_by(-.download)
      | .[:10][]
      | "\(.download/1048576 | floor)MB  \(.metadata.host // .metadata.destinationIP)  \(.metadata.processPath // "-")"'

برای فهمیدن «چه چیزی ترافیکم را می‌خورد» خیلی به کار می‌آید.

۴. دنبال کردن زندهٔ لاگ

# به websocat یا wscat نیاز دارد
websocat "ws://127.0.0.1:9090/logs?token=secret-شما&level=info"

استقرار پنل وب

پنل یک صفحهٔ کاملاً ایستاست که از راه API با هسته حرف می‌زند.

گزینهٔ الف: میزبانی توسط هسته (پیشنهادی)

external-ui: /etc/mihomo/ui
external-ui-name: metacubexd
external-ui-url: "https://نشانی-انتشار-پنل/dist.zip"

فایل‌های پنل را در پوشه‌ای که external-ui نام برده استخراج کنید، بعد بروید به:

http://نشانی-هسته:9090/ui

بار اول نشانی API (http://نشانی-هسته:9090) و secret را وارد می‌کنید.

گزینهٔ ب: پنل میزبانی‌شدهٔ عمومی

پنل فرانت‌اند خالص است، پس می‌توانید از صفحهٔ میزبانی‌شدهٔ کس دیگری استفاده کنید و نشانی API و secret خودتان را بدهید.

مقایسهٔ پنل‌های رایج

سه ردهٔ پنلmetacubexdکامل از نظر قابلرابط امروزیکمی سنگین‌ترzashboardسبک و مناسب موبابرای کار از گوشی خوب استخانوادهٔ yacdکلاسیککمترین مصرف منابعبعضی قابلیت‌های تازه را پشتیبانی نمی‌کند
پنل فقط فرانت‌اند API است — هر وقت خواستید عوضش کنید، به هسته کاری ندارد

چند کاربرد هوشمندانهٔ API

تعویض زمان‌بندی‌شدهٔ گره

در ساعت اوج به خط اختصاصی بروید و در روز به گرهٔ معمولی برگردید:

# crontab
0 20 * * * /usr/local/bin/switch-node.sh "IPLC-HK"
0 1  * * * /usr/local/bin/switch-node.sh "AUTO"

یک میان‌بر صفحه‌کلید (روی دسکتاپ)

همراه AutoHotkey روی ویندوز یا Hammerspoon روی مک، یک میان‌بر بین حالت سراسری و حالت قواعد جابه‌جا می‌کند:

# رفتن به حالت سراسری
curl -X PATCH -H "Authorization: Bearer $SECRET" \
  -d '{"mode":"global"}' http://127.0.0.1:9090/configs

تغذیهٔ یک سامانهٔ پایش

نقطهٔ پایانی /traffic یک WebSocket است که هر ثانیه نرخ ارسال و دریافت را می‌فرستد. آن را در یک پایگاه دادهٔ سری‌زمانی جمع کنید تا نمودار ترافیک داشته باشید.

عیب‌یابی

وقتی API وصل نمی‌شودآیا پورت گوش می‌دهد: ss -tlnp \grep 9090نشانی گوش دادن 127.0.0.1 است یا 0.0.0.0 (این تعیین می‌کند دسترسی از راه دور ممکن است یا نه)آیا secret درست است و سرآیند Authorization به شکل Bearer xxx نوشته شدهآیا فایروال پورت ۹۰۹۰ را اجازه می‌دهدپاسخ ۴۰۱ — secret غلط استپاسخ ۴۰۴ — مسیر غلط است؛ یادتان باشد نام گروه‌ها باید URL-encode شودوصل نمی‌شود ولی هسته در حال اجراست — ببینید external-controller در پیکربندی کامنت نشده باشد

یک بررسی سریع:

curl -i -H "Authorization: Bearer $SECRET" http://127.0.0.1:9090/version

پاسخ ۲۰۰ با JSON نسخه یعنی رد شده‌اید.

خلاصه

  • API هر کاری که رابط می‌کند را می‌تواند بکند، از جمله عوض کردن گره و حالت و بارگذاری دوبارهٔ پیکربندی
  • secret لازم است، به‌ویژه وقتی روی 0.0.0.0 گوش می‌دهد
  • نام گروه‌های دارای فاصله یا ایموجی باید URL-encode شوند
  • بعد از عوض کردن گره DELETE /connections را یادتان باشد، وگرنه اتصال‌های موجود روی گرهٔ قدیمی می‌مانند
  • پنل فقط یک فرانت‌اند است؛ میزبانی خودتان از صفحهٔ شخص ثالث امن‌تر است

بیشتر بخوانید: Mihomo به‌عنوان دروازهٔ خانگی و عیب‌یابی ترافیک و اتصال‌ها.


مستندات مرتبط

رساندن Docker و WSL2 به پروکسی Clash روی میزبان
استقرار رساندن Docker و WSL2 به پروکسی Clash روی میزبان

نشانی 127.0.0.1 داخل کانتینر همان میزبان نیست. پیکربندی برای هر سه سناریوی Docker — کشیدن تصویر توسط دیمون، زمان ساخت و زمان اجرا — به‌علاوهٔ دو رویکرد برای حالت‌های شبکهٔ متفاوت WSL2.

2026-06-141401 واژه3 دقیقه مطالعه