API Reference ko - FrankoonG/hy2scale GitHub Wiki

🌐 English | δΈ­ζ–‡ | ν•œκ΅­μ–΄

API 레퍼런슀

HY2 SCALE은 http://<호슀트>:5565/scale/api/ μ•„λž˜μ— REST APIλ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€. POST /api/login을 μ œμ™Έν•œ λͺ¨λ“  μ—”λ“œν¬μΈνŠΈλŠ” 둜그인으둜 얻은 μ„Έμ…˜ 토큰이 ν•„μš”ν•©λ‹ˆλ‹€.

인증

둜그인

POST /api/login

Body:

{
  "username": "admin",
  "password": "<sha256-hex-of-plaintext>"
}

λΉ„λ°€λ²ˆν˜ΈλŠ” 전솑 전에 ν΄λΌμ΄μ–ΈνŠΈμ—μ„œ SHA-256 ν•΄μ‹œλ©λ‹ˆλ‹€. μ„œλ²„λŠ” ν•΄μ‹œλ§Œ μ €μž₯ν•˜κ³  λΉ„κ΅ν•©λ‹ˆλ‹€.

응닡:

{
  "token": "hex-session-token",
  "force_password_change": false
}

force_password_change: trueλŠ” μ—¬μ „νžˆ κΈ°λ³Έ admin/admin 자격 증λͺ…을 μ‚¬μš© μ€‘μ΄λΌλŠ” μ˜λ―Έμž…λ‹ˆλ‹€ β€” μ›Ή UIλŠ” μ–΄λ–€ νŽ˜μ΄μ§€λ„ ν‘œμ‹œν•˜κΈ° 전에 λΉ„λ°€λ²ˆν˜Έ 변경을 κ°•μ œν•©λ‹ˆλ‹€.

토큰 μ‚¬μš©

이후 μš”μ²­μ€ Bearer ν—€λ”λ‘œ 토큰을 μ „λ‹¬ν•©λ‹ˆλ‹€:

Authorization: Bearer <token>

μž₯μ‹œκ°„ μœ μ§€λ˜λŠ” EventSource μ—”λ“œν¬μΈνŠΈ (특히 /api/graph-layout/stream)λŠ” μΆ”κ°€λ‘œ ?token=<hex> 쿼리 νŒŒλΌλ―Έν„°λ‘œλ„ 토큰을 λ°›μŠ΅λ‹ˆλ‹€. EventSourceλŠ” μ»€μŠ€ν…€ 헀더λ₯Ό μ„€μ •ν•  수 μ—†κΈ° λ•Œλ¬Έμž…λ‹ˆλ‹€.

Node

GET /api/node

이 λ…Έλ“œμ˜ 정체성과 Hysteria 2 μ„œλ²„ 섀정을 λ°˜ν™˜ν•©λ‹ˆλ‹€:

{
  "node_id": "ea1b2adb",
  "name": "sg-home",
  "exit_node": true,
  "hy2_user_auth": false,
  "compat": false,
  "limited": false,
  "server": {
    "listen": "0.0.0.0:5565",
    "password": "<hex>",
    "tls_cert": "/data/tls/default.crt",
    "tls_key": "/data/tls/default.key"
  },
  "version": "1.3.0"
}

PUT /api/node

λ…Έλ“œ 섀정을 κ΅μ²΄ν•©λ‹ˆλ‹€. ν¬ν•¨ν•œ ν•„λ“œλ§Œ μˆ˜μ •λ©λ‹ˆλ‹€.

GET /api/stats

{ "tx_bytes": 1234567890, "rx_bytes": 9876543210 }

Topology

GET /api/topology

μ΅œμƒμœ„ ν”Όμ–΄μ˜ 평면 배열을 λ°˜ν™˜ν•˜λ©°, 각 ν”Όμ–΄μ—λŠ” 쀑첩 κ²€μƒ‰μœΌλ‘œ λ³Ό 수 μžˆλŠ” ν”Όμ–΄λ“€μ˜ children νŠΈλ¦¬κ°€ ν¬ν•¨λ©λ‹ˆλ‹€. SelfλŠ” 항상 첫 번째이며 direction: "local", is_self: trueμž…λ‹ˆλ‹€.

[
  {
    "name": "ea1b2adb",
    "direction": "local",
    "latency_ms": 0,
    "is_self": true
  },
  {
    "name": "jp",
    "direction": "outbound",
    "connected": true,
    "latency_ms": 35,
    "nested": true,
    "version": "1.3.0",
    "tx_rate": 0,
    "rx_rate": 0,
    "children": [
      { "name": "jp-r1", "direction": "outbound", "latency_ms": 73 }
    ]
  }
]

Clients (μ•„μ›ƒλ°”μš΄λ“œ ν”Όμ–΄)

Method Path
GET /api/clients
POST /api/clients
PUT /api/clients/{name}
DELETE /api/clients/{name}
PUT /api/clients/{name}/disable β€” {"disabled": bool}

생성 Body:

{
  "name": "jp",
  "addr": "jp.example.com:5565",
  "addrs": ["jp.example.com:5565", "jp2.example.com:5565"],
  "password": "<hy2-password>",
  "sni": "jp.example.com",
  "insecure": false,
  "ca": "",
  "max_tx": 0,
  "max_rx": 0
}

