# 联软LV7000终端安全管理系统集成分析

> 基于联软LV7000系列LeagView5版本API接口说明文档（202210SP v1.1）
> 分析日期：2026-06-11
> 分析人：IT智能服务台项目组

---

## 一、联软API全景概览

### 1.1 认证机制

联软提供**三层认证**，灵活度高于火绒：

| 认证模式 | 说明 | 适用场景 |
|---------|------|---------|
| **白名单IP验证**（默认启用） | 配置`WhiteListServerIp`允许的调用方IP | 内网系统间调用 |
| **用户名密码验证** | 配置`ApiAccount`+`ApiPassword`，调用时传`apiAccount`+`apiPassword`+`validatekey` | 跨网段调用 |
| **一次性Token验证** | 先调`/token?act=getToken`获取token（默认30分钟有效），业务接口带`token`参数 | 安全要求高的场景 |

**端口**：`30098`（所有API统一端口）

**响应格式统一**：
```json
{
    "status": "SUCCESS | ERROR | INVALID | Exceed",
    "msg": "描述信息",
    "rows": [...],      // 数据列表（部分接口用"row"）
    "total": 100         // 总记录数
}
```

- `SUCCESS`：成功
- `ERROR`：参数错误/业务失败
- `INVALID`：无权限（IP不在白名单）
- `Exceed`：数据量超限（仅仿冒设备接口）

### 1.2 API端点分类总览（68个）

| 大类 | 数量 | 核心端点 | 对IT服务台价值 |
|------|------|---------|--------------|
| **终端设备** | 8 | `queryDevByParams`, `getDevAllInfo`, `querysoftwarebydev` | ⭐⭐⭐⭐⭐ 极高 |
| **准入控制** | 7 | `existOnlineUser`, `onlineUserList`, `forcedOffline`, `queryAccessLog` | ⭐⭐⭐⭐ 高 |
| **组织架构/用户** | 8 | `getUserInfo`, `getUserInfoByAccount`, `getAllOrgInfo`, `getDeptInfo` | ⭐⭐⭐⭐⭐ 极高（映射） |
| **审计查询** | 4 | `queryCommonAuditInfo`, `queryClientPatchAuditInfo` | ⭐⭐⭐ 中 |
| **安全策略** | 5 | `getSecScopeByName`, `addSecpolicyScope` 等 | ⭐⭐ 低 |
| **审批流程** | 12 | `queryapprovallist`, `doapproval`, `endapproval` 等 | ⭐⭐ 低 |
| **免检设备** | 6 | `addByMac`, `delByMac`, `queryCheckDevList` | ⭐⭐ 低 |
| **访客/外协** | 8 | `getGuestAccount`, `create`, `find`, `applyOutsource` | ⭐⭐ 低 |
| **其他** | 10 | `noticeAgentMsg`, `remoteWakeUp`, `queryCounterfeitList` 等 | ⭐⭐⭐ 中 |

### 1.3 核心API详解（对IT服务台有价值的端点）

#### 1.3.1 🔴 P0级 — 终端设备查询

**查询指定终端设备** `queryDevByParams`
- URL: `http://{IP}:30098/terminal?act=queryDevByParams`
- **这是最核心的接口**！返回字段包含：
```
istatus         // 终端状态（在线/离线）
strdevname      // 计算机名
strdevip        // IP地址
strmac          // MAC地址
strdeptname     // 所属部门名
strusername     // ⭐ 使用该终端的用户账号
struserdes      // ⭐ 用户姓名/描述
strswitchname   // 接入交换机名
strifname       // 交换机接口名
strmail         // 用户邮箱
strphone        // 用户电话
```

> **关键发现**：`strusername` + `struserdes` 字段**直接提供员工账号→终端的映射**！无需通过IP交叉匹配，这是联软相比火绒的最大优势。

**设备概要详细信息** `getDevAllInfo`
- URL: `http://{IP}:30098/devallinfoshowwithpaging?act=getDevAllInfo`
- 返回**极其详细**的设备信息：
```
equipment:
  strdevname, strip1, strmac, strnatip, macverdor, strdevtype
  strdeptname, strusername, struserdes
  dtdevuptime, dtdevdowntime, dtdevfirstfoundtime
  stros, strdomain, strserialnumber, strmainboardtype

equipmentdetail:
  devdetail:
    strverofuaagent      // 安全助手版本
    istatus              // 在线状态
    uniaccessagentstatus // UniAccess助手状态
    devassetno           // 设备资产号
    devgroup             // 设备所属设备组
  mainboardInformation[]  // 主板（厂商/型号/序列号）
  CPUInformation[]        // CPU（型号/核心/频率/缓存）
  MemoryInformation[]     // 内存（最大/当前/插槽数）
  HardDiskInformation[]   // 硬盘（类型/容量/型号/序列号）
  LogicalDiskInformation[] // 逻辑盘（卷标/文件系统/总量/可用/使用率）
  GraphicsCardInformation[] // 显卡
  NetworkCardInformation[]  // 网卡（名称/是否无线/厂商/MAC）
  DisplayInformation[]      // 显示器（厂商/型号/序列号/尺寸）
  PCIInformation[]          // PCI设备
  MemoryModuleDetails[]     // 内存条详情
  SoundCardInformation[]    // 声卡
  OperatingSystemInformation[] // 操作系统详情（语言/补丁/安装时间）
```

