هستهٔ 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 خودتان را بدهید.
مقایسهٔ پنلهای رایج
چند کاربرد هوشمندانهٔ 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 است که هر ثانیه نرخ ارسال و دریافت را میفرستد. آن را در یک پایگاه دادهٔ سریزمانی جمع کنید تا نمودار ترافیک داشته باشید.
عیبیابی
یک بررسی سریع:
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 بهعنوان دروازهٔ خانگی و عیبیابی ترافیک و اتصالها.
مستندات مرتبط
نشانی 127.0.0.1 داخل کانتینر همان میزبان نیست. پیکربندی برای هر سه سناریوی Docker — کشیدن تصویر توسط دیمون، زمان ساخت و زمان اجرا — بهعلاوهٔ دو رویکرد برای حالتهای شبکهٔ متفاوت WSL2.
جدول مرجعی که ارزش نشان کردن دارد. دستور پروکسی هر ابزار، محل فایل تنظیماتش، راه برگرداندنش، و اینکه چرا بعضی ابزارها متغیرهای محیطی را نادیده میگیرند.
بدون هیچ تنظیمی برای تکتک دستگاههای خانه. بدهبستان سه رویکرد (روتر جانبی، TProxy، TUN)، پیکربندی کامل و سرویس systemd، قواعد فایروال، و تابآوری تا اهل خانه آنلاین بمانند.