本地服务默认监听 `: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 分钟无活动自动回收。

## 部署建议

- 私有化交付随授权提供发行包（`opsxapi-server` 单二进制 + 官网静态资源），解压即用，不依赖源码与构建工具链；
- 生产环境建议置于内网，并按需增加鉴权反向代理；数据目录（SQLite）做好备份策略。