> 比火绒的`_info2`更详细！尤其是**逻辑磁盘使用率**（可直接判断磁盘满导致卡慢）和**显示器信息**（多屏配置排查）。

**设备安装软件信息** `querysoftwarebydev`
- URL: `http://{IP}:30098/software?act=querysoftwarebydev`
- 返回：
```
strdevname, strdevip, strmac, strdomain, strusername
softwares: [
  { strsoftware, strversion, strvendor, installdate }
]
```

#### 1.3.2 🔴 P0级 — 组织架构/用户

**查询用户信息** `getUserInfo`
- URL: `http://{IP}:30098/querydeptuser?act=getUserInfo`
- 返回：`deptid, userid, useraccount, username`

**用户账号查询** `getUserInfoByAccount`
- URL: `http://{IP}:30098/querydeptuser?act=getUserInfoByAccount`
- **直接通过账号查用户**，映射核心接口！

**查询部门和用户信息** `getAllOrgInfo`
- URL: `http://{IP}:30098/querydeptuser?act=getAllOrgInfo`
- 一次性获取所有部门+用户，可做全量同步

**查询部门信息** `getDeptInfo`
- URL: `http://{IP}:30098/querydeptuser?act=getDeptInfo`
- 返回所有部门（含父子关系）

#### 1.3.3 🟡 P1级 — 准入控制

**查询终端用户是否在线** `existOnlineUser`
- URL: `http://{IP}:30098/access/onlineUser?act=existOnlineUser`
- 参数：`username` + `strdevip`
- 返回：`data: 0`（不在线）/ `1`（在线）
- **可精确判断某员工在某IP是否当前在线**

**查询用户在线列表** `onlineUserList`
- URL: `http://{IP}:30098/onlineUser?act=onlineUserList`
- 按时间范围查在线用户（间隔不超过3个月）

**强制下线** `forcedOffline`
- URL: `http://{IP}:30098/nac?act=forcedOffline`
- ⚠️ 高危操作！将终端从网络强制断开
- 与火绒的`netctrl`隔离功能类似但机制不同

**终端入网日志** `queryAccessLog`
- URL: `http://{IP}:30098/access/queryInfo?act=queryAccessLog`
- 可查看终端入网历史

#### 1.3.4 🟡 P1级 — 终端操作

**通知助手弹出消息** `noticeAgentMsg`
- URL: `http://{IP}:30098/terminal?act=noticeAgentMsg`
- 向终端安全助手推送弹窗消息

**设备远程唤醒** `remoteWakeUp`
- URL: `http://{IP}:30098/terminal?act=remoteWakeUp`
- 通过IP+MAC唤醒关机/休眠的终端

**补丁安装审计** `queryClientPatchAuditInfo`
- URL: `http://{IP}:30098/terminalaudit?act=queryClientPatchAuditInfo`
- 查看终端补丁安装状态（补丁名/KB号/安装时间/是否成功）

**查询助手安装率** `queryAgentInstallRate`
- URL: `http://{IP}:30098/terminal?act=queryAgentInstallRate`
- 返回Windows/macOS分别的安装率

**查询终端补丁安装率** `queryAllMspatchInstallRate`
- URL: `http://{IP}:30098/terminal?act=queryAllMspatchInstallRate`
- 返回全公司补丁安装率

#### 1.3.5 🟢 P2级 — 审计与安全

**通用审计信息查询** `queryCommonAuditInfo`
- URL: `http://{IP}:30098/auditinfo?act=queryCommonAuditInfo`
- 支持所有通用审计类型（文件操作/进程控制等）

**仿冒设备查询** `queryCounterfeitList`
- URL: `http://{IP}:30098/access/queryInfo?act=queryCounterfeitList`
- 查询准入仿冒信息（发现仿冒设备告警）

**屏幕录像审计** `listScreenAuditInfo`
- URL: `http://{IP}:30098/auditinfo?act=listScreenAuditInfo`
- 获取终端屏幕录像审计信息

**Syslog推送**
- 联软支持将审计日志通过Syslog推送到第三方平台（UDP 514）
- 吞吐量：约100条/秒
- 支持：文件读写审计、非授权外联审计、打印审计、漏洞审计、进程检测审计、安全U盘审计

---

## 二、与火绒的能力对比

### 2.1 功能矩阵对比