Peers (쀑첩 검색)

Method Path μš©λ„
GET /api/peers/{name}/peers ν”Όμ–΄μ˜ μΊμ‹œλœ μ„œλΈŒ ν”Όμ–΄ λͺ©λ‘ 쑰회
PUT /api/peers/{name}/nested 이 ν”Όμ–΄μ˜ nested ν”Œλž˜κ·Έ ν† κΈ€

Nested Body:

{ "enabled": true }

{name}은 맨 이름 (직접 ν”Όμ–΄) λ˜λŠ” μ„œλΈŒ ν”Όμ–΄λ₯Ό κ°€λ¦¬ν‚€λŠ” /-ꡬ뢄 경둜 (us/us-east, kr/kr-r1/kr-r1-a …)일 수 μžˆμŠ΅λ‹ˆλ‹€.

Proxies

일반 ν”„λ‘μ‹œ λͺ©λ‘ (SOCKS5, HTTP, Shadowsocks):

Method Path
GET /api/proxies
POST /api/proxies
PUT /api/proxies/{id}
DELETE /api/proxies/{id}

생성 Body (SOCKS5 / HTTP / SS 곡톡 μŠ€ν‚€λ§ˆ):

{
  "id": "socks5",
  "protocol": "socks5",
  "listen": "0.0.0.0:1080",
  "enabled": true,
  "tls_cert": ""
}

Shadowsocks의 경우 "method": "aes-256-gcm"도 ν¬ν•¨ν•©λ‹ˆλ‹€.

L2TP / IKEv2 / WireGuard

각각 μ „μš© μ„€μ • μ—”λ“œν¬μΈνŠΈ 쌍이 μžˆμŠ΅λ‹ˆλ‹€:

ν”„λ‘œν† μ½œ GET / PUT
L2TP /api/l2tp
IKEv2 /api/ikev2
WireGuard /api/wireguard

PUT은 ν•« λ¦¬λ‘œλ“œλ₯Ό νŠΈλ¦¬κ±°ν•©λ‹ˆλ‹€ β€” μ„œλΉ„μŠ€κ°€ μ€‘μ§€λ˜κ³  μƒˆ μ„€μ •μœΌλ‘œ μž¬μ‹œμž‘ν•©λ‹ˆλ‹€.

WireGuard peers

Method Path
GET /api/wireguard (내뢀에 peers 포함)
POST /api/wireguard/peers
PUT /api/wireguard/peers/{name}
DELETE /api/wireguard/peers/{name}
GET /api/wireguard/peers/{name}/config (text/plain WireGuard .conf)
GET /api/wireguard/qr?peer={name} (PNG QR μ½”λ“œ)
POST /api/wireguard/generate-key ({private_key, public_key} λ°˜ν™˜)

Users

Method Path
GET /api/users
POST /api/users
PUT /api/users/{id}
DELETE /api/users/{id}
PUT /api/users/{id}/toggle
PUT /api/users/{id}/reset-traffic

생성 Body:

{
  "username": "alice",
  "password": "<plaintext or hashed>",
  "exit_via": "us/us-east",
  "exit_paths": ["us/us-east"],
  "exit_mode": "direct",
  "traffic_limit_gb": 500,
  "expiry": "2026-12-31T00:00:00Z",
  "enabled": true
}

Sessions

Method Path
GET /api/sessions
DELETE /api/sessions/{id} β€” kick, 60초 μž¬μ—°κ²° 차단

λΌμš°νŒ… κ·œμΉ™

Method Path
GET /api/rules
POST /api/rules
PUT /api/rules/{id}
DELETE /api/rules/{id}
PUT /api/rules/{id}/toggle

생성 Body:

{
  "id": "netflix",
  "name": "Netflix",
  "type": "domain",
  "targets": ["netflix.com"],
  "exit_via": "us",
  "exit_paths": ["us"],
  "exit_mode": "direct",
  "enabled": true
}

type은 "ip" λ˜λŠ” "domain"μž…λ‹ˆλ‹€.

TUN λͺ¨λ“œ

Method Path
GET /api/rules/tun-mode
PUT /api/rules/tun-mode

Body:

{ "enabled": true, "mode": "mixed" }

mode: "mixed" (κ·œμΉ™μ— 맀칭된 λŒ€μƒμ€ TUN을 톡해, κ·Έ μ™ΈλŠ” ν”„λ‘μ‹œλ₯Ό 톡해) λ˜λŠ” "full" (λͺ¨λ“  νŠΈλž˜ν”½μ΄ TUN을 톡해).

TLS

Method Path
GET /api/tls
POST /api/tls/import (body에 PEM)
POST /api/tls/import-path (body에 파일 경둜)
POST /api/tls/generate (자체 μ„œλͺ… λ˜λŠ” CA)
POST /api/tls/sign (κΈ°μ‘΄ CA둜 μ„œλͺ…)
GET /api/tls/{id}/pem (text/plain μΈμ¦μ„œ PEM)
DELETE /api/tls/{id}

