# 设备ID限制机制

<cite>
**本文档引用的文件**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://api/merchant/v1/model.go)
- [v_1_merchant_deploy_info.go](file://internal/model/do/v_1_merchant_deploy_info.go)
- [v_1_restrict_client_access_record.go](file://internal/model/do/v_1_restrict_client_access_record.go)
- [v_1_restrict_client_access_ip_relation.go](file://internal/model/do/v_1_restrict_client_access_ip_relation.go)
- [restriction.go](file://internal/model/restriction.go)
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
</cite>

## 目录
1. [简介](#简介)
2. [设备ID限制机制概述](#设备id限制机制概述)
3. [设备ID记录的采集与存储](#设备id记录的采集与存储)
4. [设备限制规则的配置与生效](#设备限制规则的配置与生效)
5. [设备ID匹配与验证机制](#设备id匹配与验证机制)
6. [设备伪装检测与代理识别](#设备伪装检测与代理识别)
7. [设备ID生成与隐私保护](#设备id生成与隐私保护)
8. [最佳实践与应用场景](#最佳实践与应用场景)
9. [与用户认证系统的集成](#与用户认证系统的集成)
10. [总结](#总结)

## 简介
本文档详细阐述了kami_backend系统中设备ID限制机制的实现原理和工作流程。该机制通过采集、存储和匹配设备标识信息，实现了基于设备级别的访问控制，有效防止多开、设备级滥用等安全问题。文档深入分析了设备ID的采集、存储、匹配和验证全过程，以及与用户认证系统的集成方式。

## 设备ID限制机制概述
设备ID限制机制是kami_backend系统中重要的安全控制组件，旨在通过设备标识实现精细化的访问控制。该机制允许系统管理员根据业务需求配置不同的设备限制策略，包括是否限制设备、是否检测代理、是否限制卡密等。当用户请求系统服务时，系统会采集设备相关信息，与预设的限制规则进行匹配，从而决定是否允许访问。

设备ID限制机制的核心功能包括：
- 设备信息的采集与加密传输
- 设备ID的存储与管理
- 设备限制规则的配置与查询
- 设备匹配与访问控制决策
- 代理检测与设备伪装识别

**Section sources**
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go#L17-L69)
- [model.go](file://api/merchant/v1/model.go#L75-L92)

## 设备ID记录的采集与存储
设备ID记录的采集与存储是设备限制机制的基础，涉及前端信息采集、后端接收处理和数据库持久化三个主要环节。

### 信息采集流程
系统通过前端JavaScript代码采集设备信息，包括IP地址列表、设备ID、设备型号和用户代理字符串。采集到的信息经过AES-CBC加密和Base64编码后，通过API接口发送到后端服务器。

### 后端处理流程
后端通过`UserInfoCollection`控制器接收加密数据，执行以下处理步骤：
1. 使用预设密钥解密数据
2. 验证数据签名确保完整性
3. 提取设备相关信息
4. 调用服务层存储设备信息

### 数据库存储结构
设备信息存储在两个主要数据库表中：

**设备访问记录表 (restrict_client_access_record)**
| 字段 | 类型 | 描述 |
|------|------|------|
| id | uint | 主键ID |
| visitor_id | string | 访问ID（设备ID） |
| device_model | string | 设备型号 |
| user_agent | string | 用户浏览器代理 |
| is_use_proxy | bool | 是否使用代理 |

**设备IP关联表 (restrict_client_access_ip_relation)**
| 字段 | 类型 | 描述 |
|------|------|------|
| id | uint | 主键ID |
| ip | string | IP地址 |
| is_remote_ip | bool | 是否为远程IP |
| restrict_ip_record_id | int | 限制IP详情ID |
| restrict_client_access_record_id | int | 设备访问记录ID |
| session_id | string | 会话ID |

```mermaid
erDiagram
restrict_client_access_record {
uint id PK
string visitor_id UK
string device_model
string user_agent
bool is_use_proxy
timestamp created_at
timestamp updated_at
timestamp deleted_at
}
restrict_client_access_ip_relation {
uint id PK
string ip
bool is_remote_ip
int restrict_ip_record_id FK
int restrict_client_access_record_id FK
string session_id
timestamp created_at
timestamp updated_at
timestamp deleted_at
}
restrict_client_access_record ||--o{ restrict_client_access_ip_relation : "1:N"
```

**Diagram sources**
- [v_1_restrict_client_access_record.go](file://internal/model/do/v_1_restrict_client_access_record.go#L12-L22)
- [v_1_restrict_client_access_ip_relation.go](file://internal/model/do/v_1_restrict_client_access_ip_relation.go#L12-L23)

**Section sources**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L17-L42)

## 设备限制规则的配置与生效
设备限制规则的配置与生效流程是实现灵活访问控制的关键，涉及规则定义、策略配置和实时验证三个阶段。

### 规则配置参数
设备限制规则通过商户部署配置进行定义，主要参数包括：

| 参数 | 类型 | 描述 |
|------|------|------|
| isRestrictDevice | bool | 是否限制设备 |
| isRestrictAgent | bool | 是否检测代理 |
| isRestrictCardPass | bool | 是否限制卡密 |
| isRestrictIp | bool | 是否限制IP |
| isRestrictInternalIp | bool | 是否限制局域网IP |
| restrictArea | []string | 限制地区列表 |

### 规则生效流程
当用户发起请求时，系统按照以下流程验证设备限制规则：

```mermaid
flowchart TD
A[用户请求] --> B{获取限制策略}
B --> C{是否限制卡密?}
C --> |是| D{卡密是否存在限制?}
D --> |是| E[拒绝访问]
C --> |否| F{是否限制设备?}
F --> |是| G{设备是否被禁用?}
G --> |是| E
F --> |否| H{是否检测代理?}
H --> |是| I{是否使用代理?}
I --> |是| E
H --> |否| J{是否限制IP?}
J --> |是| K{IP是否存在限制?}
K --> |是| E
J --> |否| L[允许访问]
E --> M[返回拒绝]
L --> N[返回允许]
```

**Diagram sources**
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go#L17-L69)
- [model.go](file://api/merchant/v1/model.go#L75-L92)

**Section sources**
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go#L17-L69)
- [v_1_merchant_deploy_info.go](file://internal/model/do/v_1_merchant_deploy_info.go#L12-L43)

## 设备ID匹配与验证机制
设备ID匹配与验证机制是设备限制功能的核心，负责判断特定设备是否被限制访问系统资源。

### 设备ID匹配流程
系统通过`IsRestrictDevice`方法实现设备ID匹配，其工作原理如下：

1. 接收设备ID作为输入参数
2. 在`restrict_ip_order_access`表中查询该设备ID的记录
3. 检查是否存在状态为"禁用"的记录
4. 如果存在禁用记录，返回true（设备被限制）
5. 如果不存在禁用记录，返回false（设备未被限制）

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务层"
participant Database as "数据库"
Client->>Controller : 发送设备ID验证请求
Controller->>Service : 调用IsRestrictDevice(deviceId)
Service->>Database : 查询restrict_ip_order_access表
Database-->>Service : 返回匹配记录
Service-->>Controller : 返回是否限制结果
Controller-->>Client : 返回验证结果
```

**Diagram sources**
- [restriction.go](file://internal/logic/restriction/restriction.go#L164-L172)
- [restriction.go](file://internal/service/restriction.go#L18-L49)

**Section sources**
- [restriction.go](file://internal/logic/restriction/restriction.go#L164-L172)
- [restriction.go](file://internal/service/restriction.go#L48-L48)

## 设备伪装检测与代理识别
设备伪装检测与代理识别机制用于防范用户通过技术手段绕过设备限制，提高系统的安全性。

### 代理识别原理
系统通过比较采集的IP地址列表与实际请求IP地址来识别代理使用情况：

1. 前端采集用户所有可见的IP地址
2. 后端获取实际请求的客户端IP地址
3. 比较两个IP地址是否一致
4. 如果不一致，判断为使用代理

### 会话关联检测
系统还通过会话关联机制增强代理检测的准确性：

1. 为每次设备访问生成唯一的会话ID
2. 记录该会话下所有IP地址的访问情况
3. 分析同一会话中IP地址的变化模式
4. 根据IP地址出现频率判断是否为代理

```mermaid
flowchart TD
A[采集IP列表] --> B[获取实际请求IP]
B --> C{IP是否匹配?}
C --> |是| D[未使用代理]
C --> |否| E[标记为代理]
E --> F[记录会话信息]
F --> G[分析IP访问模式]
G --> H[确认代理状态]
```

**Section sources**
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L83-L112)
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go#L50-L55)

## 设备ID生成与隐私保护
设备ID生成与隐私保护机制确保了用户隐私的同时，又能有效实现设备级别的识别和控制。

### 设备ID生成策略
系统采用客户端生成设备ID的策略，具体实现方式如下：

1. 前端JavaScript代码生成唯一设备标识
2. 设备ID基于设备硬件特征、浏览器指纹等信息生成
3. 生成的设备ID在设备本地存储，确保持久性
4. 设备ID在不同会话间保持一致

### 隐私保护措施
为保护用户隐私，系统采取了多项安全措施：

- **数据加密传输**：所有设备信息通过AES-CBC加密后传输
- **数据完整性验证**：使用MD5签名验证数据完整性
- **最小化数据采集**：仅采集必要的设备识别信息
- **数据访问控制**：严格限制设备信息的访问权限

```mermaid
flowchart TD
A[设备信息采集] --> B[数据加密]
B --> C[签名生成]
C --> D[数据传输]
D --> E[后端接收]
E --> F[解密验证]
F --> G[存储处理]
```

**Section sources**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L35-L59)
- [restriction.go](file://internal/model/restriction.go#L11-L17)

## 最佳实践与应用场景
设备ID限制机制在多种业务场景中发挥着重要作用，以下是最佳实践和典型应用场景。

### 防止多开场景
通过设备ID限制，可以有效防止用户在同一设备上运行多个实例：

1. 配置`isRestrictDevice=true`
2. 系统检测到同一设备ID的多次访问
3. 对重复访问进行限制或警告
4. 维护系统资源的公平使用

### 设备级访问控制
实现基于设备级别的精细化访问控制：

- 为特定设备分配访问权限
- 限制高风险设备的访问
- 实现设备白名单/黑名单管理
- 监控异常设备的访问行为

### 安全审计与监控
利用设备ID记录进行安全审计：

- 追踪设备访问历史
- 分析异常访问模式
- 识别潜在的安全威胁
- 生成设备访问报告

## 与用户认证系统的集成
设备ID限制机制与用户认证系统紧密集成，共同构建多层次的安全防护体系。

### 集成架构
设备限制功能作为认证流程的补充验证层：

```mermaid
flowchart TD
A[用户登录] --> B[身份认证]
B --> C{认证成功?}
C --> |是| D[设备ID验证]
D --> E{设备是否受限?}
E --> |是| F[拒绝访问]
E --> |否| G[授予访问权限]
C --> |否| H[拒绝登录]
```

### 协同工作机制
设备限制与用户认证的协同工作流程：

1. 用户提交登录凭证
2. 系统验证用户名和密码
3. 认证成功后，采集设备信息
4. 验证设备ID是否被限制
5. 综合判断是否授予访问权限

**Section sources**
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go#L17-L69)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L35-L59)

## 总结
设备ID限制机制是kami_backend系统中重要的安全控制组件，通过采集、存储和匹配设备标识信息，实现了基于设备级别的精细化访问控制。该机制有效防止了多开、设备级滥用等安全问题，增强了系统的整体安全性。

核心优势包括：
- 灵活的限制规则配置
- 可靠的设备识别能力
- 强大的代理检测功能
- 完善的隐私保护措施
- 与用户认证系统的无缝集成

通过合理配置和使用设备ID限制机制，可以有效提升系统的安全性和稳定性，为用户提供更可靠的服务体验。