feat: support desktop dashboard listen config (#134)

* fix: allow LAN dashboard access by default

* docs: explain manual LAN dashboard access

* feat: support desktop dashboard listen config

* fix: log invalid desktop dashboard config

* refactor: simplify desktop dashboard config parsing

* refactor: use cmd config for desktop dashboard listen

* fix: ignore blank dashboard env overrides

Author: zouyonghe

README.md

@@ -93,6 +93,51 @@ If you need to migrate data between the desktop app and a source-based deploymen
 
 Not really. AstrBot Desktop is intended for local desktop usage and personal workflows. If you need long-running, stable server deployment, use the upstream AstrBot source, Docker, or panel-based deployment instead.
 
+<!-- faq: lan-webui-access -->
+### How can I access the WebUI from another device on my LAN?
+
+AstrBot Desktop listens on `127.0.0.1:6185` by default, so only the local machine can access the WebUI. If you explicitly want LAN access, set the dashboard host to `0.0.0.0` in AstrBot's command config.
+
+Config file path:
+
+```text
+~/.astrbot/data/cmd_config.json
+```
+
+On Windows, this is usually:
+
+```text
+C:\Users\<username>\.astrbot\data\cmd_config.json
+```
+
+Write this content:
+
+```json
+{
+  "dashboard": {
+    "host": "0.0.0.0",
+    "port": 6185
+  }
+}
+```
+
+Fully quit and restart AstrBot Desktop after saving the file, then visit this URL from another device:
+
+```text
+http://<LAN IP of the machine running AstrBot Desktop>:6185/
+```
+
+To restore local-only access, set `dashboard.host` back to `127.0.0.1`, then restart the app.
+
+Environment variables still work as advanced overrides and take precedence over `cmd_config.json`:
+
+```bash
+ASTRBOT_DASHBOARD_HOST=0.0.0.0
+ASTRBOT_DASHBOARD_PORT=6185
+```
+
+Before enabling LAN access, make sure your system firewall allows port `6185`, and do not expose the port on untrusted networks or the public internet.
+
 <!-- faq: macos-quarantine -->
 ### macOS says the app is damaged or cannot be opened
 

README_zh.md

@@ -93,6 +93,51 @@ AstrBot Desktop 是面向本地桌面使用的 AstrBot 打包发行版。它内
 
 不推荐。AstrBot Desktop 更适合本地桌面使用和个人工作流体验；如果你要长期稳定运行在服务器上，更建议使用上游 AstrBot 的源码、Docker 或面板部署方式。
 
+<!-- faq: lan-webui-access -->
+### 如何从局域网内其他设备访问 WebUI？
+
+桌面端默认只监听 `127.0.0.1:6185`，仅允许本机访问。如果确认需要在同一局域网内访问，可以在 AstrBot 命令配置中把 dashboard host 改为 `0.0.0.0`。
+
+配置文件路径：
+
+```text
+~/.astrbot/data/cmd_config.json
+```
+
+Windows 对应路径通常是：
+
+```text
+C:\Users\<用户名>\.astrbot\data\cmd_config.json
+```
+
+写入以下内容：
+
+```json
+{
+  "dashboard": {
+    "host": "0.0.0.0",
+    "port": 6185
+  }
+}
+```
+
+保存后完全退出并重新启动 AstrBot Desktop，然后在其他设备访问：
+
+```text
+http://<运行 AstrBot Desktop 的主机内网 IP>:6185/
+```
+
+如需恢复默认本机访问，可把 `dashboard.host` 改回 `127.0.0.1` 后重启应用。
+
+环境变量仍可作为高级覆盖项，且优先级高于 `cmd_config.json`：
+
+```bash
+ASTRBOT_DASHBOARD_HOST=0.0.0.0
+ASTRBOT_DASHBOARD_PORT=6185
+```
+
+开启局域网访问前，请确认系统防火墙允许端口 `6185`，并不要在不可信网络或公网环境暴露该端口。
+
 <!-- faq: macos-quarantine -->
 ### macOS 提示“应用已损坏”或无法打开
 

docs/environment-variables.md

@@ -56,6 +56,29 @@
 | `ASTRBOT_DESKTOP_CLIENT` | 标记桌面客户端环境 | 打包态启动后端时写入 `1` |
 | `ASTRBOT_BACKEND_STARTUP_HEARTBEAT_PATH` | 桌面端写给后端启动器的 heartbeat 文件路径 | 打包态默认写到 `ASTRBOT_ROOT/data/backend-startup-heartbeat.json` |
 
+### 局域网访问 WebUI
+
+桌面端默认写入 `DASHBOARD_HOST=127.0.0.1`，因此 WebUI 默认仅允许本机访问。如果需要从同一局域网内的其他设备访问，推荐编辑 AstrBot 命令配置：
+
+```text
+~/.astrbot/data/cmd_config.json
+```
+
+Windows 对应路径通常为 `C:\Users\<用户名>\.astrbot\data\cmd_config.json`。
+
+```json
+{
+  "dashboard": {
+    "host": "0.0.0.0",
+    "port": 6185
+  }
+}
+```
+
+设置后需要完全退出并重新启动 AstrBot Desktop，再通过 `http://<主机内网 IP>:6185/` 访问。开启前请确认系统防火墙允许端口 `6185`，并避免在不可信网络或公网环境暴露该端口。如需恢复默认本机访问，可将 `dashboard.host` 设回 `127.0.0.1` 后重启应用。
+
+环境变量优先级高于 `cmd_config.json`。如果同时设置了 `ASTRBOT_DASHBOARD_HOST` / `DASHBOARD_HOST` 或 `ASTRBOT_DASHBOARD_PORT` / `DASHBOARD_PORT`，桌面端会优先保留环境变量值。
+
 ## 4. 发布/CI（GitHub Actions）
 
 | 变量 | 用途 | 默认值/行为 |