| 能力维度 | 火绒 | 联软 | 对IT服务台价值 |
|---------|------|------|--------------|
| **员工↔终端映射** | ❌ 只有computer_name | ✅ **strusername+struserdes** | 🔴 **最关键差异** |
| **终端基本信息** | ✅ `_list`（client_id/name/ip/mac/在线） | ✅ `queryDevByParams`（更丰富） | 相当 |
| **终端详细信息** | ✅ `_info2`（硬件+软件+资产+网络） | ✅ `getDevAllInfo`（**更详细**：含磁盘使用率/显示器/内存条详情） | 联软胜 |
| **病毒事件** | ✅ `_virus_events`（病毒统计+处理状态） | ❌ 无专门接口 | **火绒独有** |
| **高危漏洞** | ✅ `_leak`（漏洞等级+详情） | ✅ `queryClientPatchAuditInfo`（补丁审计） | 火绒更直观 |
| **终端隔离** | ✅ `netctrl`（网络隔离/解除） | ✅ `forcedOffline`（强制下线） | 火绒更精细（可隔离+解除） |
| **远程扫描** | ✅ `_create`（快速/全盘/自定义扫描） | ❌ 无 | **火绒独有** |
| **远程唤醒** | ❌ 无 | ✅ `remoteWakeUp` | **联软独有** |
| **消息推送** | ✅ `_create`(message) | ✅ `noticeAgentMsg` | 相当 |
| **准入控制** | ❌ 无 | ✅ `existOnlineUser`+`forcedOffline`+`queryAccessLog` | **联软独有** |
| **软件管理** | ✅ `_search`（软件安装率/版本分布） | ✅ `querysoftwarebydev`（按设备查软件） | 联软更实用 |
| **组织架构** | ❌ 无 | ✅ SCIM同步+部门/用户查询 | **联软独有** |
| **审计日志** | ❌ 无 | ✅ Syslog推送+通用审计查询 | **联软独有** |
| **仿冒设备** | ❌ 无 | ✅ `queryCounterfeitList` | **联软独有** |
| **审批流程** | ❌ 无 | ✅ 完整审批流程API | 低价值 |
| **屏幕录像** | ❌ 无 | ✅ 审计信息+图片导出 | 低价值 |

### 2.2 核心结论

> **火绒 = 安全防护**（杀毒+漏洞+隔离+扫描）
> **联软 = 终端管理**（准入+硬件+软件+映射+审计）
> 
> **两者高度互补，不存在替代关系，应双系统集成！**

---

## 三、产品维度分析

### 3.1 联软独有高价值场景

| 场景 | 联软API | 用户体验 |
|------|---------|---------|
| **员工报修「电脑卡/慢」** | `getDevAllInfo` | 坐席直接看到磁盘使用率34%→11%、内存16GB/32GB、CPU负载，一秒定位瓶颈 |
| **员工报修「网络连不上」** | `existOnlineUser` + `queryAccessLog` | 坐席查看该员工终端当前是否准入在线、最近入网记录、是否被策略阻断 |
| **员工报修「电脑开不了机」** | `remoteWakeUp` | 坐席远程唤醒终端（WOL），员工无需等待IT到现场 |
| **员工问「我装了什么软件」** | `querysoftwarebydev` | 输入员工账号→自动列出已安装软件+版本+安装日期 |
| **IT查「谁用了这个IP」** | `queryDevByParams` | 按IP反查使用人、部门、MAC，网络冲突排查利器 |
| **安全巡检「补丁安装率」** | `queryAllMspatchInstallRate` + `queryClientPatchAuditInfo` | 管理后台展示补丁合规率 |

### 3.2 联软+火绒联合场景

| 场景 | 联软提供 | 火绒提供 | 联合效果 |
|------|---------|---------|---------|
| **坐席打开会话** | 员工→终端映射（strusername） | 终端安全画像（漏洞+病毒） | 一键获知「谁的电脑+什么安全状态」 |
| **安全事件响应** | `forcedOffline`快速断网 | `netctrl`精细隔离 | 双重保障：先联软断网→火绒隔离 |
| **磁盘满排查** | `getDevAllInfo`磁盘使用率 | `_info2`软件列表 | 联软看磁盘空间→火绒查大文件软件 |
| **补丁管理** | `queryClientPatchAuditInfo`安装审计 | `_leak`高危漏洞列表 | 联软看补丁安装结果→火绒看漏洞风险 |
| **终端画像** | 硬件详情+准入状态+资产号 | 安全评分+病毒事件 | 360°终端全景 |

### 3.3 集成功能规划（按优先级）

#### P0 — 核心查询+映射（阶段三 3A-3B）

| 功能 | 用户侧效果 | 涉及API |
|------|-----------|---------|
| **员工→终端映射服务** | 输入员工账号→返回终端列表（IP/MAC/计算机名/部门/在线状态） | `queryDevByParams` + `getUserInfoByAccount` |
| **终端详细信息卡片** | 坐席打开会话→自动展示该员工终端的完整硬件+软件信息 | `getDevAllInfo` + `querysoftwarebydev` |
| **终端在线状态查询** | AI Wingman自动检测→提示终端是否在线 | `existOnlineUser` |

