安全 | XSwitch文档中心

访问控制列表

信息说明如下:

参数	说明
name	名称
rule	规则，允许(allow)或拒绝（deny）

查看所有列表信息

请求 URL： /api/acls
请求方式： GET
Body 信息：无
curl 示例:

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" http://192.168.1.100:8081/api/acls

返回值：

{
  "page": 1,
  "pageCount": 1,
  "data": [
    {
      "rule": "deny",
      "updated_at": "2023-03-01 01:18:54",
      "deleted_at": "",
      "id": "1",
      "created_at": "2023-03-01 01:18:54",
      "name": "domains"
    }
  ],
  "rowCount": 1
}

查看指定访问控制列表的配置参数

请求 URL： /api/acls/$id
请求方式： GET
Body 信息：无
返回值：
curl 示例:

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" http://192.168.1.100:8081/api/acls/3

{
  "created_at": "2023-03-03 02:19:11",
  "updated_at": "2023-03-03 02:19:11",
  "name": "test",
  "params": [
    {
      "id": 2,
      "updated_at": "2023-03-03 02:19:33",
      "ports": "",
      "port_type": 0,
      "port": "3893",
      "k": "deny",
      "max_port": "",
      "acl_id": 3,
      "node_type": "cidr",
      "min_port": "",
      "v": "192.168.3.11",
      "created_at": "2023-03-03 02:19:33",
      "deleted_at": ""
    },
    {
      "id": 3,
      "updated_at": "2023-03-03 02:19:56",
      "ports": "",
      "port_type": 2,
      "port": "",
      "k": "allow",
      "max_port": "2000",
      "acl_id": 3,
      "node_type": "cidr",
      "min_port": "1000",
      "v": "192.168.3.112",
      "created_at": "2023-03-03 02:19:56",
      "deleted_at": ""
    }
  ],
  "rule": "deny",
  "id": 3,
  "deleted_at": ""
}

返回信息说明如下:

参数	说明
acl_id	控制列表 ID
node_type	数据类型，cidr 或 domain
port_type	端口类型 0: 单个端口（port） 1: 多个端口（ports） 2: 端口范围(min_port,max_port)
port	单个端口填写
ports	多个端口填写比如 10000,10200
min_port	最小端口比如 10000
max_port	最大端口 20000
k	参数规则，允许(allow)或拒绝（deny）
v	如果数据类型为 cidr，则值填 IP 地址+子网掩码或指定了端口范围则直接填 IP

创建新的访问控制列表

请求 URL： /api/acls
请求方式： POST
Body 信息：

参数	说明
name	名称
rule	规则，允许(allow)或拒绝（deny）

Body

{
  "name": "xyt",
  "rule": "allow"
}

curl 示例:

curl -XPOST -H "X-XTRA-AUTH-ID: 69ee9c54-734b-11e7-a262-b5df20245f60" \
-d '{"name": "xyt","rule": "allow"}' \
-H "Content-Type: application/json" http://192.168.1.100:8081/api/acls

返回值：

{
  "data": 2,
  "message": "success",
  "code": 200
}

修改指定访问控制列表

请求 URL： /api/acls/$id
请求方式： PUT
Body 信息：

参数	说明
name	名称
rule	规则，允许(allow)或拒绝（deny）

{
  "name": "test",
  "rule": "deny"
}

curl 示例:

curl -XPUT -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
-H "Content-Type: application/json" \
-d '{"name": "test", "rule":"deny"}' \
http://192.168.1.100:8081/api/acls/1

返回值：

{
  "message": "success",
  "data": "1",
  "code": 200
}

创建控制列表的节点

请求 URL： /api/acls/$id/nodes
请求方式： POST
Body 信息：

参数	说明
node_type	数据类型，cidr 或 domain
port_type	端口类型 0: 单个端口（port） 1: 多个端口（ports） 2: 端口范围(min_port,max_port)
port	单个端口填写
ports	多个端口填写比如 10000,10200
min_port	最小端口比如 10000
max_port	最大端口 20000
k	参数规则，允许(allow)或拒绝（deny）
v	如果数据类型为 cidr，则值填 IP 地址+子网掩码或指定了端口范围则直接填 IP

{
  "k": "deny",
  "node_type": "cidr",
  "v": "192.168.3.145/32"
}

curl 示例:

curl -XPOST -H "X-XTRA-AUTH-ID: 69ee9c54-734b-11e7-a262-b5df20245f60" \
-d '{"k": "deny","node_type": "cidr","v": "192.168.3.145/32"}' \
-H "Content-Type: application/json" http://192.168.1.100:8081/api/acls/2/nodes

返回值：

{
  "code": 200,
  "message": "success",
  "data": 2
}

修改指定访问控制列表的参数配置

请求 URL： /api/acls/$id/nodes/$node_id
请求方式： PUT
Body 信息：

{
  "k": "allow",
  "node_type": "cidr",
  "v": "192.168.3.118/24"
}

curl 示例:

curl -XPUT -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
-H "Content-Type: application/json" \
-d '{"k": "allow", "node_type": "cidr","v": "192.168.3.118/24"}' \
http://192.168.1.100:8081/api/acls/1/nodes/2

返回值：

{
  "data": "2",
  "message": "success",
  "code": 200
}

删除指定访问控制列表中指定参数

请求 URL： /api/acls/$id/node/$node_id
请求方式： DELETE
Body 信息：无
返回值：

{
  "id": "1"
}

删除指定访问控制列表

请求 URL： /api/acls/$id
请求方式： DELETE
Body 信息：无
返回值：
curl 示例:

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" -XDELETE http://192.168.1.100:8081/api/acls/2

{
  "id": "2"
}

