API 文档

IPAM 提供 RESTful API 接口，支持标准的 HTTP 方法和 JSON 数据格式。

API 概览

基础信息

项目	内容
基础 URL	`http://localhost:8080/api`
数据格式	JSON
认证方式	JWT Token
字符编码	UTF-8

请求格式

http

GET /api/ips HTTP/1.1
Host: localhost:8080
Authorization: Bearer <token>
Content-Type: application/json

响应格式

json

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

标准响应码

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

认证

获取验证码

http

GET /api/captcha

响应：

json

{
  "code": 200,
  "data": {
    "captcha_id": "captcha_abc123",
    "image": "data:image/png;base64,..."
  }
}

使用 Token

在请求头中添加 Authorization：

http

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

注销登录

http

POST /api/logout
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "message": "注销成功"
}

获取用户资料

http

GET /api/profile
Authorization: Bearer <token>

用户注册

http

POST /api/users/register
Content-Type: application/json

{
  "username": "newuser",
  "password": "password123",
  "nickname": "新用户"
}

获取注册配置

http

GET /api/auth/register-config

响应：

json

{
  "code": 200,
  "data": {
    "allow_register": true,
    "default_role": "operator"
  }
}

灵活查询

系统采用灵活查询模式，支持动态过滤、排序和分页。

查询参数

参数	类型	说明
page	int	页码，默认 1
page_size	int	每页数量，默认 20
order	string	排序字段
order_by	string	排序方式：asc/desc
filters	JSON	过滤条件

过滤条件格式

json

{
  "filters": {
    "field_name": {
      "operator": "value"
    }
  }
}

支持的运算符：

运算符	说明
eq	等于
neq	不等于
gt	大于
gte	大于等于
lt	小于
lte	小于等于
like	模糊匹配
in	在列表中
not_in	不在列表中
is_null	为空
is_not_null	不为空

查询示例

http

GET /api/ips?page=1&page_size=20&order=id&order_by=desc
GET /api/ips?filters={"ip":{"like":"192.168"}}

响应格式

json

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

错误处理

错误响应格式

json

{
  "code": 400,
  "message": "请求参数错误",
  "error": {
    "code": "INVALID_PARAMETER",
    "details": {}
  }
}

错误码列表

错误码	说明
INVALID_PARAMETER	请求参数错误
UNAUTHORIZED	未授权
FORBIDDEN	禁止访问
NOT_FOUND	资源不存在
ALREADY_EXISTS	资源已存在
INTERNAL_ERROR	内部服务器错误

数据校验错误码

错误码	说明	适用场景
NAME_EXISTS	名称已存在	单位、部门、项目、网络区域等的名称唯一性校验
CODE_EXISTS	编码已存在	单位、部门、项目、网络区域等的编码唯一性校验
ID_NOT_FOUND	ID不存在	更新时指定的资源ID不存在
INVALID_LEVEL	行政级别无效	单位级别不在1-5范围内
INVALID_PARENT	上级单位无效	层级关系校验失败
PARENT_NOT_FOUND	上级单位不存在	指定的上级单位ID不存在
PROVINCE_HAS_PARENT	省级单位不能有上级	1级单位设置了ParentID
MISSING_PARENT	缺少上级单位	N级单位(N>1)未指定上级

资源接口

IP 地址管理

方法	路径	说明
GET	/api/ips	获取 IP 列表（灵活查询）
GET	/api/ips/count	获取 IP 数量
GET	/api/ips/options	获取选项列表
POST	/api/ips/allocate	分配 IP
PATCH	/api/ips	灵活更新 IP
POST	/api/ips/release	释放 IP

子网管理

方法	路径	说明
GET	/api/subnets	获取子网列表（灵活查询）
GET	/api/subnets/count	获取子网数量
GET	/api/subnets/options	获取选项列表
POST	/api/subnets	创建子网
PATCH	/api/subnets	灵活更新子网
DELETE	/api/subnets	删除子网

网关管理

方法	路径	说明
GET	/api/gateways	获取网关列表（灵活查询）
GET	/api/gateways/count	获取网关数量
GET	/api/gateways/options	获取选项列表
POST	/api/gateways	创建网关
PATCH	/api/gateways	灵活更新网关
DELETE	/api/gateways	删除网关

