# 远程服务与 GUI

> 触发词：serve、gui、FastAPI、uvicorn、远程调试
> 返回索引：[SKILL.md](../SKILL.md)

## 依赖安装

GUI 依赖安装详见 [references/install.md](install.md) 的「GUI 依赖」章节。


## Web GUI（浏览器模式）

### serve — 远程调试服务器

```powershell
python -m mklink serve --host 127.0.0.1 --port 8765
# 启动 FastAPI 服务器，访问 http://127.0.0.1:8765/docs 查看 API 文档

# 远程/局域网访问必须加 token；不要暴露到公网
python -m mklink serve --host 0.0.0.0 --port 8765 --token <随机长 token>
```

选项：
- `--backend {legacy,fastapi}` — 选择后端（默认 fastapi）
- `--project-root <dir>` — 指定项目根目录
- `--token <token>` — 客户端认证 Token；绑定非 `127.0.0.1` / `localhost` 时必须指定
- `--device-port COM6` — 启动时自动连接指定 MKLink 端口
- `--axf path/to/firmware.axf` — 自动连接时加载 AXF/ELF 符号文件

### gui — 一键启动 Web GUI

```powershell
# 一键启动（托管预构建前端、启动后端、打开浏览器）
python -m mklink gui

# 指定端口和设备
python -m mklink gui --port 8765 --device-port COM6

# 远程访问 GUI 必须加 token；不要暴露到公网
python -m mklink gui --host 0.0.0.0 --port 8765 --token <随机长 token>

# 不自动打开浏览器
python -m mklink gui --no-browser
```

安全边界：`serve` / `gui` 提供烧录、擦除、halt/resume、读写内存等硬件控制 API。默认只绑定 `127.0.0.1`。如果用户要求绑定 `0.0.0.0`、局域网 IP 或远程访问，Agent 必须要求 `--token`，并提醒不要暴露到公网。

GUI 启动后在浏览器中提供两个页面：
- **配置页** (`/config`) — COM 口选择、MCU 配置、项目初始化
- **仪表盘页** (`/dashboard`) — RTT View、烧录、调试控制、串口、Modbus、SuperWatch


## 桌面应用说明

当前包只提供浏览器 Web GUI 和预构建 `gui/dist/` 静态资源，不包含 `package.json`、Tauri `src-tauri/` 工程或前端源码。如果 `gui/dist/` 缺失，请重新获取完整发布包；除非用户另外提供完整前端源码，否则不要执行 `npm install`、`npx tauri dev` 或 Tauri 打包命令。


## Dashboard 生命周期

GUI 仪表盘中 RTT / Serial / Modbus / SuperWatch 均以独立子进程启动，通过 iframe 嵌入：

| Dashboard | 端口 | CLI 命令 |
|-----------|------|----------|
| RTT View | 8081 | `python -m mklink rtt --visualize` |
| Serial | 8084 | `python -m mklink serial dashboard` |
| Modbus | 8085 | `python -m mklink modbus dashboard` |
| SuperWatch | 8086 | `python -m mklink superwatch --visualize` |

API 端点：
- `POST /api/dashboard/start` — 启动 Dashboard（body: `{"type": "rtt|serial|modbus|superwatch"}`）
- `POST /api/dashboard/stop` — 停止 Dashboard
- `GET /api/dashboard/status` — 查询所有 Dashboard 运行状态

## 资源管理 API

FastAPI 后端维护 `mklink_bridge`、`serial_port`、`modbus_port` 三类资源租约。串口/Modbus dashboard 启动后会登记租约；停止或强制释放时会同时关闭对应后台 manager，避免虚拟串口被占用后无法释放。

注意：REST API 是 GUI/dashboard 的 HTTP 包装层。Agent 或命令行释放本地串口资源时优先使用 CLI，不需要启动 FastAPI：

```powershell
python -m mklink resources status --port COM3
python -m mklink resources release-serial --port COM3
```

常用端点：

- `GET /api/resources/status` — 查询当前资源占用。
- `POST /api/resources/release-serial` — 释放当前 `serial_port` 持有者；用于串口 dashboard 占用虚拟串口时的一键释放。
- `POST /api/resources/release` — 按 owner 或 resource 释放，例如 `{"owner":"user:dashboard:serial"}` 或 `{"resource":"serial_port"}`。
- `POST /api/resources/release-all` — 停止所有已登记 dashboard 并释放全部租约。

示例：

```powershell
curl http://127.0.0.1:8765/api/resources/status
curl -X POST http://127.0.0.1:8765/api/resources/release-serial -H "Content-Type: application/json" -d "{}"
curl -X POST http://127.0.0.1:8765/api/resources/release -H "Content-Type: application/json" -d "{\"resource\":\"serial_port\"}"
```