#### P1 — 操作+控制（阶段三 3C + 阶段四）

| 功能 | 用户侧效果 | 涉及API |
|------|-----------|---------|
| **远程唤醒终端** | 坐席一键唤醒休眠/关机的终端 | `remoteWakeUp` |
| **推送助手消息** | 向员工终端弹窗通知（如「请重启电脑安装补丁」） | `noticeAgentMsg` |
| **强制下线** | 安全事件→坐席一键断网（与火绒隔离互为补充） | `forcedOffline` |
| **补丁审计查询** | 查看某终端补丁安装状态 | `queryClientPatchAuditInfo` |
| **入网日志查询** | 排查网络问题时查看终端入网历史 | `queryAccessLog` |

#### P2 — 管理与运营（阶段四 4B）

| 功能 | 用户侧效果 | 涉及API |
|------|-----------|---------|
| **助手安装率看板** | 管理后台展示公司安全助手安装率 | `queryAgentInstallRate` |
| **补丁合规率看板** | 管理后台展示补丁安装率 | `queryAllMspatchInstallRate` |
| **仿冒设备告警** | 发现仿冒设备自动推送告警 | `queryCounterfeitList` |
| **Syslog审计日志** | 联软审计事件实时推送到IT服务台 | Syslog接口 |

---

## 四、开发维度分析

### 4.1 后端模块设计

```
backend/app/
├── integrations/
│   ├── __init__.py
│   ├── base.py                     # 集成基类
│   ├── huorong/                    # 火绒集成（已有设计）
│   │   ├── client.py
│   │   ├── config.py
│   │   ├── models.py
│   │   ├── cache.py
│   │   └── exceptions.py
│   ├── leagsoft/                   # 联软集成模块
│   │   ├── __init__.py
│   │   ├── client.py               # 联软API客户端（认证+请求）
│   │   ├── config.py               # 配置（BaseUrl/账号密码/Token）
│   │   ├── models.py               # 数据模型（Pydantic）
│   │   ├── cache.py                # 缓存策略
│   │   └── exceptions.py           # 自定义异常
│   └── mapping/                    # 🆕 统一映射服务
│       ├── __init__.py
│       ├── service.py              # 员工→终端映射核心逻辑
│       └── models.py               # 映射数据模型
├── api/
│   └── integrations.py             # 集成API路由
└── services/
    └── integration_service.py      # 集成业务逻辑
```

### 4.2 认证实现

联软推荐使用**一次性Token模式**（安全性最高）：

```python
import httpx
from datetime import datetime, timedelta

class LeagsoftClient:
    """联软API客户端"""
    
    def __init__(self, base_url: str, api_account: str, api_password: str):
        self.base_url = base_url       # 如 http://leagsoft.oa.servyou-it.com:30098
        self.api_account = api_account
        self.api_password = api_password
        self._token: str | None = None
        self._token_expire: datetime | None = None
    
    async def _ensure_token(self) -> str:
        """
        确保token有效，过期则重新获取
        - 联软token默认30分钟有效
        - 提前5分钟刷新，避免临界过期
        """
        if self._token and self._token_expire and datetime.now() < self._token_expire - timedelta(minutes=5):
            return self._token
        
        async with httpx.AsyncClient(timeout=10) as client:
            resp = await client.get(f"{self.base_url}/token", params={"act": "getToken"})
            data = resp.json()
            # 解析token（具体字段需根据实际返回确认）
            self._token = data.get("token", "")
            self._token_expire = datetime.now() + timedelta(minutes=25)  # 保守25分钟
        
        return self._token
    
    async def query_dev_by_params(self, username: str = None, devip: str = None, 
                                   mac: str = None, devname: str = None) -> list[dict]:
        """
        查询终端设备
        - username: 员工账号（映射核心参数）
        - devip: 终端IP
        - mac: MAC地址
        - devname: 计算机名
        - 支持多条件组合查询
        """
        token = await self._ensure_token()
        params = {"act": "queryDevByParams", "token": token}
        form_data = {}
        if username:
            form_data["strusername"] = username
        if devip:
            form_data["strdevip"] = devip
        if mac:
            form_data["strmac"] = mac
        if devname:
            form_data["strdevname"] = devname
        
        async with httpx.AsyncClient(timeout=10) as client:
            resp = await client.post(
                f"{self.base_url}/terminal",
                params=params,
                data=form_data
            )
            result = resp.json()
        
        if result.get("status") != "SUCCESS":
            raise LeagsoftAPIError(result.get("msg", "未知错误"))
        
        return result.get("rows", [])
```

### 4.3 缓存策略