网络区域管理

方法	路径	说明
GET	/api/network_areas	获取网络区域列表（灵活查询）
GET	/api/network_areas/count	获取网络区域数量
GET	/api/network_areas/options	获取选项列表
POST	/api/network_areas	创建网络区域
PATCH	/api/network_areas	灵活更新网络区域
DELETE	/api/network_areas	删除网络区域

单位管理

方法	路径	说明
GET	/api/units	获取单位列表（灵活查询）
GET	/api/units/count	获取单位数量
GET	/api/units/options	获取选项列表
POST	/api/units	创建单位
PATCH	/api/units	灵活更新单位
DELETE	/api/units	删除单位

部门管理

方法	路径	说明
GET	/api/departments	获取部门列表（灵活查询）
GET	/api/departments/count	获取部门数量
GET	/api/departments/options	获取选项列表
POST	/api/departments	创建部门
PATCH	/api/departments	灵活更新部门
DELETE	/api/departments	删除部门

项目管理

方法	路径	说明
GET	/api/projects	获取项目列表（灵活查询）
GET	/api/projects/count	获取项目数量
GET	/api/projects/options	获取选项列表
POST	/api/projects	创建项目
PATCH	/api/projects	灵活更新项目
DELETE	/api/projects	删除项目

使用人管理

方法	路径	说明
GET	/api/user_contacts	获取使用人列表（灵活查询）
GET	/api/user_contacts/count	获取使用人数量
GET	/api/user_contacts/options	获取选项列表
POST	/api/user_contacts	创建使用人
PATCH	/api/user_contacts	灵活更新使用人
DELETE	/api/user_contacts	批量删除使用人

用户组管理

方法	路径	说明
GET	/api/user-groups	获取用户组列表（灵活查询）
GET	/api/user-groups/count	获取用户组数量
GET	/api/user-groups/options	获取选项列表
POST	/api/user-groups	创建用户组（管理员）
PATCH	/api/user-groups	灵活更新用户组（管理员）
DELETE	/api/user-groups	删除用户组（管理员）

字段定义管理

方法	路径	说明
GET	/api/field_definitions	获取字段定义列表（灵活查询）
GET	/api/field_definitions/count	获取字段定义数量
GET	/api/field_definitions/options	获取选项列表
POST	/api/field_definitions	创建字段定义（管理员）
PATCH	/api/field_definitions	灵活更新字段定义（管理员）
DELETE	/api/field_definitions	删除字段定义（管理员）

IP 注册申请管理

方法	路径	说明
GET	/api/registerIps	获取注册申请列表（灵活查询）
GET	/api/registerIps/count	获取注册申请数量
POST	/api/registerIps	创建注册申请
PUT	/api/registerIps	灵活更新注册申请
DELETE	/api/registerIps	删除注册申请

用户管理

方法	路径	说明
GET	/api/users	获取用户列表
POST	/api/users	创建用户（管理员）
PATCH	/api/users	更新用户（管理员）
DELETE	/api/users	删除用户（管理员）

登录日志

方法	路径	说明
GET	/api/login-logs	获取登录日志列表
DELETE	/api/login-logs	删除登录日志（管理员）

智能导入导出

智能导出

http

POST /api/smart/export
Authorization: Bearer <token>
Content-Type: application/json

{
  "resource_types": ["network_areas", "units"],
  "include_dependencies": true,
  "filters": {}
}

响应：

json

{
  "code": 200,
  "message": "导出成功",
  "data": {
    "file_path": "/exports/xxx.xlsx",
    "file_name": "export_20240115.xlsx"
  }
}

导出全部

http

POST /api/smart/export/all

导入预览

http

POST /api/smart/import/preview
Content-Type: multipart/form-data

file: <Excel文件>

执行导入

http

POST /api/smart/import/execute
Content-Type: multipart/form-data

file: <Excel文件>

下载导入模板

http

GET /api/smart/import/template?type=network_areas

通知管理

方法	路径	说明
GET	/api/notifications	获取通知列表
GET	/api/notifications/count	获取通知数量
GET	/api/notifications/unread-count	获取未读数量
PATCH	/api/notifications/mark-read	标记已读
PATCH	/api/notifications/mark-all-read	标记全部已读
POST	/api/notifications	创建通知（管理员）
PATCH	/api/notifications	更新通知（管理员）
DELETE	/api/notifications	删除通知（管理员）