POST /api/tls/generate Body:

{
  "id": "vpn-cert",
  "name": "vpn.sg.example",
  "domains": ["vpn.sg.example"],
  "days": 730,
  "is_ca": false
}

Graph layout

λ…Έλ“œ νŽ˜μ΄μ§€ κ·Έλž˜ν”„λŠ” λ…Έλ“œ μ’Œν‘œλ₯Ό μ„œλ²„ 츑에 μ €μž₯ν•˜μ—¬ 둜그인된 λͺ¨λ“  μ„Έμ…˜μ—μ„œ λ™μΌν•œ λ ˆμ΄μ•„μ›ƒμ„ 보게 ν•©λ‹ˆλ‹€.

Method Path μš©λ„
GET /api/graph-layout ν˜„μž¬ λ ˆμ΄μ•„μ›ƒ { key: {x, y} } 쑰회
PUT /api/graph-layout μƒˆ 맡으둜 λ ˆμ΄μ•„μ›ƒ ꡐ체
GET /api/graph-layout/stream SSE 슀트림 β€” μ—°κ²° μ‹œ ν˜„μž¬ λ ˆμ΄μ•„μ›ƒμ„ 내보내고 이후 λͺ¨λ“  λ³€μ΄λ§ˆλ‹€ λ°œν–‰

SSE μ΄λ²€νŠΈλŠ” GET 응닡과 λ™μΌν•œ ν˜•νƒœμ˜ JSON κ°μ²΄μž…λ‹ˆλ‹€.

λ°±μ—… / 볡원

Method Path
GET /api/backup
POST /api/restore

Build info

Method Path 인증 μš©λ„
GET /api/build-id μ—†μŒ λ‚΄μž₯ index.html의 sha256; SPAκ°€ 배포 μ‹œ μžλ™ λ¦¬λ‘œλ“œμ— μ‚¬μš©
GET /api/build-info 있음 전체 λΉŒλ“œ 정보: {version, license, repository, go_deps[], natives[]}

/api/build-infoλŠ” μ„€μ • β†’ Upgrade의 λΌμ΄μ„ μŠ€ + λ„€μ΄ν‹°λΈŒ μ»΄ν¬λ„ŒνŠΈ νŒ¨λ„μ„ κ΅¬λ™ν•©λ‹ˆλ‹€.

μ„€μ •

Method Path Body
PUT /api/settings/password {current_password, new_username?, new_password?} (λͺ¨λ‘ SHA-256)
GET /api/settings/ui 포트, κΈ°λ³Έ 경둜, DNS, μ„Έμ…˜ νƒ€μž„μ•„μ›ƒ λ°˜ν™˜
PUT /api/settings/ui UI μ„€μ • μ—…λ°μ΄νŠΈ

μ—…κ·Έλ ˆμ΄λ“œ

Method Path μš©λ„
POST /api/upgrade μƒˆ λ°”μ΄λ„ˆλ¦¬λ₯Ό ν¬ν•¨ν•˜λŠ” .tar.gzλ₯Ό multipart μ—…λ‘œλ“œ. μ„œλ²„κ°€ νŒŒμΌμ„ κ΅μ²΄ν•˜κ³  μž¬μ‹œμž‘ν•©λ‹ˆλ‹€.

μœ ν‹Έλ¦¬ν‹°

POST /api/check-ports

{ "ports": [5565, 1701, 500] }

응닡:

{ "results": { "5565": true, "1701": false, "500": false } }

trueλŠ” ν˜ΈμŠ€νŠΈμ—μ„œ ν•΄λ‹Ή ν¬νŠΈκ°€ λΉ„μ–΄ μžˆλ‹€λŠ” μ˜λ―Έμž…λ‹ˆλ‹€.

λ‚΄λΆ€ / 릴레이 ν”Œλ ˆμΈ μ—”λ“œν¬μΈνŠΈ

λ‹€μŒ μ—”λ“œν¬μΈνŠΈλŠ” 릴레이 ν”„λ‘œν† μ½œ μžμ²΄κ°€ λ…Έλ“œ κ°„ 쑰정을 μœ„ν•΄ μ‚¬μš©ν•©λ‹ˆλ‹€. μ›Ή UI 인증을 μ‚¬μš©ν•˜μ§€ μ•ŠμœΌλ©° β€” μ ‘κ·Ό μ œμ–΄λŠ” Hysteria 2 터널 λΉ„λ°€λ²ˆν˜Έλ‘œ μ΄λ€„μ§‘λ‹ˆλ‹€.

GET /api/internal/peers    β€” μ—­λ°©ν–₯ 쀑첩 검색을 μœ„ν•œ ν”Όμ–΄ λͺ©λ‘

μ™ΈλΆ€ μžλ™ν™”λ₯Ό μœ„ν•΄ μ„€κ³„λœ 것은 μ•„λ‹ˆλ©° β€” ν”„λ‘œν† μ½œ κ΅¬ν˜„μžλ₯Ό μœ„ν•΄ λ¬Έμ„œν™”λœ κ²ƒλΏμž…λ‹ˆλ‹€.

⚠️ **GitHub.com Fallback** ⚠️