| 数据类型 | 缓存时间 | 理由 |
|---------|---------|------|
| 终端基本信息 (`queryDevByParams`) | 5分钟 | 终端上下线变化较频繁 |
| 终端详细信息 (`getDevAllInfo`) | 30分钟 | 硬件信息极少变化 |
| 软件安装信息 (`querysoftwarebydev`) | 1小时 | 软件安装变化慢 |
| 在线状态 (`existOnlineUser`) | 1分钟 | 需较实时 |
| 组织架构 (`getAllOrgInfo`) | 24小时 | 组织变更极少 |
| 用户信息 (`getUserInfoByAccount`) | 24小时 | 用户信息变更少 |
| 补丁审计 (`queryClientPatchAuditInfo`) | 1小时 | 补丁安装周期为天级 |

### 4.4 员工→终端映射方案（重大升级）

#### 原方案回顾

之前火绒集成分析中，因火绒API只有`computer_name`无员工账号，提出了三种映射方案：

| 方案 | 原理 | 缺点 |
|------|------|------|
| A. computer_name匹配 | 依赖命名规范 | 不稳定 |
| B. eHR+火绒IP交叉匹配 | eHR取IP→火绒查终端 | 需eHR接口，IP可能变化 |
| C. 手动绑定 | 坐席手动关联 | 运营成本高 |

#### 新方案：联软直接映射（方案D）⭐推荐

**核心发现**：联软 `queryDevByParams` 接口直接返回 `strusername`（员工账号）和 `struserdes`（员工姓名），且总部员工必须安装联软安全助手，因此**联软拥有最准确的员工↔终端映射数据**。

```
联软 queryDevByParams(strusername="songxian")
    ↓ 返回
[
  {strdevname: "DESKTOP-SX001", strdevip: "10.8.11.21", strmac: "0C:C4:7A:0C:75:B5",
   strusername: "songxian", struserdes: "宋献", strdeptname: "IT部", istatus: "在线"},
  {strdevname: "DESKTOP-SX002", strdevip: "10.8.11.22", strmac: "0C:C4:7A:0C:75:B6",
   strusername: "songxian", struserdes: "宋献", strdeptname: "IT部", istatus: "离线"}
]
```

#### 映射架构（多源融合）

```
                    ┌──────────────────────────────────────────┐
                    │         IT服务台 统一映射服务              │
                    │    (mapping/service.py)                  │
                    └───────┬──────────┬──────────┬────────────┘
                            │          │          │
                   ┌────────▼──┐  ┌────▼─────┐  ┌─▼──────────┐
                   │  联软      │  │  aTrust   │  │  eHR       │
                   │  (主源)    │  │  (VPN源)  │  │  (辅助源)  │
                   └───────────┘  └──────────┘  └────────────┘
                        │              │              │
                        ▼              ▼              ▼
                   总部终端映射    远程办公映射     人员基础信息
                   (最准确)      (VPN连接时准确)   (无终端信息)
```

**映射优先级策略**：

| 场景 | 数据源 | 匹配键 | 准确度 | 说明 |
|------|--------|--------|--------|------|
| 总部办公终端 | **联软** | `strusername` = 员工账号 | ⭐⭐⭐⭐⭐ | 最准确，安全助手必装 |
| 外网VPN终端 | **aTrust** | VPN登录账号 = 员工账号 | ⭐⭐⭐⭐⭐ | 远程办公时最准确 |
| eHR补充 | eHR | 员工工号 = 员工账号 | ⭐⭐⭐ | 无终端映射，仅人员信息 |
| 火绒安全数据 | 火绒 | 通过联软映射获得`client_id`→查安全 | ⭐⭐⭐⭐ | 依赖联软映射做桥梁 |

**映射实现**：

```python
class TerminalMappingService:
    """
    统一员工→终端映射服务
    优先级: 联软(主) > aTrust(VPN) > 手动绑定
    """
    
    async def get_employee_terminals(self, employee_id: str) -> list[TerminalInfo]:
        """
        根据员工ID获取关联的终端列表
        
        策略:
        1. 先查联软（最准确，覆盖总部终端）
        2. 联软无结果 → 查aTrust（覆盖VPN终端）
        3. 都无结果 → 返回空，标记为「未发现终端」
        """
        # Step 1: 联软查询
        leagsoft_terminals = await self.leagsoft_client.query_dev_by_params(
            username=employee_id
        )
        if leagsoft_terminals:
            return [self._parse_leagsoft_terminal(t) for t in leagsoft_terminals]
        
        # Step 2: aTrust查询（后续实现）
        # atrust_terminals = await self.atrust_client.query_user_devices(employee_id)
        # if atrust_terminals:
        #     return atrust_terminals
        
        # Step 3: 无结果
        return []
    
    async def get_terminal_security(self, employee_id: str) -> TerminalSecurityInfo:
        """
        获取员工终端的安全信息（跨系统聚合）
        
        流程:
        1. 联软获取终端列表 → 得到strdevip/strmac
        2. 用strdevip去火绒查安全状态
        3. 聚合联软硬件+火绒安全 → 完整画像
        """
        # Step 1: 联软获取终端
        terminals = await self.get_employee_terminals(employee_id)
        if not terminals:
            return TerminalSecurityInfo(available=False, reason="未发现关联终端")
        
        terminal = terminals[0]  # 取主终端
        
        # Step 2: 火绒查安全（用IP或computer_name匹配）
        huorong_info = await self.huorong_client.query_by_ip(terminal.ip)
        
        # Step 3: 聚合
        return TerminalSecurityInfo(
            terminal=terminal,           # 联软硬件信息
            security=huorong_info,       # 火绒安全信息
            available=True
        )
```