通知配置管理

方法	路径	说明
GET	/api/notification-configs	获取通知配置列表
GET	/api/notification-configs/count	获取配置数量
GET	/api/notification-configs/options	获取选项列表
POST	/api/notification-configs	创建配置（管理员）
PATCH	/api/notification-configs	更新配置（管理员）
DELETE	/api/notification-configs	删除配置（管理员）

邮箱配置管理

方法	路径	说明
GET	/api/email-configs	获取邮箱配置列表
GET	/api/email-configs/count	获取配置数量
GET	/api/email-configs/options	获取选项列表
POST	/api/email-configs	创建邮箱配置（管理员）
PATCH	/api/email-configs	更新邮箱配置（管理员）
PATCH	/api/email-configs/set-default/:id	设置默认配置（管理员）
POST	/api/email-configs/test/:id	测试连接（管理员）
POST	/api/email-configs/send	发送邮件（管理员）
DELETE	/api/email-configs	删除配置（管理员）

系统配置

方法	路径	说明
GET	/api/config/registration	获取注册配置
PUT	/api/config/registration	更新注册配置（管理员）

探针管理

探针客户端接口（无需认证）

方法	路径	说明
POST	/probe/register	注册探针客户端
POST	/probe/heartbeat	探针心跳
POST	/probe/report	上报扫描结果

探针管理接口（需要认证）

方法	路径	说明
GET	/api/probe/clients	获取探针客户端列表
GET	/api/probe/clients/stats	获取探针统计
GET	/api/probe/clients/count	获取探针数量
PATCH	/api/probe/clients	更新探针客户端
DELETE	/api/probe/clients	删除探针客户端
GET	/api/probe/reports	获取上报记录列表
GET	/api/probe/reports/stats	获取上报记录统计
GET	/api/probe/reports/count	获取上报记录数量
DELETE	/api/probe/reports	删除上报记录

备份管理

备份配置

方法	路径	说明
GET	/api/backup/config	获取备份配置
PUT	/api/backup/config	更新备份配置（管理员）

手动备份

方法	路径	说明
POST	/api/backup/manual	手动执行备份（管理员）

备份记录

方法	路径	说明
GET	/api/backup/records	获取备份记录列表
DELETE	/api/backup/records/:id	删除备份记录（管理员）

备份下载

方法	路径	说明
GET	/api/backup/download/:id	下载备份文件

备份统计

方法	路径	说明
GET	/api/backup/stats	获取备份统计信息

系统信息

获取系统信息

http

GET /api/system/info

响应：

json

{
  "code": 200,
  "data": {
    "app_name": "IPAM - IP地址管理系统",
    "version": "1.2.0",
    "description": "企业级IP地址管理系统",
    "author": "坐公交也用券",
    "license": "MIT",
    "website": "https://ipam.liumou.site/",
    "go_version": "go1.21",
    "os": "linux",
    "arch": "amd64",
    "start_time": "2024-01-15T10:00:00Z",
    "uptime": "24h0m0s",
    "server_host": "0.0.0.0",
    "server_port": 8080,
    "database_type": "mysql",
    "database_host": "localhost"
  }
}

数据库管理

获取数据库信息

http

GET /api/database/info

执行数据库操作（管理员）

http

POST /api/database/execute

示例代码

cURL

bash

# 登录
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 获取 IP 列表
curl -X GET "http://localhost:8080/api/ips?page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

# 创建子网
curl -X POST http://localhost:8080/api/subnets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "办公网段",
    "cidr": "192.168.1.0/24",
    "gateway_id": 1,
    "network_area_id": 1
  }'

# 灵活更新子网
curl -X PATCH http://localhost:8080/api/subnets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "新名称"
  }'

# 删除子网（批量）
curl -X DELETE http://localhost:8080/api/subnets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1, 2, 3]}'

Python

python

import requests

BASE_URL = 'http://localhost:8080/api'

# 登录
response = requests.post(f'{BASE_URL}/login', json={
    'username': 'admin',
    'password': 'admin123'
})
token = response.json()['data']['token']
headers = {'Authorization': f'Bearer {token}'}

