HTTP API

当使用 --api-key 标志启用时，LinkSocks 服务器提供用于动态令牌管理和服务器监控的 HTTP API。

快速开始

启用 API

# 启用 API 启动服务器
linksocks server --api-key your_secret_api_key

API 将在与 WebSocket 服务器相同的主机和端口上可用（默认：http://localhost:8765）。

基本用法

# 获取服务器状态
curl -H "X-API-Key: your_secret_api_key" \
     http://localhost:8765/api/status

# 添加正向令牌
curl -X POST \
     -H "X-API-Key: your_secret_api_key" \
     -H "Content-Type: application/json" \
     -d '{"type":"forward","token":"my_token"}' \
     http://localhost:8765/api/token

# 删除令牌
curl -X DELETE \
     -H "X-API-Key: your_secret_api_key" \
     http://localhost:8765/api/token/my_token

身份验证

所有 API 请求都需要包含您配置的 API 密钥的 X-API-Key 头：

X-API-Key: your_secret_api_key

可在服务器启动时通过 ServerOption.WithAPIKeys(map[string][]AccessRule) 注册附加 API 密钥。每个附加密钥可绑定自己的默认目标规则：使用该密钥创建令牌且未显式指定 rules 时,令牌继承该密钥的规则。主 --api-key 密钥本身不携带规则。

错误响应

如果身份验证失败，API 返回：

{
  "success": false,
  "error": "invalid API key"
}

端点概述

方法	端点	描述
GET	/api/status	获取服务器状态和令牌列表
POST	/api/token	添加新令牌
DELETE	/api/token/{token}	通过 URL 路径删除令牌
DELETE	/api/token	通过请求主体删除令牌
GET	/api/config/access	获取服务器级全局入口/出站规则
PUT	/api/config/access	更新服务器级全局入口/出站规则

服务器状态

GET /api/status

返回服务器版本和所有令牌列表及其类型和活跃客户端计数。

响应：

{
  "version": "3.0.12",
  "tokens": [
    {
      "token": "forward_token_123",
      "type": "forward", 
      "clients_count": 2
    },
    {
      "token": "reverse_token_456",
      "type": "reverse",
      "clients_count": 1,
      "port": 9870,
      "connector_tokens": ["connector_abc", "connector_def"]
    }
  ]
}

令牌对象字段：

• token（字符串）：身份验证令牌
• type（字符串）：令牌类型 - "forward" 或 "reverse"
• clients_count（数字）：活跃客户端连接数
• port（数字）：SOCKS5 端口（仅反向令牌）
• connector_tokens（数组）：关联的连接者令牌（仅反向令牌）

令牌管理

添加正向令牌

POST /api/token

{
  "type": "forward",
  "token": "my_forward_token",
  "rules": [
    {
      "addrs": ["192.168.1.0/24"],
      "ports": [22]
    }
  ]
}

参数：

• type（必需）：必须是 "forward"
• token（可选）：要使用的特定令牌，如果未提供则自动生成
• rules（可选）：目标允许条目，由服务器在替该令牌拨号前执行。详见访问控制。

响应：

{
  "success": true,
  "token": "my_forward_token"
}

添加反向令牌

POST /api/token

{
  "type": "reverse",
  "token": "my_reverse_token",
  "port": 9870,
  "username": "socks_user",
  "password": "socks_pass",
  "allow_manage_connector": true,
  "rules": [
    {
      "addrs": ["192.168.1.0/24", "192.168.1.1-255"],
      "ports": [22, [90, 150]]
    },
    {
      "addrs": ["10.0.0.5"],
      "ports": [443]
    }
  ]
}

参数：

• type（必需）：必须是 "reverse"
• token（可选）：要使用的特定令牌，如果未提供则自动生成
• port（可选）：特定的 SOCKS5 端口，如果未提供则自动分配
• username（可选）：SOCKS5 身份验证用户名
• password（可选）：SOCKS5 身份验证密码
• allow_manage_connector（可选）：允许客户端管理连接者令牌（自助连接者管理）
• rules（可选）：该令牌本地代理入口的目标允许条目。每条条目将 addrs（CIDR、裸 IP 或 IP 范围）与 ports（单个端口或 [start, end] 范围）配对;目标命中至少一条条目即被允许。详见访问控制。

响应：

{
  "success": true,
  "token": "my_reverse_token",
  "port": 9871
}

添加连接者令牌

POST /api/token

{
  "type": "connector",
  "token": "my_connector_token",
  "reverse_token": "associated_reverse_token",
  "rules": [
    {
      "addrs": ["10.0.0.0/8"],
      "ports": [[8000, 9000]]
    }
  ]
}

参数：

• type（必需）：必须是 "connector"
• token（可选）：特定的连接者令牌，如果未提供则自动生成
• reverse_token（必需）：关联的反向代理令牌
• rules（可选）：目标允许条目，由服务器在把该连接者的请求转发给反向 provider 前执行。详见访问控制。

响应：

{
  "success": true,
  "token": "my_connector_token"
}

删除令牌（URL 路径）

DELETE /api/token/{token}

通过在 URL 路径中指定来删除令牌。

示例：

curl -X DELETE \
     -H "X-API-Key: your_api_key" \
     http://localhost:8765/api/token/token_to_remove

响应：

{
  "success": true,
  "token": "token_to_remove"
}

删除令牌（请求主体）

DELETE /api/token

{
  "token": "token_to_remove"
}

响应：

{
  "success": true,
  "token": "token_to_remove"
}

服务器级访问控制

/api/config/access 读取和更新服务器级的**入口(entry)与出站(dial)**目标规则。这些是服务器上对任何未设置按 token 覆盖的请求执行的服务器级默认规则,等价于用 WithEntryAccessControl / WithDialAccessControl 服务器选项设置的内容。在 API 服务器模式下,这是配置全局限制的方式,因为该模式下 CLI 的 --access-rule 会被拒绝。

GET /api/config/access

返回当前服务器级规则。

响应：

{
  "entry": [
    {
      "addrs": ["192.168.0.0/16"],
      "ports": [22]
    }
  ],
  "dial": [
    {
      "addrs": ["10.0.0.0/8"],
      "ports": [[8000, 9000]]
    }
  ]
}

PUT /api/config/access

设置服务器级规则。任一字段可独立提供;未提供的字段保持当前值。使用空数组 [] 清空某侧(该侧允许一切)。

curl -X PUT \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{
       "entry": [
         {"addrs": ["192.168.1.0/24"], "ports": [22]}
       ],
       "dial": []
     }' \
     http://localhost:8765/api/config/access

非法地址或端口范围会被拒绝并返回 400 Bad Request。

错误响应

所有端点都以此格式返回错误响应：

{
  "success": false,
  "error": "error description"
}

常见错误：

• "invalid API key" - 身份验证失败
• "invalid request body" - 格式错误的 JSON 请求
• "invalid token type" - 不支持的令牌类型
• "token not specified" - 缺少必需的令牌参数
• "reverse_token is required for connector token" - 连接者缺少 reverse_token