IP 黑名单

IP黑名单说明如下:

参数	说明
target_ip	限制源IP地址
target_name	名称
target_port	限制端口
target_protocol	协议

获取 IP 黑名单

请求 URL: /api/iptables 返回被限制的ip及端口等信息
请求方式: GET
返回值: 路由 JSON 对象，如果找不到会返回 HTTP 状态码404。
curl 示例:

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" http://192.168.1.100:8081/api/iptables

{
 "code": 200,
 "message": "success",
 "data": [
  {
   "chain": "-A",
   "rule_spec": "INPUT -s 1.1.21.12/32 -p udp -m udp --dport 21345 -m comment --comment test -j DROP"
  },
  {
   "chain": "-A",
   "rule_spec": "INPUT -s 1.1.1.12/32 -p udp -m udp --dport 2345 -m comment --comment test -j DROP"
  }
 ]
}

新建 IP 黑名单

请求 URL: /api/iptables/add_rule
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 参见IP黑名单信息说明。

Body:

{
  "target_ip": "1.1.21.12",
  "target_name": "test",
  "target_port": "21345",
  "target_protocol": "udp"
}

{
 "code": 200,
 "data": true,
 "message": "success"
}

curl 示例:

curl -XPOST -H "X-XTRA-AUTH-ID: 69ee9c54-734b-11e7-a262-b5df20245f60" \
-d '{"target_ip": "1.1.21.12","target_name": "test","target_port": "21345","target_protocol": "udp"}' \
-H "Content-Type: application/json" "http://192.168.1.100:8081/api/iptables/add_rule"

通过 IP 地址创建IP黑名单

请求 URL: /api/iptables/drop
请求方式: POST
消息头: Content-Type: application/json
Body 信息:

{
	"target_ip": "192.168.1.111"
}

{
 "code": 200,
 "data": true,
 "message": "success"
}

验证 IP 黑名单

请求 URL: /api/iptables/query_blacklist
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 参见IP黑名单信息说明。

Body:

{
  "query_ip": "192.168.0.165"
}

{
	"code":	200,
	"message":	"success",
	"data":	[{
			"error":	"ipset command not found"
		}, {
			"blacklist_result":	false
		}]
}

更新 IP 黑名单

请求 URL: /api/iptables/query_update_time
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 无

{
	"data":	[{
			"v":	"2025-08-29 09:07:10"
		}],
	"code":	200,
	"message":	"success"
}

获取更新的 IP 黑名单

请求 URL: /api/iptables/update_blacklist
请求方式: GET
消息头: Content-Type: application/json
Body 信息: 无

{
	"message":	"success",
	"data":	3135,
	"code":	200
}

删除 IP 黑名单

请求 URL: /api/iptables/clean_drop_rule
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 参见IP黑名单信息说明。

Body:

{
  "target_ip": "1.1.21.12",
  "target_name": "test",
  "target_port": "21345",
  "target_protocol": "udp"
}

curl 示例:

curl -XPOST -H "X-XTRA-AUTH-ID: 69ee9c54-734b-11e7-a262-b5df20245f60" \
-d '{"target_ip": "1.1.21.12","target_name": "test","target_port": "21345","target_protocol": "udp"}' \
-H "Content-Type: application/json" "http://192.168.1.100:8081/api/iptables/clean_drop_rule"

{
 "code": 200,
 "data": true,
 "message": "success"
}

添加 DSCP 规则

请求 URL: /api/iptables/add_dscp_rule
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 参见IP黑名单信息说明。

{
  "dscp_type": "sip",
  "dscp_value": "CS5"
}

{
	"message":	"success",
	"data":	3135,
	"code":	200
}

curl 示例:

curl -XPOST -H "X-XTRA-AUTH-ID: 69ee9c54-734b-11e7-a262-b5df20245f60" \
-d '{"dscp_type": "sip","dscp_value": "CS5"}' \
-H "Content-Type: application/json" "http://192.168.1.100:8081/api/iptables/add_dscp_rule"

获取 DSCP 规则

请求 URL: /api/iptables/dscp_rule
请求方式: GET
消息头: Content-Type: application/json
Body 信息: 无

{
	"data": [
		{
			"ref_id": "",
			"created_at": "2025-08-29 02:19:09",
			"deleted_at": "",
			"id": "3137",
			"realm": "DSCP",
			"v": "CS5",
			"disabled": "0",
			"updated_at": "2025-08-29 02:19:09",
			"k": "sip"
		}
	],
	"message": "success",
	"code": 200
}

添加 TOS 规则

请求 URL: /api/iptables/add_tos_rule
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 参见IP黑名单信息说明。

{
  "tos_type": "sip",
  "tos_value": "CS5"
}

{
	"code": 200,
	"data": 3138,
	"message": "success"
}

获取 TOS 规则

请求 URL: /api/iptables/tos_rule
请求方式: GET
消息头: Content-Type: application/json
Body 信息: 无

{
	"code": 200,
	"data": [
		{
			"id": "3138",
			"disabled": "0",
			"deleted_at": "",
			"ref_id": "",
			"v": "CS5",
			"created_at": "2025-08-29 02:27:23",
			"updated_at": "2025-08-29 02:27:23",
			"k": "sip",
			"realm": "TOS"
		}
	],
	"message": "success"
}

添加 IP 白名单

请求 URL: /api/iptables/white_list
请求方式: POST
消息头: Content-Type: application/json
Body 信息: 参见IP黑名单信息说明。

{
  "target_name": "允许访问的服务器",
  "target_ip": "192.168.1.100",
  "target_port": "8080",
  "target_protocol": "tcp"
}

{
	"data": true,
	"message": "success",
	"code": 200
}