feat: OpsxAPI v1.0 全协议接口工作台

- 六协议调试：HTTP/GraphQL/WebSocket/SSE/Socket.IO/MQTT - 集合树/多标签/多环境变量/历史记录，localStorage 持久化 - 导入：OpenAPI 2/3/3.1、Postman、Apifox、Apipost、cURL、HAR、 Insomnia、Hoppscotch、Markdown（自动识别，21 个单测覆盖） - 导出：OpenAPI 3.0 JSON/YAML、Postman v2.1、Markdown 文档、全量备份；单请求生成 cURL/fetch/Python/Go 代码 - Gin 服务：HTTP 代理、NDJSON 流式代理（SSE 透传）、 WebSocket 隧道（浏览器自定义握手 Header） - 内置产品官网 /home 与用户文档站 /docs（SSR，随二进制交付） - lucide 图标体系 + 品牌标识（Logo/favicon），明暗双主题 - 环境变量：彩色徽标切换器、管理弹窗、{{ 自动补全
2026-09-18 00:16:59 +08:00
commit dec66db5aa
@@ -0,0 +1,36 @@
+OpsxAPI 是一款**本地优先**的专业接口工作台，面向运维与开发，把 HTTP、GraphQL、WebSocket、SSE、Socket.IO、MQTT 六种协议的调试放进同一个窗口。
+
+无需注册、无需联网同步，数据全部保存在本地浏览器（localStorage），导出备份随时带走。
+
+## 功能总览
+
+| 能力 | 说明 |
+| --- | --- |
+| 六种协议 | HTTP / GraphQL / WebSocket / SSE / Socket.IO / MQTT |
+| 集合管理 | 目录树、搜索、右键菜单、拖拽移动、多标签页 |
+| 多环境变量 | `{{baseUrl}}`、`{{token}}` 全局替换，一键切换环境 |
+| 数据导入 | OpenAPI/Swagger、Postman、Apifox、Apipost、cURL、HAR、Insomnia、Hoppscotch、Markdown 等 |
+| 数据导出 | OpenAPI 3.0、Postman v2.1、Markdown 文档、全量备份 |
+| 代码生成 | cURL / JavaScript fetch / Python requests / Go net/http |
+| 代理能力 | 本地 Gin 代理绕开 CORS；WebSocket 隧道支持自定义握手 Header |
+| 双端形态 | 浏览器（Web）与桌面端（Tauri）共用同一套界面 |
+
+## 支持的协议与场景
+
+| 协议 | 典型场景 | 特色 |
+| --- | --- | --- |
+| HTTP / REST | 调试 REST 接口、运维平台 API | 7 种方法、6 种请求体、3 种鉴权 |
+| GraphQL | 查询网关、中台接口 | Query + Variables 独立编辑 |
+| WebSocket | 实时推送、行情、IM | 自定义握手 Header（经本地隧道） |
+| SSE | AI 流式输出、监控事件流 | 直连失败自动切代理、断点续传 |
+| Socket.IO | Node 实时应用 | 事件监听、emit 参数、path/auth 配置 |
+| MQTT | IoT 设备、消息总线 | 通配符订阅、QoS、自动重连 |
+
+## 为什么选 OpsxAPI
+
+- **数据主权**：所有集合、环境、历史保存在本机，不经过任何第三方服务器。
+- **开箱即用**：`./run.sh web` 一条命令启动；首次打开自带覆盖全部协议的示例集合。
+- **工程友好**：导入自动建目录、路径参数自动转变量；导出即标准 OpenAPI，可回流 Apifox / Swagger 生态。
+- **轻量克制**：一个 Go 二进制 + 一份前端，资源占用小，内网可部署。
+
+> **提示**：想快速感受？直接看下一章《快速开始》，30 秒发出第一个请求。
@@ -0,0 +1,48 @@
+## 环境要求
+
+| 组件 | 版本 | 用途 |
+| --- | --- | --- |
+| Node.js | ≥ 20 | Web 前端（Vite） |
+| Go | ≥ 1.23 | 本地代理服务（Gin） |
+| Rust + Cargo | 可选 | 仅编译桌面端（Tauri）时需要 |
+
+## 启动
+
+```bash
+git clone <你的仓库地址> opsxapi
+cd opsxapi
+make install     # 安装依赖（npm install，含桌面端）
+
+./run.sh web     # 启动：Gin(:8787) + Web UI(:5173)
+```
+
+看到下面的输出即可打开浏览器：
+
+```bash
+[OK] 后端 UP  http://127.0.0.1:8787/health
+[OK] Web UP  http://127.0.0.1:5173
+```
+
+| 命令 | 说明 |
+| --- | --- |
+| `./run.sh web` | 浏览器版（推荐） |
+| `./run.sh gui` | 桌面窗口（Tauri，共用同一 UI） |
+| `./run.sh all` | Web + 桌面一起开 |
+| `./run.sh status` / `stop` | 查看状态 / 停止 |
+
+## 30 秒发出第一个请求
+
+1. 打开 <http://127.0.0.1:5173>，左侧是内置的「示例集合」。
+2. 点击 **HTTP · httpbin → 获取请求回显**。
+3. 点击右上角 **发送**。
+4. 下方响应区显示 `200`、耗时与 JSON 高亮响应体 —— 完成！
+
+## 桌面端（可选）
+
+```bash
+./run.sh gui
+```
+
+桌面端复用同一份界面与数据通道，HTTP 请求走 Tauri 原生网络栈，不依赖浏览器 CORS。
+
+> **提示**：首次打开会自动创建两个环境（正式 / 本地）和一个覆盖全部协议的示例集合，可随时在「设置」中重置。
@@ -0,0 +1,41 @@
+OpsxAPI 主界面分为五个区域：
+
+## 顶栏
+
+| 元素 | 作用 |
+| --- | --- |
+| ＋ 新建 | 快捷创建各协议请求 / 目录（默认建在第一个集合） |
+| 导入 / 导出 | 打开数据导入、导出对话框 |
+| 环境选择器 | 切换当前环境（变量随之生效），「⚙ 环境」管理环境与变量 |
+| 🌙 / ☀️ | 明暗主题切换 |
+| ⋯ | 设置（主题、超时、重置工作区） |
+
+## 左侧集合树
+
+- 点击请求 → 在标签页中打开；点击目录 → 展开 / 折叠。
+- **右键**任意节点：新建、重命名、复制、导出、删除。
+- **拖拽**请求或目录到另一个目录，即可移动（支持跨集合）。
+- 顶部搜索框按名称 / 方法 / URL 实时过滤。
+- 底部为**历史记录**：显示最近请求的状态码与耗时，点击可回跳到对应接口。
+
+## 标签页栏
+
+同时打开多个接口，中键或 × 关闭；右键支持「关闭其他 / 关闭全部」。正在连接中的实时协议标签会显示呼吸圆点。
+
+## 请求编辑区（上半部分）
+
+按协议呈现不同编辑器：
+
+| 协议 | 标签页 |
+| --- | --- |
+| HTTP | Params · Body · Headers · Cookies · Auth · 说明 |
+| GraphQL | Query · Variables · Headers · Auth |
+| WebSocket | 消息 · 握手配置 · 说明 |
+| SSE | 事件流 · 连接配置 · 说明 |
+| Socket.IO | 事件 · 连接配置 · 说明 |
+| MQTT | 消息 · Broker / 订阅 · 发布 · 说明 |
+
+## 响应区（下半部分）
+
+- **HTTP / GraphQL**：响应体（Pretty JSON 高亮）、Raw、响应头，右上角状态 / 耗时 / 大小 / 复制。
+- **实时协议**：分色消息日志（接收 · 绿、发送 · 蓝、系统 · 灰、错误 · 红），顶部实时统计收发条数与连接时长。
@@ -0,0 +1,47 @@
+## 发送请求
+
+1. 选择方法（GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS）。
+2. 输入 URL，支持 `{{baseUrl}}/path` 形式的变量（见《环境与变量》）。
+3. 点击 **发送**，或直接在 URL 输入框按 **Enter**。
+
+请求默认经本地 Gin 代理（`/v1/proxy/http`）发出，天然绕开浏览器 CORS 限制。
+
+## Params（查询参数）
+
+键值对编辑器，每行可勾选启用 / 停用、填写说明。URL 中已有的查询串会被拆分到表格里，两边双向同步。
+
+## Body（请求体）
+
+| 模式 | 适用场景 |
+| --- | --- |
+| none | GET 等无体请求 |
+| JSON | REST 接口（默认自动补 `Content-Type: application/json`，带格式化按钮） |
+| XML / Text / HTML | 原始报文 |
+| x-www-form-urlencoded | 表单提交 |
+| form-data | multipart 文本字段（文件上传请用代码生成的 cURL） |
+
+## Headers / Cookies
+
+- Headers：键值对，支持 `{{变量}}`；`Authorization`、`Cookie` 由 Auth / Cookies 标签统一管理时避免重复。
+- Cookies：键值对，发送时自动拼接为 `Cookie` 请求头。
+
+## 代码生成
+
+点击 URL 栏右侧 **`</>` 代码**，可生成：
+
+- cURL（可直接在终端执行）
+- JavaScript fetch
+- Python requests
+- Go net/http
+
+生成内容保留 `{{变量}}` 原样，便于粘贴到脚本后再替换。
+
+## 响应面板
+
+| 标签 | 内容 |
+| --- | --- |
+| 响应体 | JSON 自动格式化 + 语法高亮；其他类型原样展示 |
+| Raw | 未格式化的原始文本 |
+| 响应头 | 全部响应头表格 |
+
+右上角常驻 **状态码 / 耗时 / 大小 / Content-Type**，并提供「复制体」按钮。
@@ -0,0 +1,29 @@
+在 HTTP / GraphQL / SSE 请求的 **Auth** 标签中选择鉴权方式：
+
+## Bearer Token
+
+```text
+Authorization: Bearer <token>
+```
+
+Token 支持 `{{token}}` 变量引用 —— 推荐把 token 放进环境变量，一次配置全局生效。
+
+## Basic Auth
+
+填写用户名 / 密码，自动进行 Base64 编码后放入 `Authorization` 头。
+
+## API Key
+
+| 字段 | 说明 |
+| --- | --- |
+| Key 名 | 如 `X-API-Key` |
+| 值 | 支持 `{{变量}}` |
+| 位置 | Header（默认）或 Query 参数 |
+
+## 组合规则
+
+- 鉴权产生的 Header 会与 Headers 标签中的同名项合并（鉴权优先）。
+- API Key 放 Query 时，会追加到 Params，不会重复出现在 Headers。
+- 导入 OpenAPI / Postman 时，文档中声明的 `securitySchemes` 会自动映射到对应鉴权方式。
+
+> **注意**：鉴权信息保存在本地集合数据中。如需分享集合，请先通过「导出」审查是否包含敏感 token。
@@ -0,0 +1,50 @@
+## 变量语法
+
+在 URL、Params、Headers、Cookies、Body、鉴权字段中，使用双花括号引用变量：
+
+```text
+{{baseUrl}}/v1/users?page={{page}}
+Authorization: Bearer {{token}}
+```
+
+发送时统一替换为**当前启用环境**中同名变量的值；未定义的变量保留原样，便于发现遗漏。
+
+## 切换环境
+
+顶栏环境切换器显示**彩色单字徽标 + 环境名 + 变量数**，点击弹出环境列表（当前环境带「当前」标记），一眼防误发；底部可进入「管理环境」或「不使用环境」。
+
+## 管理环境
+
+顶栏 **环境** 按钮打开管理弹窗（左侧环境列表 + 右侧编辑区）：
+
+- **左栏**：环境列表（徽标 + 名称 + 当前标记），底部虚线按钮新建环境。
+- **右栏**：提示条（变量引用语法 + 文档直达）、环境重命名、设为当前 / 取消使用、**复制环境**、删除；变量表支持**按名称 / 描述搜索**、逐行启用停用、内联编辑。
+- 所有修改即时生效并自动保存。
+
+## 输入 {{ 自动补全
+
+在 URL 输入框或任意「值」输入框键入 `{{`，会弹出当前环境的变量浮层：
+
+- ↑↓ 选择、Enter / Tab 插入完整的 `{{变量名}}`；Esc 关闭。
+- 浮层同时显示变量值，选之前即可确认。
+
+内置示例环境：
+
+| 环境 | baseUrl | token |
+| --- | --- | --- |
+| 正式 | `https://httpbin.org` | demo-token |
+| 本地 | `http://127.0.0.1:8787` | dev-token |
+
+## 变量从哪来自动生成
+
+| 来源 | 行为 |
+| --- | --- |
+| 导入 OpenAPI / Swagger | `servers` 地址写入 `baseUrl`；路径参数 `{id}` 转为 `{{id}}` 并写入示例值 |
+| 导入 Postman | `collection.variable` 写入当前环境 |
+| 手动输入 | 在环境面板随时增改 |
+
+## 实际地址预览
+
+URL 含 `{{ }}` 时，编辑器会在 URL 栏下方实时显示替换后的实际地址，切换环境立即更新。
+
+> **提示**：路径参数用变量而不是写死，是接口可复用的关键 —— 复制接口后只改变量值即可调试另一个资源。
@@ -0,0 +1,32 @@
+## 编辑查询
+
+GraphQL 请求由三部分组成：
+
+| 部分 | 说明 |
+| --- | --- |
+| Query | GraphQL 查询语句，支持变量定义 `$code: ID!` |
+| Variables | JSON 对象，随查询一起发送；非法 JSON 会红框提示 |
+| Headers / Auth | 与 HTTP 请求一致 |
+
+## 发送
+
+点击 **执行**（或 URL 栏按 Enter）。实际发送的是标准 GraphQL over HTTP：
+
+```json
+{
+  "query": "query ($code: ID!) { country(code: $code) { name capital currency } }",
+  "variables": { "code": "CN" }
+}
+```
+
+响应面板会自动格式化 `data` / `errors`，字段名高亮。
+
+## 内置示例
+
+示例集合中的「国家查询 · countries」连接公共 GraphQL 服务 <https://countries.trevorblades.com/graphql>，无需鉴权，可直接体验。
+
+## 最佳实践
+
+- 把 endpoint 存为 `{{baseUrl}}/graphql`，环境切换即切换网关。
+- 需要鉴权时在 Auth 标签配置 Bearer，不必手写 Header。
+- 想看实际报文？点 `</>` 代码 生成 cURL，即为此查询的完整 HTTP 请求。
@@ -0,0 +1,34 @@
+## 连接
+
+1. 填写 `ws://` 或 `wss://` 地址。
+2. 点击 **连接**；状态点变绿（已连接）后即可收发消息。
+3. 再次点击按钮即断开。
+
+## 消息收发
+
+- **消息日志**：接收（绿）/ 发送（蓝）/ 系统（灰）/ 错误（红）分色展示，顶部统计 ↑↓ 条数与连接时长。
+- **发送框**：支持 JSON / 纯文本；**⌘/Ctrl + Enter** 快速发送；「格式化 JSON」一键美化。
+
+## 子协议
+
+「握手配置」标签中的**子协议**填逗号分隔列表，例如：
+
+```text
+graphql-transport-ws, v1.json
+```
+
+## 自定义握手 Header（隧道模式）
+
+浏览器原生 WebSocket **不能**携带自定义 Header（如 `Authorization`、`X-API-Key`）。OpsxAPI 的处理方式：
+
+1. 「握手配置」中填写 Header 后，工具自动改走**本地 Gin 隧道**：
+   - 浏览器 → Gin `/v1/proxy/ws/attach`（普通 WS）
+   - Gin → 目标服务器（携带你填的全部 Header）
+2. 不填 Header 时直连目标，零额外开销。
+
+> **注意**：隧道要求本地 Gin 服务（:8787）在运行，即用 `./run.sh web` / `gui` 启动的默认形态。
+
+## 调试技巧
+
+- 消息过多时点「清空」；日志上限 500 条，超出自动滚动淘汰。
+- 把常用报文保存在「说明」里，或为不同报文建多个 WS 请求节点。
@@ -0,0 +1,29 @@
+## 连接事件流
+
+1. 填写 SSE 地址（如 `https://stream.wikimedia.org/v2/stream/recentchange`）。
+2. 点击 **连接**，事件按到达顺序流入消息日志。
+3. 每条消息按 `event:` 名称归类显示；`data` 为 JSON 时自动格式化。
+
+## 直连与代理自动切换
+
+- 默认**直连**目标站（fetch 流式读取，延迟最低）。
+- 直连因 CORS / 网络失败时，自动降级走**本地 Gin 流式代理**，日志中会提示切换过程，无需手工干预。
+
+## 断点续传（Last-Event-ID）
+
+「连接配置」中填写 Last-Event-ID，连接时以 `Last-Event-ID` 请求头携带，支持断点续传的流会在该事件之后继续推送。
+
+## 连接配置项
+
+| 配置 | 说明 |
+| --- | --- |
+| Query 参数 / Headers | 以键值对附加 |
+| Last-Event-ID | 断点续传游标 |
+| 仅显示 data 内容 | 开启后只显示 `data:` 载荷；关闭则连同 `event:` 名称一起显示 |
+| 鉴权 | 与 HTTP 相同（Bearer / Basic / API Key） |
+
+## 典型场景
+
+- LLM 流式输出接口（`text/event-stream`）
+- 监控 / 审计事件流
+- 需要长期挂机观察的推送通道
@@ -0,0 +1,45 @@
+## 连接
+
+1. 填写服务地址（**不含** `/socket.io` 路径），如 `http://127.0.0.1:3000`。
+2. 点击 **连接**，状态变为「已连接」后即可收发事件。
+
+## 监听事件
+
+「连接配置」→ **监听事件** 填逗号分隔的事件名：
+
+```text
+message, notification
+```
+
+留空则接收全部服务端事件（onAny 模式）。事件名在每条日志中标注。
+
+## 发送（emit）
+
+「事件」标签底部的发送区：
+
+- **事件名**：如 `message`
+- **参数**：JSON 数组，作为 `socket.emit(event, ...args)` 的参数
+
+```json
+["hello", 42]
+```
+
+## 连接选项
+
+以 JSON 配置传给 socket.io-client：
+
+```json
+{
+  "path": "/socket.io",
+  "transports": ["websocket"],
+  "auth": { "token": "{{token}}" }
+}
+```
+
+| 选项 | 说明 |
+| --- | --- |
+| path | 服务端挂载路径，默认 `/socket.io` |
+| transports | `websocket` / `polling`，默认两者皆可 |
+| auth | 握手鉴权载荷，支持 `{{变量}}` |
+
+> **提示**：浏览器直连外部站点同样受 CORS 限制，Socket.IO 服务端需配置对应 origin，或把服务与本工具部署在同源下。
@@ -0,0 +1,41 @@
+## 连接 Broker
+
+浏览器环境要求 **WebSocket 形式**的 Broker 地址：
+
+```text
+wss://broker.emqx.io:8084/mqtt
+```
+
+| 配置 | 说明 |
+| --- | --- |
+| 用户名 / 密码 | 可选，支持 `{{变量}}` |
+| ClientId | 默认随机生成；同一 Broker 上必须唯一 |
+| QoS | 0 至多一次 · 1 至少一次 · 2 恰好一次 |
+
+## 订阅
+
+「Broker / 订阅」中填写逗号分隔的主题，支持通配符：
+
+```text
+opsxapi/demo, sensor/+, home/#
+```
+
+> **注意**：订阅在**建立连接时**生效，修改主题后需断开重连。
+
+## 发布
+
+「发布」标签配置主题与 Payload（JSON / 纯文本），点击发布按钮即送达；已发布消息以蓝色出现在日志中并标注主题。
+
+## 公共测试 Broker
+
+| Broker | 地址 |
+| --- | --- |
+| EMQX | `wss://broker.emqx.io:8084/mqtt` |
+| HiveMQ | `wss://broker.hivemq.com:8884/mqtt` |
+
+两个浏览器窗口连接同一主题，即可互相收发验证。
+
+## 行为说明
+
+- 断线自动重连（3 秒间隔），状态点显示「重连中」。
+- 消息日志上限 500 条；QoS 与主题逐条标注。
@@ -0,0 +1,40 @@
+顶栏 **导入** 打开导入对话框，支持三种来源：
+
+| 来源 | 说明 |
+| --- | --- |
+| 粘贴文本 / cURL | 直接粘贴任意受支持格式的内容 |
+| 文件导入 | 选择或拖入 `.json` / `.yaml` / `.har` / `.md` / `.txt` |
+| URL 导入（Swagger） | 填写 OpenAPI 地址，经本地 Gin 代理拉取，避开 CORS |
+
+格式**自动识别**，也可手动指定。
+
+## 支持格式
+
+| 格式 | 细节 |
+| --- | --- |
+| OpenAPI 3.0 / 3.1、Swagger 2.0 | JSON 或 YAML；Apifox 导出的 OpenAPI 同样适用 |
+| Postman Collection | v2.0 / v2.1，含鉴权、变量、GraphQL body |
+| Apipost 项目 | `api_collection` 格式（宽容解析） |
+| cURL | 引号、续行、`-d` / `-F` / `-u` / `--data-urlencode`、cookie、代理等参数 |
+| HAR | 按域名分组、相同请求去重 |
+| Insomnia | 导出文件 v3 / v4，含 workspace / group 层级 |
+| Hoppscotch | 集合 JSON（数组或单对象） |
+| Markdown | 提取文中的 ```curl 代码块 |
+| OpsxAPI 备份 | 全量集合 + 环境，用于迁移恢复 |
+
+YApi、Apidoc、Apizza、Eolink 请先在原平台导出为 **OpenAPI 或 Postman** 格式，再导入本工具。
+
+## 导入时自动完成
+
+| 原始内容 | 转换结果 |
+| --- | --- |
+| OpenAPI `tags` | 目录分组 |
+| 路径参数 `/pets/{petId}` | `{{petId}}` 变量 + 环境示例值 |
+| `servers` 地址 | 当前环境 `baseUrl` 变量 |
+| requestBody schema | JSON 示例请求体 |
+| securitySchemes | Bearer / Basic / API Key 鉴权配置 |
+| Postman `variable` | 当前环境变量 |
+
+## 结果确认
+
+导入完成显示汇总：新建集合、接口数量、写入的环境变量与告警（如跳过的文件上传字段）。集合名重复时自动追加序号。
@@ -0,0 +1,30 @@
+顶栏 **导出**（多集合时可选择目标集合）：
+
+| 格式 | 用途 |
+| --- | --- |
+| OpenAPI 3.0 · JSON / YAML | 回流 Apifox、Swagger UI、代码生成器 |
+| Postman v2.1 | 直接导入 Postman |
+| Markdown 接口文档 | 带目录、参数表格、请求体代码块，可放 Wiki |
+| 全量备份 | 全部集合 + 环境，用于迁移与灾备 |
+
+每种格式均支持**复制到剪贴板**与**下载文件**；对话框内实时预览导出内容。
+
+## 全量备份与恢复
+
+- 备份文件是包含 `__opsxapi__: "backup"` 标记的 JSON。
+- 恢复：导入对话框 → 粘贴备份内容或选择备份文件 → 格式自动识别为「OpsxAPI 备份」。
+
+## 代码生成（单请求）
+
+在 HTTP / GraphQL 编辑器点 **`</>` 代码**：
+
+| 目标 | 说明 |
+| --- | --- |
+| cURL | 含方法、头、体、cookie，可直接执行 |
+| JavaScript fetch | `async/await` 风格 |
+| Python requests | 含 `import requests` 完整脚本 |
+| Go net/http | 完整 `main` 函数 |
+
+`{{变量}}` 保留原样输出，方便接入你自己的配置体系。
+
+> **提示**：导出的 OpenAPI 中，目录名会成为 `tags`，请求说明写入 `description`，鉴权自动生成 `securitySchemes`。
@@ -0,0 +1,39 @@
+## 新建
+
+| 入口 | 行为 |
+| --- | --- |
+| 顶栏「＋ 新建」 | 快捷菜单，建在第一个集合 |
+| 树右键「新建请求 / 目录」 | 精确指定位置 |
+| 新建对话框 | 选择类型（六协议 + 目录）、命名、目标集合与目录 |
+
+接口名自动避免重复（追加序号）。
+
+## 集合树操作
+
+| 操作 | 方式 |
+| --- | --- |
+| 重命名 | 右键 → 重命名 |
+| 复制 | 右键 → 复制（深拷贝子树，名字加「副本」） |
+| 移动 | 拖拽到目标目录（支持跨集合） |
+| 删除 | 右键 → 删除（直接生效，请先备份重要数据） |
+| 搜索 | 侧栏搜索框，匹配名称 / 方法 / URL |
+
+## 标签页
+
+- 点击树节点在标签页打开；同时打开数量不限。
+- 中键 / × 关闭；右键「关闭其他 / 关闭全部」。
+- 关闭实时协议（WS / SSE / MQTT…）标签时自动断开连接。
+
+## 历史记录
+
+- 每次 HTTP / GraphQL 发送记录：时间、方法、接口名、状态码，失败标红。
+- 点击记录跳回对应接口；最多保留 100 条；可一键清空。
+
+## 数据存储与备份
+
+- 位置：浏览器 localStorage（键 `opsxapi.workspace.v2`），自动保存（防抖 400ms）。
+- 内容：集合、环境、历史、设置。标签页会话与实时消息不落盘。
+- 备份：导出 → 全量备份；恢复：导入备份文件。
+- 重置：设置 → 重置工作区（恢复初始示例，请先备份）。
+
+> **注意**：桌面端与浏览器是两份独立的 localStorage。跨端迁移请使用全量备份 / 导入。
@@ -0,0 +1,75 @@
+本地服务（Gin）默认监听 `:8787`，可用环境变量 `OPSXAPI_ADDR` 修改。所有端点仅监听本机回环，供 Web UI 与桌面端调用。
+
+## 端点总览
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/health` | 健康检查 |
+| POST | `/v1/proxy/http` | HTTP 代理（全方法、自定义头、超时） |
+| POST | `/v1/proxy/http/stream` | NDJSON 流式代理（SSE / chunked 透传） |
+| POST | `/v1/proxy/ws/connect` | 建立到目标 WS 的隧道会话 |
+| GET | `/v1/proxy/ws/attach` | 浏览器 attach 到隧道会话（双向桥接） |
+| POST | `/v1/proxy/ws/close` | 关闭隧道会话 |
+| GET | `/docs` | 本文档站 |
+
+## HTTP 代理
+
+```bash
+curl -s -X POST http://127.0.0.1:8787/v1/proxy/http \
+  -H 'Content-Type: application/json' \
+  -d '{"method":"GET","url":"https://httpbin.org/get","headers":{}}'
+```
+
+响应：
+
+```json
+{
+  "status": 200,
+  "headers": { "content-type": "application/json" },
+  "body": "{ ... }",
+  "timeMs": 320,
+  "size": 274
+}
+```
+
+请求体 `body.mode` 支持 `json` / `xml` / `text` / `html` / `urlencoded` / `form-data`，`raw` 为原始报文；`timeoutMs` 可选。
+
+## 流式代理
+
+请求体与 HTTP 代理一致，响应为 NDJSON 事件流：
+
+```text
+{"type":"meta","status":200,"headers":{...}}
+{"type":"chunk","data":"<base64>","size":1024}
+{"type":"end","timeMs":1200,"size":8192}
+```
+
+## WebSocket 隧道
+
+```bash
+# 1. 建立会话（可带自定义 Header）
+curl -s -X POST http://127.0.0.1:8787/v1/proxy/ws/connect \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"wss://echo.example.com","headers":{"Authorization":"Bearer t"}}'
+# → {"sessionId":"..."}
+
+# 2. 浏览器 / 客户端 attach（普通 WebSocket）
+#    ws://127.0.0.1:8787/v1/proxy/ws/attach?sessionId=...
+
+# 3. 关闭
+curl -s -X POST http://127.0.0.1:8787/v1/proxy/ws/close \
+  -H 'Content-Type: application/json' -d '{"sessionId":"..."}'
+```
+
+attach 后第一条消息为控制帧 `{"type":"open"}`；此后浏览器与目标服务器双向透传。
+
+## 安全边界
+
+- 仅允许 `http/https`（代理）与 `ws/wss`（隧道）目标。
+- 拒绝云元数据地址（169.254.169.254 等）防 SSRF。
+- 单响应上限 10 MiB；隧道会话 10 分钟无活动自动回收。
+
+## 部署建议
+
+- 开发：`./run.sh web`（Vite :5173 反代 `/v1`、`/docs` 到 :8787）。
+- 生产：`npm run build:web` 产物交给任意静态服务器，`opsxapi-server` 独立部署；生产环境建议置于内网并按需增加鉴权反向代理。
@@ -0,0 +1,45 @@
+## 请求报 CORS 错误？
+
+Web 端请求默认经本地 Gin 代理（gin-proxy）发出，不会遇到 CORS。若仍报错：
+
+- 确认 Gin 在运行：`curl http://127.0.0.1:8787/health`。
+- 用 `./run.sh web` / `gui` 场景启动（Vite 已配置 `/v1` 反代）。
+- 桌面端优先走 Tauri 原生网络栈，同样不受 CORS 限制。
+
+## 浏览器 WebSocket 不能加自定义 Header？
+
+规范限制。在 WS「握手配置」里填写 Header 后，OpsxAPI 自动改走本地 Gin 隧道（见《WebSocket》章节），Header 由 Gin 在握手时代为携带。不填 Header 则直连。
+
+## 外部 wss:// 地址连不上（DNS 失败）？
+
+本机网络环境可能限制部分域名解析。可先用 `curl -v wss://…` 或换用公共 echo 服务验证；自建服务请确认防火墙与证书。
+
+## MQTT 一定要 wss:// 吗？
+
+浏览器只能通过 WebSocket 连 MQTT。常见 Broker 的 WS 端口：EMQX `8084/mqtt`（TLS）、`8083/mqtt`（明文，仅 http 页面）。`mqtt://` TCP 直连仅在桌面原生环境可行。
+
+## 数据存在哪里？换电脑怎么办？
+
+集合 / 环境 / 历史保存在浏览器 localStorage。迁移：**导出 → 全量备份** 生成 JSON，在新设备 **导入** 即可。
+
+## 误删了接口 / 想回到初始状态？
+
+设置（顶栏 ⋯）→ 重置工作区，恢复内置示例集合。日常请养成导出备份的习惯。
+
+## SSE 事件流看着卡住了？
+
+- 事件频率低（如告警流）属正常，等待即可。
+- 部分网关会缓冲 SSE，工具会在直连失败时自动切换 Gin 流式代理；若仍无事件，检查中间层（Nginx 需关闭 `proxy_buffering`）。
+
+## 发送按钮点击后没反应？
+
+查看响应区是否有红色错误提示（如代理不可达）。`</>` 代码 生成 cURL 在终端执行可快速分辨是工具问题还是网络 / 接口问题。
+
+## 支持文件上传吗？
+
+form-data 当前支持文本字段；文件上传请用 `</>` 代码 生成的 cURL / 脚本执行。
+
+## 更多问题？
+
+- 服务端能力与边界：见《服务端 API 参考》
+- 各协议用法：见左侧「请求调试」分组
@@ -0,0 +1,41 @@
+{
+  "productVersion": "1.0",
+  "groups": [
+    {
+      "name": "开始使用",
+      "pages": [
+        { "file": "01-intro.md", "slug": "intro", "title": "产品介绍", "updated": "2026-09-17" },
+        { "file": "02-quickstart.md", "slug": "quickstart", "title": "快速开始", "updated": "2026-09-17" },
+        { "file": "03-interface.md", "slug": "interface", "title": "界面导览", "updated": "2026-09-17" }
+      ]
+    },
+    {
+      "name": "请求调试",
+      "pages": [
+        { "file": "04-http.md", "slug": "http", "title": "发送 HTTP 请求", "updated": "2026-09-17" },
+        { "file": "05-auth.md", "slug": "auth", "title": "接口鉴权", "updated": "2026-09-17" },
+        { "file": "06-env.md", "slug": "env", "title": "环境与变量", "updated": "2026-09-17" },
+        { "file": "07-graphql.md", "slug": "graphql", "title": "GraphQL", "updated": "2026-09-17" },
+        { "file": "08-websocket.md", "slug": "websocket", "title": "WebSocket", "updated": "2026-09-17" },
+        { "file": "09-sse.md", "slug": "sse", "title": "SSE 事件流", "updated": "2026-09-17" },
+        { "file": "10-socketio.md", "slug": "socketio", "title": "Socket.IO", "updated": "2026-09-17" },
+        { "file": "11-mqtt.md", "slug": "mqtt", "title": "MQTT", "updated": "2026-09-17" }
+      ]
+    },
+    {
+      "name": "数据管理",
+      "pages": [
+        { "file": "12-import.md", "slug": "import", "title": "数据导入", "updated": "2026-09-17" },
+        { "file": "13-export.md", "slug": "export", "title": "导出与代码生成", "updated": "2026-09-17" },
+        { "file": "14-manage.md", "slug": "manage", "title": "集合与历史", "updated": "2026-09-17" }
+      ]
+    },
+    {
+      "name": "参考",
+      "pages": [
+        { "file": "15-server-api.md", "slug": "server-api", "title": "服务端 API 参考", "updated": "2026-09-17" },
+        { "file": "16-faq.md", "slug": "faq", "title": "常见问题", "updated": "2026-09-17" }
+      ]
+    }
+  ]
+}