sangfor-ac-api

深信服 AC 上网行为管理设备开放接口 SDK（Node.js）

基于深信服 AC 开放接口文档 v1.0（2019-05），覆盖文档中全部 30+ 端点。

---

目录

• 特性
• 安装
• 快速开始
• API 模块
  • Status — 设备状态
  • User — 用户管理
  • Group — 组管理
  • Policy — 策略查询
  • BindInfo — 绑定关系
  • OnlineUsers — 在线用户
• 认证机制
• 错误处理
• 注意事项

---

特性

• 零外部依赖，仅使用 Node.js 内置模块（http + crypto）
• 完整覆盖 Status / User / Group / Policy / BindInfo / OnlineUsers 六大模块
• 全部端点带 JSDoc 注释，IDE 自动补全友好
• 统一响应格式 { code, message, data }
• 支持配置覆盖和自定义超时/语言

---

##安装

# 直接克隆到项目中使用
git clone ...

# 或使用 npm link
npm link sangfor-ac-api

---

快速开始

const SangforAC = require('sangfor-ac-api');

// 必须传入完整配置
const ac = new SangforAC({
  host: '10.0.0.1',
  port: 9999,
  sharedKey: 'your-shared-key',
  timeout: 5000
});

// 获取设备基本信息
const ver = await ac.status.version();
console.log(ver.data); // 'AC12.0.40.002 Build20191102'

const online = await ac.status.onlineUser();
console.log(`在线用户: ${online.data} 人`);

---

API 模块

Status — 设备状态

方法	说明	请求方式
version()	获取设备版本号	GET
onlineUser()	获取在线用户数	GET
sessionNum()	获取会话数	GET
insidelib()	获取内置库版本信息	GET
log()	获取行为日志数量	GET
cpuUsage()	获取 CPU 使用率	GET
memUsage()	获取内存使用率	GET
diskUsage()	获取磁盘使用率	GET
sysTime()	获取系统时间	GET
throughput(filter)	获取吞吐量（上行/下行）	POST
userRank(filter)	获取用户流量排行	POST
appRank(filter)	获取应用流量排行	POST
bandwidthUsage()	获取带宽使用率	GET
fluxUnits()	获取流速单位配置	GET

// 获取吞吐量（指定 eth1 网口）
const tp = await ac.status.throughput({
  unit: 'bits',
  interface: 'eth1'
});
console.log(`上行: ${tp.data.send} | 下行: ${tp.data.recv} ${tp.data.unit}`);

// 获取用户流量 Top 10
const rank = await ac.status.userRank({ top: 10, line: '0' });
rank.data.forEach(u => {
  console.log(`${u.name}: 上行 ${u.up}B / 下行 ${u.down}B`);
});

---

User — 用户管理

方法	说明	请求方式
add(userInfo)	添加用户	POST
delete(name)	删除用户	POST
search({ search_type, search_value })	搜索用户	POST
update(name, data)	修改用户信息	POST
detail(name)	获取用户详细信息	GET
setNetPolicy(opr, user, policy)	关联上网策略	POST
getNetPolicy(user)	获取上网策略	GET
setFluxPolicy(opr, user, policy)	关联流控策略	POST
getFluxPolicy(user)	获取流控策略	GET
verifyPassword(name, password)	验证密码	GET

// 添加用户并设置密码
await ac.user.add({
  name: 'zhangsan',
  father_path: '/研发部',
  desc: '研发工程师',
  extend: {
    self_pass: { enable: true, password: 'abc123', modify_once: false },
    bind_cfg: ['192.168.1.100']
  }
});

// 给用户关联策略
await ac.user.setNetPolicy('add', 'zhangsan', ['默认策略']);

// 搜索用户
const res = await ac.user.search({
  search_type: 'user',
  search_value: '张三'
});

---

Group — 组管理

方法	说明	请求方式
add(path, desc)	添加组	POST
delete(path)	删除组	POST
update(path, desc)	修改组信息	POST
setNetPolicy(opr, group, policy)	关联上网策略	POST
getNetPolicy(path)	获取上网策略	GET
setFluxPolicy(opr, group, policy)	关联流控策略	POST
getFluxPolicy(path)	获取流控策略	GET

// 创建组并关联策略
await ac.group.add('/研发部', '研发部门');
await ac.group.setNetPolicy('add', '/研发部', ['办公策略']);

---

Policy — 策略查询

方法	说明	请求方式
netpolicy()	获取所有上网策略	GET
fluxpolicy()	获取所有流控策略	GET