### 4.5 前端集成设计

#### 坐席端新增

```
坐席工作台
└── 右侧面板
    └── 「终端信息」标签页（替代原「终端安全」，合并联软+火绒）
        ├── 终端概要卡片（联软数据）
        │   ├── 在线状态 🟢/🔴 + IP地址
        │   ├── 计算机名 + 员工账号
        │   ├── 操作系统版本
        │   ├── 硬件概要（CPU/内存/磁盘使用率）
        │   ├── 设备资产号
        │   └── 安全助手版本
        ├── 安全状态卡片（火绒数据）
        │   ├── 安全评分
        │   ├── 🔴 高危漏洞 (N个)
        │   ├── 🟡 未处理病毒事件 (N个)
        │   └── 🟢 安全状态正常
        ├── 软件列表（联软数据）
        │   └── 已安装软件 + 版本 + 安装日期
        └── 快速操作
            ├── 📡 远程唤醒 (联软)
            ├── 📢 推送消息 (联软/火绒)
            ├── 🛡️ 快速扫描 (火绒)
            ├── 🔒 强制下线 (联软) / 隔离终端 (火绒)
            └── 🔓 解除隔离 (火绒)
```

### 4.6 开发风险与应对

| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|---------|
| 联软API账户/密码未申请 | 无法调用任何接口 | 中 | 提前联系信息安全/终端安全团队 |
| 内网地址不通 | 开发环境无法调试 | 中 | 需VPN或开发机部署在内网 |
| Token过期处理 | 长时间运行后API调用失败 | 中 | 实现自动刷新token，提前5分钟续期 |
| IP白名单未配置 | 返回INVALID | 中 | 确认部署服务器IP加入白名单 |
| API字段名不一致 | 部分接口返回字段与文档不符 | 低 | 先用Postman验证，编写适配层 |
| 联软版本差异 | API端点可能不存在 | 低 | 确认当前版本是否为202210SP |
| 查询数据量过大 | 部分接口有数据量限制（仿冒设备默认1万条） | 低 | 分页查询+限制时间范围 |

---

## 五、安全维度分析

### 5.1 认证安全

| 风险项 | 等级 | 说明 | 建议 |
|--------|------|------|------|
| API账户密码泄露 | **严重** | 泄露后可调用所有联软API，包括强制下线 | 密码存环境变量，**禁止**写入代码 |
| Token泄露 | 高 | Token有效期内可被冒用 | 使用HTTPS（如有）；Token存储在内存不落盘 |
| IP白名单过宽 | 中 | 白名单IP范围过大增加攻击面 | 仅添加必要的服务器IP |

**认证方式建议**：

| 场景 | 推荐认证方式 | 理由 |
|------|------------|------|
| 内网服务器间调用 | IP白名单 + 一次性Token | 安全性最高 |
| 开发调试 | IP白名单 + 用户名密码 | 方便调试 |
| 生产环境 | **三种全部启用** | 纵深防御 |

### 5.2 操作安全

| 操作 | 风险等级 | 安全要求 |
|------|---------|---------|
| 查询终端设备 (`queryDevByParams`) | 🟢 低 | 无特殊要求 |
| 查询终端详情 (`getDevAllInfo`) | 🟢 低 | 无特殊要求 |
| 查询在线状态 (`existOnlineUser`) | 🟢 低 | 无特殊要求 |
| 推送助手消息 (`noticeAgentMsg`) | 🟡 中 | 记录审计日志；限制频率（同终端5分钟1条） |
| 远程唤醒 (`remoteWakeUp`) | 🟡 中 | 记录审计日志；仅坐席可操作 |
| **强制下线** (`forcedOffline`) | 🔴 **高** | **必须**二次确认 + 审计日志 + 仅admin角色 |
| Syslog推送 | 🟢 低 | 只读，无风险 |

**强制下线 vs 火绒隔离的区别**：

| 维度 | 联软强制下线 | 火绒网络隔离 |
|------|-----------|-----------|
| 机制 | 准入控制断网（802.1X） | 终端agent执行隔离 |
| 彻底性 | ⭐⭐⭐⭐⭐ 非常彻底（交换机层面断网） | ⭐⭐⭐⭐ 较彻底（终端层面断网） |
| 恢复 | 需重新认证入网 | 调用API即可解除 |
| 影响范围 | 该终端所有网络 | 可配置例外（如仅隔离外网） |
| 推荐场景 | 确认中毒/仿冒，紧急切断 | 可疑行为，需隔离观察 |

