NPS WebAPI 开发日志 & 调试说明（全接口+自动生成auth_key示例）

› VFX大学 › NPS WebAPI 开发日志 & 调试说明（全接口+自动生成auth_key示例）

  • 该话题为空。
正在查看 0 条回复
  • 作者
    帖子
    • 2025年7月26日 - 下午5:08 #829

      追光
      管理员

      本项目基于 NPS (内网穿透服务) 的官方 Web API，进行二次开发，实现与自有系统的无缝对接。由于官方接口文档不够完善，且部分调用方式存在差异，本次开发在充分调试和测试后，确认了接口的请求规范及调用流程，并结合实际业务需求，封装出一套易用、兼容性强的调用方案。-季松斌 2025年7月26日

      以下是我开发过程中NPS服务端api的 $endpoints 列表超链接形式（Markdown格式），给自己记录也分享给开发者们，因为文档的松散，找到这些接口还费了不少力气：

      📡 NPS 接口列表汇总

      🧩 客户端相关（Client）

      • client/add/ — 添加客户端

      • client/edit/ — 编辑客户端

      • client/getclient/ — 获取单个客户端信息

      • client/list/ — 获取客户端列表

      • client/del/ — 删除客户端

      🧩 自定义 Host 相关

      • index/addhost/ — 添加 Host
      • index/edithost/ — 编辑 Host
      • index/hostlist/ — 获取 Host 列表
      • index/delhost/ — 删除 Host

      🧩 隧道相关（Tunnel）

      • index/add/ — 添加隧道
      • index/edit/ — 编辑隧道
      • index/gettunnel/ — 获取隧道列表
      • index/getonetunnel/ — 获取单个隧道信息
      • index/del/ — 删除隧道
      • index/stop/ — 停止隧道
      • index/start/ — 启动隧道

      🔐 授权与密钥相关

      • auth/gettime/ — 获取当前时间戳
      • auth/getauthkey/ — 获取签名密钥（Auth Key）

      如你需要导出为 HTML、PDF、或 WordPress 页面短代码版本，我也可以帮你转换。是否要带上完整 base_url 拼接为绝对地址？比如：

      https://nps.example.com/client/add/

      可以随时告诉我。

      核心设计点

        1. 统一认证机制

          • 所有接口调用均必须携带 auth_key 和 timestamp 参数。

          • auth_key 由服务端配置的 secret 与当前时间戳通过 MD5 生成，保证接口安全性。

          • 时间戳必须与服务端时间保持同步，防止请求被拒绝。

        2. 接口请求方式

          • 采用 HTTP POST 方法，传递参数使用 application/x-www-form-urlencoded 格式。

          • 为兼容各种环境，采用 curl 的 –data-urlencode 形式确保参数编码安全。

        3. 接口参数管理

          • 通过统一配置管理接口基础 URL 和认证 secret，避免硬编码。

          • 支持动态调整 API 地址及认证密钥，方便切换环境和维护。

        4. 功能覆盖全面

          • 集成客户端管理（增删改查）

          • 域名解析（Host）管理

          • 隧道（Tunnel）管理，包括启动、停止、列表及单条记录操作

          • 所有接口均提供示例请求，便于快速测试与调试。

        • 明确错误来源，日志记录接口请求与响应，方便排查问题。

        • 过滤无效数据，避免业务异常。

          错误与兼容处理

      公共变量说明（Shell 生成示例）：

      # 配置参数，必填
SECRET="在服务端配置的密钥"
BASE_URL="https://nps.域名.com"

