کنترلر خارجی (Clash API)
mihomo پیادهسازی Clash RESTful API را ارائه میدهد. همهٔ داشبوردهای Clash (metacubexd، yacd، Clash Dashboard) از طریق آن با mihomo صحبت میکنند. این صفحه خوشهٔ کلیدهای سطح بالا را مستندسازی میکند که محل گوش دادن API، UI همراه و CORS را پیکربندی میکنند.
کلیدهای سطح بالا
| فیلد | نوع | پیشفرض | مقادیر مجاز | توضیحات |
|---|---|---|---|---|
external-controller | string | (unset) | <host:port> | آدرس گوش دادن HTTP ساده برای API RESTful. |
external-controller-pipe | string | (unset) | <pipe path> | مسیر named-pipe ویندوز. فقط زمانی روی ویندوز تنظیم کنید که میخواهید API به کلاینتهای همان میزبان محدود شود. |
external-controller-unix | string | (unset) | <socket path> | مسیر سوکت دامنه-Unix برای API. |
external-controller-tls | string | (unset) | <host:port> | آدرس گوش دادن محافظتشده با TLS. نیاز دارد بلوک سطح-بالای `tls` گواهی و کلید خصوصی را داشته باشد. |
external-controller-cors | RawCors | (unset) | RawCors | فهرست مجاز CORS برای API از نوع HTTP. |
external-ui | string | (unset) | <dir path> | دایرکتوری محلی که محتوای آن در /ui ارائه میشود. |
external-ui-url | string | (unset) | <URL> | URL آرشیوی که هنگام خالی بودن دایرکتوری external-ui واکشی و در آن باز میشود. |
external-ui-name | string | (unset) | <name> | زیرشاخهای زیر external-ui که ارائه میشود، که اجازه میدهد چند داشبورد در کنار هم قرار گیرند. |
external-doh-server | string | (unset) | <path> | <host:port> | یک نقطه پایانی DoH را در این مسیر سوار کن تا دستگاههای دیگر بتوانند از حلکنندهٔ DNS مربوط به mihomo استفاده کنند. |
secret | string | (unset) | <bearer token> | توکن Bearer لازم برای همهٔ فراخوانیهای API. هرگاه external-controller روی آدرس غیر-loopback مقیّد میشود، اکیداً توصیه میشود. |
منبع: config/config.go:392-459 · ثابتشده در v1.19.24 (a847246)
external-controller-cors
| فیلد | نوع | پیشفرض | مقادیر مجاز | توضیحات |
|---|---|---|---|---|
allow-origins | []string | [] | <origin> | فهرست مجاز مبدأها. فهرست خالی یعنی فقط همان مبدأ. |
allow-private-network | bool | false | true | false | به درخواستهای preflight شبکهٔ خصوصی احترام بگذار تا داشبوردهای روی LANهای خصوصی بتوانند به API دسترسی داشته باشند. |
منبع: config/config.go:212-215 · ثابتشده در v1.19.24 (a847246)
مثال
yaml
external-controller: 127.0.0.1:9090
external-controller-cors:
allow-origins:
- https://metacubex.github.io
- http://localhost:5173
allow-private-network: true
external-ui: /etc/mihomo/ui
external-ui-url: https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip
external-ui-name: metacubexd
secret: <random-string-here>نکات
- اگر
external-controllerبه آدرس غیر-loopback مقیّد شود، همیشهsecretو/یاexternal-controller-tlsرا تنظیم کنید. API میتواند هر تصمیم مسیریابی در دیمن را تغییر دهد. external-uiصرفاً یک سرور فایل است — هیچ امنیتی فراتر از چیزی که CORS فراهم میکند ندارد. بیشتر کاربران داشبورد را ازlocalhostارائه میدهند و از مرورگری در همان میزبان به آن میروند.external-controller-pipe(ویندوز) وexternal-controller-unix(Linux/macOS) زمانی مفیدند که میخواهید فقط کلاینتهای همان میزبان به API برسند؛ آنها را با ACLهای فایلسیستم جفت کنید.
منبع: config/config.go:412-421 · v1.19.24 (a847246)