[Suggestion/Documentation] Connection Failure due to CORS Policy Mismatch in Mihomo `config.yaml`

[jiezhengj]

Description

Environment:

• Platform: Docker on NAS (Synology/Ugreen/QNAP)
• Backend: metacubex/mihomo (latest) running in Host mode (External Controller on port 9090)
• Frontend: metacubex/metacubexd (latest) running in Bridge mode (Mapped to port 8080)
• Client: Browser accessing the local network IP (e.g., 192.168.31.218)

The Issue:
When accessing the panel via http://192.168.31.218:8080, the UI loads correctly. However, when attempting to connect to the Mihomo backend at http://192.168.31.218:9090, the error message "Unable to connect to backend, please check the address and if the backend is running" appears, even though the backend is confirmed to be accessible directly in the browser.

---

Root Cause Analysis

The issue is rooted in the Cross-Origin Resource Sharing (CORS) security policy.

In the default or user-generated config.yaml for Mihomo, the external-controller-cors section typically includes a whitelist of allowed origins:

external-controller-cors:
  allow-origins:
    - tauri://localhost
    - https://yacd.metacubex.one
    - https://metacubex.github.io

When a user hosts their own dashboard (e.g., on port 8080), the browser treats requests from http://192.168.31.218:8080 to http://192.168.31.218:9090 as a cross-origin request. Since the local IP/port is not in the allow-origins whitelist, the Mihomo core rejects the request, and the browser blocks the connection for security reasons.

This is a common "blind spot" because:

1. Users often assume that being on the same local network is sufficient.
2. The error message is generic and doesn't explicitly mention CORS issues.

---

Solution / Logic

The user must manually add their local dashboard access URL to the allow-origins list in the Mihomo configuration.

Proposed Configuration Change:

external-controller-cors:
  allow-private-network: true
  allow-origins:
    - http://192.168.31.218:8080  # Add the specific dashboard URL
    - '*'                         # Alternatively, use wildcard for local environments

---

Suggestion for Improvement

To prevent this confusion for future users, I suggest adding a "CORS Troubleshooting" or "Self-Hosted Note" section to the README.md.

Draft for README:

Note for Self-Hosted Users:
If you are hosting this dashboard on your own server (e.g., via Docker), ensure that your Mihomo config.yaml allows your dashboard's URL in the CORS settings. Otherwise, the browser will block the connection.

external-controller-cors:
  allow-origins:
    - 'http://your-nas-ip:port'

If you still cannot connect, check your browser's Developer Tools (F12) Console for CORS errors.

By including this in the documentation, we can significantly reduce the number of support requests related to "connection failed" errors in self-hosted setups.

---

(End of Issue)