⚠️ 只读：不支持通过 API 创建/修改/删除策略，策略内容需在 AC 设备本地配置。

// 获取所有策略名（用于关联时引用）
const policies = await ac.policy.netpolicy();
const names = policies.data.map(p => p.policy_info.name);
console.log('可用策略:', names);

---

BindInfo — 绑定关系

方法	说明	请求方式
searchUserBind(search)	查询用户-IP/MAC 绑定	GET
searchIpMac(search)	查询 IP/MAC 绑定	GET
deleteUserBind(addr)	删除用户-IP/MAC 绑定	POST
deleteIpMac(ip)	删除 IP/MAC 绑定	POST
addUserBind(data)	增加用户-IP/MAC 绑定	POST
addIpMac(data)	增加 IP/MAC 绑定	POST

// 绑定用户到 IP
await ac.bindInfo.addUserBind({
  enable: true,
  name: 'zhangsan',
  addr_type: 'ip',
  addr: '192.168.1.100',
  limitlogon: true,
  noauth: { enable: false, expire_time: 0 }
});

// IP+MAC 双绑定
await ac.bindInfo.addUserBind({
  enable: true,
  name: 'zhangsan',
  addr_type: 'ipmac',
  addr: '192.168.1.100+aa-bb-cc-dd-ee-ff',
  limitlogon: true,
  noauth: { enable: true, expire_time: 0 }
});

---

OnlineUsers — 在线用户

方法	说明	请求方式
list(filter)	获取在线用户列表	POST
kick(ip)	强制注销用户	POST
login(data)	单点登录上线	POST

// 查看在线用户
const list = await ac.onlineUsers.list({ status: 'active' });
console.log(`在线: ${list.data.count} 人`);

// 强制注销
await ac.onlineUsers.kick('192.168.1.100');

// 单点登录
await ac.onlineUsers.login({
  ip: '192.168.1.100',
  name: 'zhangsan',
  mac: 'aa-bb-cc-dd-ee-ff'
});

---

认证机制

深信服 AC 使用 MD5 签名 认证，规则如下：

1. 客户端生成随机字符串 random
2. 计算签名 md5(共享密钥 + random)
3. 将 random 和 md5 值附加到请求中：
   • GET：URL 查询参数 ?random=xxx&md5=xxx
   • POST/PUT/DELETE：JSON body 中 { random, md5, ...data }

SDK 内部自动处理认证签名，无需手动计算。

共享密钥: 在 AC 设备「高级设置 - 开放接口」中配置
random:   客户端随机字串（同一 random 1 小时内只能使用 1 次）
md5:      md5(共享密钥 + random)，注意顺序不能颠倒

---

错误处理

所有接口返回统一格式：

字段	类型	说明
code	number	0=成功，1=失败
message	string	响应消息
data	*	响应数据（成功时存在）

const res = await ac.status.cpuUsage();
if (res.code === 0) {
  console.log(`CPU: ${res.data}%`);
} else {
  console.error(`获取失败: ${res.message}`);
}

// 网络错误会 reject，用 try/catch 捕获
try {
  await ac.status.version();
} catch (e) {
  console.error(`请求失败: ${e.message}`);
}

---

注意事项

1. 白名单：请求方 IP 必须在 AC 设备中配置为白名单
2. RESTful 服务：需在 AC 设备「高级设置 - 开放接口」中启用
3. 随机字串：同一 random 1 小时内只能使用 1 次
4. 策略不可创建：API 只支持查询策略，不能创建策略内容
5. 性能开销：流量排行类接口（userRank / appRank）开销较大，避免频繁请求
6. 语言切换：Status 接口支持 Accept-Language: zh-CN 切换中文；User/Group 接口语言跟随设备

---

项目结构

sangfor-ac-api/
├── index.js                # SDK 统一入口（SangforAC 类）
├── package.json
├── README.md               # 本文档
├── LICENSE                 # MIT 许可证
├── .gitignore
├── .npmignore
├── lib/
│   ├── auth.js             # 认证签名模块（MD5）
│   └── client.js           # HTTP 客户端封装
├── api/
│   ├── status.js           # Status 接口（14 个端点）
│   ├── user.js             # User 接口（10 个端点）
│   ├── group.js            # Group 接口（7 个端点）
│   ├── policy.js           # Policy 接口（2 个端点）
│   ├── bindinfo.js         # BindInfo 接口（6 个端点）
│   └── online-users.js     # OnlineUsers 接口（3 个端点）
└── examples/
    ├── config.js           # 示例配置（需根据实际情况修改）
    └── demo.js             # 全模块演示脚本

---

许可证

MIT