API 文档

概述

NNIPMS 提供 RESTful API 接口，支持对端口映射、IP 管理等功能的程序化操作。

基础信息

• Base URL: http://localhost:8070/api/v1
• 认证方式: Bearer Token
• 数据格式: JSON

认证

所有 API 请求需要在 Header 中携带认证令牌：

Authorization: Bearer YOUR_ACCESS_TOKEN

获取 Token：

curl -X POST http://localhost:8070/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password"
  }'

端口映射 API

获取端口映射列表

GET /port-mappings

查询参数：

参数	类型	说明
page	int	页码，默认 1
size	int	每页数量，默认 20
keyword	string	搜索关键词
status	string	状态筛选：active, inactive

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "source": "0.0.0.0:8080",
        "target": "192.168.1.100:80",
        "protocol": "tcp",
        "status": "active",
        "description": "Web服务器",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "size": 20
  }
}

创建端口映射

POST /port-mappings

请求体：

{
  "source": "0.0.0.0:8080",
  "target": "192.168.1.100:80",
  "protocol": "tcp",
  "description": "Web服务器"
}

字段说明：

字段	类型	必填	说明
source	string	是	源地址，格式：ip:port
target	string	是	目标地址，格式：ip:port
protocol	string	是	协议：tcp, udp, http, https
description	string	否	描述

更新端口映射

PUT /port-mappings/{id}

请求体：

{
  "source": "0.0.0.0:8080",
  "target": "192.168.1.100:8080",
  "protocol": "tcp",
  "status": "active",
  "description": "更新描述"
}

删除端口映射

DELETE /port-mappings/{id}

批量删除

POST /port-mappings/batch-delete

请求体：

{
  "ids": [1, 2, 3]
}

IP 管理 API

获取 IP 列表

GET /ip-addresses

查询参数：

参数	类型	说明
subnet_id	int	子网 ID
status	string	状态：available, allocated, reserved

分配 IP

POST /ip-addresses/allocate

请求体：

{
  "subnet_id": 1,
  "resource_type": "port_mapping",
  "resource_id": 100
}

释放 IP

POST /ip-addresses/{id}/release

子网管理 API

获取子网列表

GET /subnets

创建子网

POST /subnets

请求体：

{
  "name": "生产环境",
  "cidr": "192.168.1.0/24",
  "gateway": "192.168.1.1",
  "description": "生产服务器网段"
}

用户管理 API

获取用户列表

GET /users

创建用户

POST /users

请求体：

{
  "username": "zhangsan",
  "password": "initial_password",
  "email": "zhangsan@example.com",
  "role": "operator",
  "department": "运维部"
}

更新用户

PUT /users/{id}

删除用户

DELETE /users/{id}

系统监控 API

获取系统状态

GET /system/status

响应示例：

{
  "code": 200,
  "data": {
    "cpu_usage": 45.2,
    "memory_usage": 62.5,
    "disk_usage": 38.0,
    "uptime": "15d 3h 24m",
    "version": "v1.0.0"
  }
}

获取端口统计

GET /statistics/port-mappings

响应示例：

{
  "code": 200,
  "data": {
    "total": 150,
    "active": 120,
    "inactive": 30,
    "tcp": 100,
    "udp": 50
  }
}

错误码

错误码	说明
200	成功
400	请求参数错误
401	未授权
403	禁止访问
404	资源不存在
409	资源冲突
500	服务器内部错误

SDK 示例

Python

import requests

class NNIPMSClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def get_port_mappings(self, page=1, size=20):
        url = f'{self.base_url}/port-mappings'
        params = {'page': page, 'size': size}
        response = requests.get(url, headers=self.headers, params=params)
        return response.json()
    
    def create_port_mapping(self, source, target, protocol, description=''):
        url = f'{self.base_url}/port-mappings'
        data = {
            'source': source,
            'target': target,
            'protocol': protocol,
            'description': description
        }
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()

# 使用示例
client = NNIPMSClient('http://localhost:8070/api/v1', 'YOUR_TOKEN')
result = client.get_port_mappings()
print(result)

JavaScript

class NNIPMSClient {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }
  
  async getPortMappings(page = 1, size = 20) {
    const url = new URL(`${this.baseUrl}/port-mappings`);
    url.searchParams.append('page', page);
    url.searchParams.append('size', size);
    
    const response = await fetch(url, {
      headers: this.headers
    });
    return response.json();
  }
  
  async createPortMapping(source, target, protocol, description = '') {
    const url = `${this.baseUrl}/port-mappings`;
    const data = { source, target, protocol, description };
    
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(data)
    });
    return response.json();
  }
}

// 使用示例
const client = new NNIPMSClient('http://localhost:8070/api/v1', 'YOUR_TOKEN');
client.getPortMappings().then(result => console.log(result));