### 5.3 数据安全

| 风险项 | 说明 | 建议 |
|--------|------|------|
| 员工账号信息 | 联软返回员工账号/姓名/邮箱/电话 | H5用户端不展示；坐席端仅展示必要信息 |
| 终端敏感信息 | MAC/IP/序列号等 | 同火绒策略：坐席端可见，用户端不可见 |
| 硬件详情 | 包含主板序列号等资产信息 | 后端过滤后再传前端，不暴露内部序列号 |
| 组织架构 | 全量部门+用户数据 | 仅同步必要字段，不存储完整组织架构 |

---

## 六、aTrust集成方案

> ✅ aTrust OpenAPI V3文档已获取并完成分析（2026-06-11），详见 `docs/aTrust零信任系统集成分析.md`

### 6.1 系统信息

| 项目 | 说明 |
|------|------|
| 产品 | 深信服aTrust零信任访问控制系统 |
| API版本 | OpenAPI V3（适用于≥2.4.10版本） |
| 端点数 | **104个**（10大类） |
| 认证方式 | HMAC-SHA256签名（4个必填Header: x-ca-sign/key/timestamp/nonce） |
| 默认端口 | 4433（HTTPS） |
| IP白名单 | 支持 |

### 6.2 核心P0接口

| 接口 | 路径 | 方法 | 核心价值 |
|------|------|------|---------|
| **查询在线用户** | /api/v1/monitor/getUserStatus | GET | VPN在线状态+remoteIp+vips(虚拟IP)+os+browser |
| **查询全量终端** | /api/v1/device/queryAll | POST | 按绑定用户查询终端（bindUserList过滤） |
| **查询单个终端** | /api/v1/device/query | GET | 终端详情+bindUsers(绑定用户列表)+macList |

### 6.3 核心P1接口

| 接口 | 路径 | 方法 | 安全等级 |
|------|------|------|---------|
| **踢出在线用户** | /api/v1/monitor/kickoutUsers | POST | 🔴 高危（需二次确认+审计） |
| **终端绑定用户** | /api/v1/device/assignUser | POST | 🟡 中 |
| **查询用户详情** | /api/v3/user/queryByName | GET | 🟢 低 |

### 6.4 aTrust映射字段

| 映射路径 | 字段 | 说明 |
|---------|------|------|
| **在线用户→员工** | `name`（用户名） | 如果与公司域账号一致，直接映射employee_id |
| **在线用户→虚拟IP** | `vips[].ip` | VPN分配的内网IP，可用于火绒交叉匹配 |
| **终端→绑定用户** | `bindUsers[].bindUser` | 终端绑定的用户名 |
| **用户→外部ID** | `externalId` | **可设置为工号，实现直接映射** |
| **终端→MAC** | `macList` | MAC地址列表，与联软交叉匹配 |

### 6.5 与联软的互补关系

| 能力 | 联软（内网主源） | aTrust（VPN源） | 互补效果 |
|------|---------------|---------------|---------|
| 内网终端映射 | ⭐⭐⭐⭐⭐ strusername | ⭐⭐⭐ 部分覆盖 | 联软主导 |
| 远程/VPN终端 | ⚠️ 可能未覆盖 | ⭐⭐⭐⭐⭐ 核心覆盖 | aTrust补全 |
| VPN会话数据 | ❌ 无 | ✅ 唯一数据源 | 不可替代 |
| 踢出能力 | forcedOffline(准入下线) | kickoutUsers(VPN踢出) | 双通道 |
| 终端授信 | ❌ 无 | ✅ trusted字段 | aTrust独有 |

### 6.6 集成优先级

aTrust集成为**P1优先级**（联软P0之后），因为：
1. VPN连接问题是IT服务台高频场景
2. aTrust的`vips`虚拟IP可用于火绒交叉匹配，补全远程终端安全画像
3. aTrust API文档已获取，可直接开发
4. 104个端点中仅需3-5个P0接口，开发量可控

---

## 七、三系统集成总览

### 7.1 系统定位

```
┌──────────────────────────────────────────────────────────────┐
│                    IT智能服务台                               │
│                  （统一集成层）                               │
│                                                              │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   联软      │  │   火绒      │  │   aTrust   │             │
│  │  终端管理   │  │  终端安全   │  │  远程接入   │             │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘             │
│        │               │               │                    │
│  员工↔终端映射    安全态势+隔离    VPN状态+远程IP           │
│  硬件+软件详情    病毒+漏洞+扫描   VPN连接审计              │
│  准入+远程唤醒    网络隔离/解除    认证状态                  │
│  补丁+审计日志    软件合规统计    虚拟IP分配                 │
└──────────────────────────────────────────────────────────────┘
```

### 7.2 集成优先级与排程

