SaltStack磁盘用量Beacon触发后出现Unicode解码异常求助

安全阿岳

2026-6-19

问题描述

测试SaltStack的diskusage Beacon时，触发后出现全局未处理异常：An un-handled exception was caught by Salt's global exception handler，具体为UnicodeDecodeError：无法解码字节0xf0。相关环境与配置信息如下：

Salt版本：salt-master、salt-minion均为3006.9（Sulfur分支）
Beacon配置文件/etc/salt/minion.d/disk.conf内容：

beacons:
  diskusage:
    - /: 5%
    - interval: 60

执行sudo salt-call state.event pretty=True时，能正常接收Beacon触发的返回数据：

__beacons_return    {
    "_stamp": "2024-08-19T15:45:14.797958",
    "beacons": [
        {
            "beacon_name": "diskusage",
            "data": {
                "diskusage": 77.6,
                "id": "hostname",
                "mount": "/"
            },
            "tag": "salt/beacon/hostname/diskusage/"
        }
    ]
}

但随后会抛出完整的Unicode解码异常栈信息，更换不同minion测试问题依旧。

解决建议

排查系统中的非ASCII路径/文件名
字节0xf0属于UTF-8的4字节字符（常见于emoji或特殊符号），diskusage Beacon扫描磁盘内容时可能遇到了无法解码的文件名或路径。用以下命令排查系统内的非ASCII路径：
```
find / -type f -name "*[!a-zA-Z0-9/._-]*" 2>/dev/null
```
找到后可选择重命名相关文件/路径，或修改diskusage Beacon配置，排除包含特殊字符的目录。
强制Salt使用UTF-8编码
在minion配置文件（如/etc/salt/minion或新建/etc/salt/minion.d/encoding.conf）中添加以下配置：
```
output_encoding: utf-8
error_encoding: utf-8
```
重启salt-minion服务后重新测试：
```
sudo systemctl restart salt-minion
```
升级到SaltStack最新补丁版本
3006.9版本可能存在已知的Unicode解码bug，建议升级到Sulfur分支的最新补丁版本（如3006.10及以上），升级后验证问题是否解决：
```
# Debian/Ubuntu系统示例
sudo apt update && sudo apt install salt-minion=3006.10-1
# RHEL/CentOS系统示例
sudo yum update salt-minion
```

自定义diskusage Beacon模块
若上述方法无效，可基于官方diskusage模块修改，添加异常捕获逻辑跳过无法解码的路径。创建自定义模块文件/srv/salt/_beacons/custom_diskusage.py：

import salt.utils.disk
import logging

log = logging.getLogger(__name__)

def validate(config):
    return salt.beacons.diskusage.validate(config)

def beacon(config):
    ret = []
    try:
        data = salt.utils.disk.diskusage()
        for mount, usage in data.items():
            try:
                mount_str = str(mount)
                for item in config:
                    if isinstance(item, dict) and mount_str in item:
                        threshold = item[mount_str]
                        if usage >= float(threshold.strip('%')):
                            ret.append({
                                'tag': f'salt/beacon/{__opts__["id"]}/custom_diskusage/',
                                'data': {
                                    'mount': mount_str,
                                    'diskusage': usage,
                                    'id': __opts__['id']
                                }
                            })
            except UnicodeDecodeError as e:
                log.warning(f"跳过无法解码的挂载路径: {mount}, 错误信息: {e}")
                continue
    except Exception as e:
        log.error(f"自定义diskusage Beacon执行错误: {e}")
    return ret

然后修改minion配置使用自定义Beacon：

beacons:
  custom_diskusage:
    - /: 5%
    - interval: 60

内容的提问来源于stack exchange，提问作者Noelle Wiley