# 时间戳和签名生成
TIMESTAMP=$(date +%s)
AUTH_KEY=$(echo -n "${SECRET}${TIMESTAMP}" | md5sum | awk '{print $1}')

      以上变量需替换成自己真实的 SECRET 和接口地址

      1. 获取服务端时间

      方法

      URL

      说明

      POST

      ${BASE_URL}/auth/gettime

      获取服务器当前时间戳

      		 
      curl -X POST "${BASE_URL}/auth/gettime" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}"

      2. 获取客户端列表

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/client/list/

      获取指定分页客户端列表

      offset, limit, search, order

      		 
      curl -X POST "${BASE_URL}/client/list/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=10" \
  --data-urlencode "search=" \
  --data-urlencode "order=asc"

      3. 获取单个客户端信息

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/client/getclient/

      获取单个客户端详情

      id (客户端ID)

      		 
      curl -X POST "${BASE_URL}/client/getclient/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=253"

      4. 添加客户端

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/client/add/

      添加新客户端

      remark, u, p, vkey, compress, crypt

      		 
      curl -X POST "${BASE_URL}/client/add/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "remark=测试客户端" \
  --data-urlencode "u=basic_user" \
  --data-urlencode "p=basic_pass" \
  --data-urlencode "vkey=client_verify_key" \
  --data-urlencode "compress=true" \
  --data-urlencode "crypt=true"

      5. 修改客户端

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/client/edit/

      修改客户端信息

      id, remark, u, p, vkey, compress, crypt

      		 
      curl -X POST "${BASE_URL}/client/edit/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=253" \
  --data-urlencode "remark=修改备注" \
  --data-urlencode "u=basic_user" \
  --data-urlencode "p=basic_pass" \
  --data-urlencode "vkey=updated_verify_key" \
  --data-urlencode "compress=true" \
  --data-urlencode "crypt=true"

      6. 删除客户端

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/client/del/

      删除客户端

      id

      		 
      curl -X POST "${BASE_URL}/client/del/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=253"

      7. 获取域名解析列表

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/hostlist/

      获取域名解析记录列表

      nps_id, offset, limit

      		 
      curl -X POST "${BASE_URL}/index/hostlist/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "nps_id=253" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=30"

      8. 添加域名解析

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/addhost/

      新增域名解析

      nps_id, host, target, scheme, remark

      		 
      curl -X POST "${BASE_URL}/index/addhost/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "nps_id=253" \
  --data-urlencode "host=example.newvfx.com" \
  --data-urlencode "target=192.168.0.1:80" \
  --data-urlencode "scheme=all" \
  --data-urlencode "remark=备注信息"

      9. 修改域名解析

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/edithost/

      修改域名解析

      id, host, target, scheme, remark

      		 
      curl -X POST "${BASE_URL}/index/edithost/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=100" \
  --data-urlencode "host=example.newvfx.com" \
  --data-urlencode "target=192.168.0.2:80" \
  --data-urlencode "scheme=all" \
  --data-urlencode "remark=修改备注"

      10. 删除域名解析

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/delhost/

      删除域名解析

      id

      		 
      curl -X POST "${BASE_URL}/index/delhost/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=100"

      11. 获取隧道列表

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/gettunnel/

      获取隧道列表

      client_id, offset, limit

      		 
      curl -X POST "${BASE_URL}/index/gettunnel/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "client_id=253" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=30"

      12. 获取单条隧道信息

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/getonetunnel/

      获取单条隧道详情

      id (隧道ID)

      		 
      curl -X POST "${BASE_URL}/index/getonetunnel/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=181"

      13. 添加隧道

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/add/

      新增隧道

      client_id, mode, port, target, remark

      		 
      curl -X POST "${BASE_URL}/index/add/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "client_id=253" \
  --data-urlencode "mode=tcp" \
  --data-urlencode "port=12345" \
  --data-urlencode "target=10.11.12.13:9988" \
  --data-urlencode "remark=测试隧道"

      14. 修改隧道

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/edit/

      修改隧道信息

      id, mode, port, target, remark

      		 
      curl -X POST "${BASE_URL}/index/edit/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=181" \
  --data-urlencode "mode=tcp" \
  --data-urlencode "port=54321" \
  --data-urlencode "target=10.11.12.14:9988" \
  --data-urlencode "remark=修改备注"

      15. 删除隧道

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/del/

      删除隧道

      id

      		 
      curl -X POST "${BASE_URL}/index/del/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=181"

      16. 隧道停止工作

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/stop/

      停止指定隧道

      id

      		 
      curl -X POST "${BASE_URL}/index/stop/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=181"

      17. 隧道开始工作

      方法

      URL

      说明

      主要参数

      POST

      ${BASE_URL}/index/start/

      启动指定隧道

      id

      		 
      curl -X POST "${BASE_URL}/index/start/" \
  --data-urlencode "auth_key=${AUTH_KEY}" \
  --data-urlencode "timestamp=${TIMESTAMP}" \
  --data-urlencode "id=181"

      附录：动态 PHP 生成

      auth_key

      示例

      <?php
$secret = 'A9b7C4d2E8f6H3j1';
$timestamp = time();
$auth_key = md5($secret . $timestamp);

echo "auth_key={$auth_key}\n";
echo "timestamp={$timestamp}\n";
?>

      说明

      • 所有接口均须传递 auth_key 和 timestamp 参数验证身份

      • 时间戳误差过大会导致验证失败，请优先调用 /auth/gettime 获取服务器时间同步

      • 请求数据用 POST 且 application/x-www-form-urlencoded 编码

      • –data-urlencode 保证参数正确编码，兼容性最佳

      • client_id 和 nps_id 根据上下文传递，需用真实ID替换

      如果需要，我可以帮你做成一个自动调用脚本或后台配置面板。需要的话随时告诉我！

  • 作者
    帖子
正在查看 0 条回复
  • 在下方一键注册，登录后就可以回复啦。