| 阶段 | 系统 | 功能 | 预计周期 | 前置条件 |
|------|------|------|---------|---------|
| **P0** | 联软 | 员工→终端映射 + 终端详情查询 | ~2周 | 联软API账户+白名单 |
| **P0** | 火绒 | 终端安全画像 + 漏洞/病毒查询 | ~2周 | 火绒AccessKey |
| **P1** | 联软 | 远程唤醒 + 消息推送 + 准入查询 | ~1周 | P0已完成 |
| **P1** | 火绒 | 远程扫描 + 隔离/解除 | ~1周 | P0已完成 |
| **P1** | aTrust | VPN状态 + 远程终端映射 | ~2周 | aTrust API文档 |
| **P2** | 联软+火绒 | 管理后台安全态势看板 | ~1周 | P0+P1已完成 |
| **P2** | 联软 | Syslog审计日志对接 | ~1周 | 联软Syslog配置 |

### 7.3 统一数据模型

```python
class UnifiedTerminalInfo:
    """统一终端信息模型（聚合联软+火绒+aTrust）"""
    
    # 基础标识（联软提供）
    computer_name: str          # 计算机名
    ip: str                    # IP地址
    mac: str                   # MAC地址
    employee_id: str           # 使用人账号
    employee_name: str         # 使用人姓名
    department: str            # 所属部门
    
    # 在线状态（联软+aTrust）
    is_online: bool            # 是否在线
    online_source: str         # "leagsoft" | "atrust" | "offline"
    last_online_time: str      # 最后在线时间
    
    # 硬件信息（联软 getDevAllInfo）
    os_version: str            # 操作系统版本
    cpu: str                   # CPU型号
    memory_gb: int             # 内存(GB)
    disk_total_gb: float       # 磁盘总量(GB)
    disk_usage_pct: float      # 磁盘使用率(%)
    
    # 安全信息（火绒提供）
    security_score: int | None       # 安全评分
    high_risk_leaks: int | None       # 高危漏洞数
    uncleaned_virus: int | None       # 未处理病毒数
    last_scan_time: str | None        # 最近扫描时间
    
    # 准入信息（联软提供）
    agent_version: str | None        # 安全助手版本
    patch_install_rate: float | None  # 补丁安装率
    
    # VPN信息（aTrust提供）
    vpn_online: bool | None           # VPN是否在线
    vpn_virtual_ip: str | None        # VPN虚拟IP
    vpn_last_connect: str | None     # 最近VPN连接时间
```

---

## 八、对接前准备清单

### 联软

#### 必须完成（阻塞性）

- [ ] **申请API账户**：联系终端安全团队，获取`ApiAccount` + `ApiPassword`
- [ ] **配置IP白名单**：将IT服务台服务器IP加入联软白名单
- [ ] **确认网络可达**：确认开发/部署服务器可访问联软系统（端口30098）
- [ ] **确认联软版本**：确认当前版本是否为202210SP，API文档是否匹配

#### 建议完成（非阻塞）

- [ ] **确认员工账号映射**：验证联软中`strusername`字段是否为公司企微/域账号
- [ ] **确认数据量级**：了解联软管理的终端数量，评估查询性能
- [ ] **确认安全助手安装率**：了解公司终端安全助手安装覆盖率
- [ ] **准备测试终端**：准备1-2台测试终端用于开发调试

### aTrust

- [ ] **获取API文档**：联系网络/信息安全团队获取aTrust API文档
- [ ] **确认认证方式**：了解aTrust API认证机制
- [ ] **确认映射数据格式**：了解aTrust中员工↔终端的映射字段

---

## 九、总结

### 9.1 核心结论

1. **联软是终端映射的金钥匙**：`strusername`字段直接打通员工→终端的映射，这是火绒和eHR都无法提供的关键能力
2. **联软+火绒高度互补**：联软管「终端画像+准入」，火绒管「安全态势+隔离」，无替代关系
3. **aTrust补全远程办公**：联软覆盖内网终端，aTrust覆盖VPN终端，两者结合实现100%覆盖
4. **三系统联合映射是最佳方案**：联软(主)+aTrust(VPN)+eHR(辅助)，取代之前推荐的IP交叉匹配方案
5. **实现成本低**：联软API为标准HTTP+JSON，认证简单，无需安装agent

### 9.2 映射策略升级总结

| 维度 | 旧方案（仅火绒） | 新方案（三系统） |
|------|----------------|----------------|
| 映射准确度 | ⭐⭐⭐（IP交叉匹配） | ⭐⭐⭐⭐⭐（联软直接映射） |
| 覆盖范围 | 仅内网在线终端 | 内网+VPN全覆盖 |
| 实现复杂度 | 需eHR+火绒双接口 | 仅联软单接口 |
| 维护成本 | 高（IP变化需定期校验） | 低（联软实时更新） |
| 前置依赖 | eHR接口+火绒接口 | 联软接口 |

### 9.3 一句话总结

> 联软是IT智能服务台打通「员工↔终端」映射的关键系统，与火绒形成「管理+安全」双引擎，加上aTrust补全远程办公，三系统集成将实现终端问题排查的360°全景视角。