164 lines
4.9 KiB
Markdown
164 lines
4.9 KiB
Markdown
# 设备优先前缀配置说明
|
||
|
||
## 功能概述
|
||
|
||
设备优先前缀配置允许管理员指定在空闲设备选择时的优先级规则，优先选择特定前缀的设备，实现更灵活的设备分配策略。
|
||
|
||
## 配置项
|
||
|
||
**配置键**: `device.priority_prefixes`
|
||
**配置类型**: STRING
|
||
**默认值**: 空字符串（全随机）
|
||
**格式**: 逗号分隔的前缀列表
|
||
|
||
## 使用方法
|
||
|
||
### 1. 配置优先前缀
|
||
|
||
通过系统配置接口设置 `device.priority_prefixes` 的值。
|
||
|
||
**示例配置值**:
|
||
```
|
||
xx,yy,zz
|
||
```
|
||
|
||
这表示：
|
||
- 第1优先级：`xx` 开头的设备
|
||
- 第2优先级：`yy` 开头的设备
|
||
- 第3优先级：`zz` 开头的设备
|
||
- 最低优先级：其他所有设备
|
||
|
||
### 2. 选择逻辑
|
||
|
||
设备分配时会按照以下逻辑进行：
|
||
|
||
1. **过滤占用设备**：排除被其他任务占用的设备
|
||
2. **按前缀分组**：根据配置的前缀将设备分成不同优先级组
|
||
3. **组内随机**：每个优先级组内的设备随机打乱
|
||
4. **顺序尝试**：按优先级从高到低依次尝试分配，直到成功
|
||
|
||
**特点**：
|
||
- ✅ 优先使用指定前缀的设备
|
||
- ✅ 同优先级内随机选择，避免总是选中同一台设备
|
||
- ✅ 实现负载均衡和优先级控制的平衡
|
||
- ✅ 支持冷却机制和并发安全
|
||
|
||
### 3. 示例场景
|
||
|
||
#### 场景1：无配置（默认行为）
|
||
```
|
||
device.priority_prefixes = ""
|
||
```
|
||
**效果**：所有设备完全随机选择，与原有逻辑一致
|
||
|
||
#### 场景2：优先使用xx设备
|
||
```
|
||
device.priority_prefixes = "xx"
|
||
```
|
||
**假设可用设备**：`xx1, xx2, yy1, yy2, zz1`
|
||
|
||
**选择顺序**：
|
||
1. 优先在 `xx1, xx2` 中随机选择
|
||
2. 如果 xx 设备都在冷却期或被占用，再从 `yy1, yy2, zz1` 中随机选择
|
||
|
||
#### 场景3：多级优先级
|
||
```
|
||
device.priority_prefixes = "xx,yy"
|
||
```
|
||
**假设可用设备**：`xx1, xx2, yy1, yy2, zz1, zz2`
|
||
|
||
**选择顺序**：
|
||
1. 第1优先级：在 `xx1, xx2` 中随机选择
|
||
2. 第2优先级：如果 xx 都不可用，在 `yy1, yy2` 中随机选择
|
||
3. 第3优先级：如果 xx、yy 都不可用，在 `zz1, zz2` 中随机选择
|
||
|
||
## API使用示例
|
||
|
||
### 查询当前配置
|
||
```bash
|
||
GET /api/admin/config/key/device.priority_prefixes
|
||
```
|
||
|
||
### 更新配置
|
||
```bash
|
||
PUT /api/admin/config
|
||
|
||
{
|
||
"configKey": "device.priority_prefixes",
|
||
"configValue": "xx,yy,zz",
|
||
"configType": "STRING",
|
||
"description": "设备选择优先前缀（逗号分隔）"
|
||
}
|
||
```
|
||
|
||
### 批量更新（推荐）
|
||
```bash
|
||
PUT /api/admin/config/batch
|
||
|
||
[
|
||
{
|
||
"configKey": "device.priority_prefixes",
|
||
"configValue": "xx,yy"
|
||
}
|
||
]
|
||
```
|
||
|
||
## 日志输出
|
||
|
||
启用该功能后，日志中会输出相关信息：
|
||
|
||
```
|
||
[INFO] 使用设备优先前缀配置：[xx, yy]
|
||
[DEBUG] 优先级0（前缀=xx）：2 台设备
|
||
[DEBUG] 优先级1（前缀=yy）：3 台设备
|
||
[DEBUG] 无优先级设备：5 台
|
||
[INFO] 设备列表已按优先级排序并随机化：[xx2, xx1, yy3, yy1, yy2, zz1, aa1, bb1, cc1, dd1]
|
||
[INFO] 设备分配成功：设备=xx2, 任务ID=123, 原因=首次选区
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **前缀匹配**：使用 `startsWith()` 进行前缀匹配，例如配置 `xx` 会匹配 `xx1`、`xx2`、`xxabc` 等
|
||
2. **大小写敏感**：前缀匹配区分大小写
|
||
3. **空格处理**：配置值会自动去除前后空格，`"xx, yy"` 会被处理为 `["xx", "yy"]`
|
||
4. **空配置**：如果配置为空或不存在，系统会退化到原有的完全随机选择逻辑
|
||
5. **优先级顺序**：前缀在配置字符串中的顺序决定优先级，越靠前优先级越高
|
||
6. **实时生效**：配置修改后立即生效，无需重启服务
|
||
|
||
## 数据库迁移
|
||
|
||
执行以下 SQL 脚本添加配置项：
|
||
|
||
```sql
|
||
-- 位置: db_migration_device_priority_prefixes.sql
|
||
INSERT INTO system_config (config_key, config_value, config_type, description, is_system, created_at, updated_at)
|
||
VALUES (
|
||
'device.priority_prefixes',
|
||
'',
|
||
'STRING',
|
||
'设备选择优先前缀（逗号分隔），例如：xx,yy,zz。优先选择匹配前缀的设备，同优先级内随机。为空则全随机',
|
||
1,
|
||
NOW(3),
|
||
NOW(3)
|
||
)
|
||
ON DUPLICATE KEY UPDATE
|
||
config_type = 'STRING',
|
||
description = '设备选择优先前缀（逗号分隔），例如：xx,yy,zz。优先选择匹配前缀的设备，同优先级内随机。为空则全随机',
|
||
updated_at = NOW(3);
|
||
```
|
||
|
||
## 相关代码
|
||
|
||
- **配置服务**: `SystemConfigService.getDevicePriorityPrefixes()`
|
||
- **分配服务**: `DeviceAllocationService.allocateDevice()`
|
||
- **排序逻辑**: `DeviceAllocationService.sortByPrefixPriority()`
|
||
|
||
## 测试建议
|
||
|
||
1. **无配置测试**：不配置前缀，验证随机选择是否正常
|
||
2. **单前缀测试**：配置单个前缀，验证是否优先选择该前缀设备
|
||
3. **多前缀测试**：配置多个前缀，验证优先级顺序是否正确
|
||
4. **负载均衡测试**：多次分配，验证同优先级内是否随机分布
|
||
5. **冷却期测试**：验证高优先级设备在冷却期时，能否正确选择低优先级设备
|
||
|