# My Proxy Manager 接口文档

这份文档说明 `my-proxy-manager` 管理接口怎么请求、怎么更新代理程序、怎么回滚和验证。

如果只需要 `curl` 命令示例，请看：

```text
docs\CURL_API.md
```

## 基本信息

默认管理接口地址：

```text
http://服务器IP:18080
```

默认统一 token：

```text
td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No=
```

除 `/health` 外，其他接口都需要带认证头：

```text
Authorization: Bearer td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No=
```

## 接口列表

```text
GET  /health     检查 my-proxy-manager 是否存活
GET  /version    查看代理程序版本和 my-proxy 服务状态
POST /update     更新代理程序
POST /rollback   回滚到最近一次备份
POST /restart    重启 my-proxy 代理服务
```

## 1. 健康检查

用于确认 `my-proxy-manager` 服务是否在线。这个接口不需要 token。

```powershell
Invoke-RestMethod http://10.10.10.124:18080/health
```

正常返回示例：

```json
{
  "ok": true,
  "service": "my-proxy-manager",
  "time": "2026-06-16T17:38:55.9848247+08:00"
}
```

## 2. 查询版本

用于确认当前代理程序版本，以及 `my-proxy` 服务是否正在运行。

```powershell
$token = "td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No="

Invoke-RestMethod `
  -Uri "http://10.10.10.124:18080/version" `
  -Headers @{ Authorization = "Bearer $token" }
```

正常返回示例：

```json
{
  "ok": true,
  "version": "my-goproxy version v19",
  "serviceStatus": "Running"
}
```

## 3. 上传 exe 更新

这是推荐的更新方式：控制端本地有新版 `my-goproxy`，然后上传到指定服务器更新。

本地文件名可以随便叫，例如：

```text
my-goproxy-win64-v20.exe
new.exe
proxy-new.exe
```

远端服务器最终都会统一安装成：

```text
C:\app\my-proxy\my-goproxy-win64.exe
```

请求示例：

```powershell
$server = "10.10.10.124"
$token = "td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No="
$package = ".\my-goproxy-win64.exe"
$sha256 = (Get-FileHash $package -Algorithm SHA256).Hash

Invoke-RestMethod `
  -Uri "http://${server}:18080/update" `
  -Method Post `
  -Headers @{
    Authorization = "Bearer $token"
    "X-Proxy-Sha256" = $sha256
  } `
  -InFile $package `
  -ContentType "application/octet-stream"
```

服务器收到后会执行：

```text
保存上传的新 exe
校验 SHA256
停止 my-proxy 服务
备份旧的 C:\app\my-proxy\my-goproxy-win64.exe
用新 exe 覆盖 C:\app\my-proxy\my-goproxy-win64.exe
启动 my-proxy 服务
返回更新结果
```

正常返回示例：

```json
{
  "ok": true,
  "version": "my-goproxy version v19",
  "output": "[my-proxy] Using local package ... Started"
}
```

## 4. 通过 URL 更新

如果每台服务器都能访问同一个下载地址，也可以让服务器自己下载新版 exe。

适合把新版程序放到内网 HTTP、对象存储、CDN 后再更新。

```powershell
$token = "td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No="

Invoke-RestMethod `
  -Uri "http://10.10.10.124:18080/update" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body (@{
    url = "https://download.example.com/proxy/my-goproxy-win64.exe"
    sha256 = "新版EXE的SHA256"
  } | ConvertTo-Json -Compress)
```

请求体格式：

```json
{
  "url": "https://download.example.com/proxy/my-goproxy-win64.exe",
  "sha256": "新版EXE的SHA256"
}
```

## 5. 回滚

回滚会从下面目录里找最近一次备份：

```text
C:\app\my-proxy\releases
```

然后恢复旧版 exe 并重启 `my-proxy` 服务。

```powershell
$token = "td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No="

Invoke-RestMethod `
  -Uri "http://10.10.10.124:18080/rollback" `
  -Method Post `
  -Body "" `
  -Headers @{ Authorization = "Bearer $token" }
```

## 6. 重启代理服务

这个接口只重启 `my-proxy` 服务，不会重启 `my-proxy-manager`。

```powershell
$token = "td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No="

Invoke-RestMethod `
  -Uri "http://10.10.10.124:18080/restart" `
  -Method Post `
  -Body "" `
  -Headers @{ Authorization = "Bearer $token" }
```

## 7. 批量更新指定服务器

只更新你指定的服务器。例如只更新 3 台：

```powershell
$targets = @(
  "10.10.10.124",
  "10.10.10.125",
  "10.10.10.126"
)

$token = "td3oisW/OhYLweb1+Zb05WpO4/Gmc+BqYbaTs3I05No="
$package = ".\my-goproxy-win64.exe"
$sha256 = (Get-FileHash $package -Algorithm SHA256).Hash

foreach ($server in $targets) {
  try {
    $result = Invoke-RestMethod `
      -Uri "http://${server}:18080/update" `
      -Method Post `
      -Headers @{
        Authorization = "Bearer $token"
        "X-Proxy-Sha256" = $sha256
      } `
      -InFile $package `
      -ContentType "application/octet-stream"

    [pscustomobject]@{
      server = $server
      ok = $result.ok
      version = $result.version
    }
  } catch {
    [pscustomobject]@{
      server = $server
      ok = $false
      error = $_.Exception.Message
    }
  }
}
```

## 8. 验证代理端口

管理接口端口：

```text
18080
```

代理端口：

```text
9001 SOCKS
9002 HTTP
9003 HTTPS
8001 Magic HTTP
8002 Magic HTTPS
```

测试 HTTP 代理：

```powershell
curl.exe --proxy-user "用户名:密码" -x http://10.10.10.124:9002 http://ip.sb
```

测试 SOCKS 代理：

```powershell
curl.exe --socks5 用户名:密码@10.10.10.124:9001 http://ip.sb
```

`8001` 和 `8002` 是 magic 代理端口，需要用 `Obc-Use-IP` 指定本机出口 IP：

```powershell
curl.exe `
  --proxy-user "用户名:密码" `
  -x http://10.10.10.124:8001 `
  -H "Obc-Use-IP: 出口IP" `
  http://ip.sb
```

普通代理测试优先看 `9002`。`9002` 能返回出口 IP，就说明 HTTP 代理可用。

## 9. 常见错误

`401 Unauthorized`：

```text
没有带 Authorization，或者 token 不正确。
```

`407 Proxy Authentication failed`：

```text
代理端口通了，但代理用户名/密码不正确，或者没有带代理认证。
```

`TcpTestSucceeded: False`：

```text
端口不通，通常是 Windows 防火墙、安全组、服务没监听导致。
```

`SERVER_IP 无法解析`：

```text
命令里的 SERVER_IP 是占位符，需要替换成真实服务器 IP。
```