# 获取 IP 列表
response = requests.get(f'{BASE_URL}/ips', headers=headers, params={
    'page': 1,
    'page_size': 20
})
ip_list = response.json()['data']['list']

# 创建子网
response = requests.post(f'{BASE_URL}/subnets', headers=headers, json={
    'name': '办公网段',
    'cidr': '192.168.1.0/24',
    'gateway_id': 1,
    'network_area_id': 1
})

# 灵活更新
response = requests.patch(f'{BASE_URL}/subnets', headers=headers, json={
    'id': 1,
    'name': '新名称'
})

# 灵活查询示例
response = requests.get(f'{BASE_URL}/ips', headers=headers, params={
    'filters': '{"ip":{"like":"192.168"}}',
    'order': 'id',
    'order_by': 'desc'
})

JavaScript

javascript

const BASE_URL = 'http://localhost:8080/api';

const login = async () => {
  const response = await fetch(`${BASE_URL}/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'admin', password: 'admin123' })
  });
  const data = await response.json();
  return data.data.token;
};

const getIPs = async (token, params = {}) => {
  const query = new URLSearchParams(params).toString();
  const response = await fetch(`${BASE_URL}/ips?${query}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
};

const createSubnet = async (token, subnet) => {
  const response = await fetch(`${BASE_URL}/subnets`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(subnet)
  });
  return await response.json();
};

const flexibleUpdate = async (token, resource, data) => {
  const response = await fetch(`${BASE_URL}/${resource}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });
  return await response.json();
};

Swagger 文档

系统提供 Swagger UI 接口文档：

http://localhost:8080/swagger/index.html

Swagger 文档包含所有接口的详细说明、请求参数和响应示例。

API 文档 ​

API 概览 ​

基础信息 ​

请求格式 ​

响应格式 ​

标准响应码 ​

认证 ​

获取验证码 ​

登录 ​

使用 Token ​

注销登录 ​

获取用户资料 ​

用户注册 ​

获取注册配置 ​

灵活查询 ​

查询参数 ​

过滤条件格式 ​

查询示例 ​

响应格式 ​

错误处理 ​

错误响应格式 ​

错误码列表 ​

数据校验错误码 ​

资源接口 ​

IP 地址管理 ​

子网管理 ​

网关管理 ​

网络区域管理 ​

单位管理 ​

部门管理 ​

项目管理 ​

使用人管理 ​

用户组管理 ​

字段定义管理 ​

IP 注册申请管理 ​

用户管理 ​

登录日志 ​

智能导入导出 ​

智能导出 ​

导出全部 ​

导入预览 ​

执行导入 ​

下载导入模板 ​

通知管理 ​

通知配置管理 ​

邮箱配置管理 ​

系统配置 ​

探针管理 ​

探针客户端接口（无需认证） ​

探针管理接口（需要认证） ​

备份管理 ​

备份配置 ​

手动备份 ​

备份记录 ​

备份下载 ​

备份统计 ​

系统信息 ​

获取系统信息 ​

数据库管理 ​

获取数据库信息 ​

执行数据库操作（管理员） ​

示例代码 ​

cURL ​

Python ​

JavaScript ​

Swagger 文档 ​

API 文档

API 概览

基础信息

请求格式

响应格式

标准响应码

认证

获取验证码

登录

使用 Token

注销登录

获取用户资料

用户注册

获取注册配置

灵活查询

查询参数

过滤条件格式

查询示例

响应格式

错误处理

错误响应格式

错误码列表

数据校验错误码

资源接口

IP 地址管理

子网管理

网关管理

网络区域管理

单位管理

部门管理

项目管理

使用人管理

用户组管理

字段定义管理

IP 注册申请管理

用户管理

登录日志

智能导入导出

智能导出

导出全部

导入预览

执行导入

下载导入模板

通知管理

通知配置管理

邮箱配置管理

系统配置

探针管理

探针客户端接口（无需认证）

探针管理接口（需要认证）

备份管理

备份配置

手动备份

备份记录

备份下载

备份统计

系统信息

获取系统信息

数据库管理

获取数据库信息

执行数据库操作（管理员）

示例代码

cURL

Python

JavaScript

Swagger 文档