用 salt-call --local 可安全本地调试：先 test.ping 验证 minion，再 state.show_sls 查渲染结果，最后 test=true 模拟执行；注意 file_roots、saltenv 配置对齐及 yaml 格式规范。
怎么用 salt-call 测试单机配置是否生效
本地调试比直接跑 salt '*' state.apply 安全得多，尤其改系统服务或用户权限时。salt-call 默认走本地模式，不依赖 master，适合验证 sls 文件语法、jinja 渲染结果和执行逻辑。
- 先确认 minion 配置正常：
salt-call --local test.ping，返回True才继续 - 渲染后看实际内容：
salt-call --local state.show_sls nginx，检查端口、用户、路径有没有被变量意外覆盖 - 真正执行前加
--dry-run：salt-call --local state.apply nginx test=True，注意这里test=True是参数，不是 flag - 常见坑：
salt-call默认读/etc/salt/minion，但如果你用非 root 用户运行，可能加载不到自定义file_roots，得加--config-dir /etc/salt
state.apply 报错 “No matching sls found” 怎么定位
不是文件没放对位置，就是环境没对上。Salt 的 file_roots 和 saltenv 是两层过滤，缺一不可。
- 查当前生效的 roots：
salt '*' cp.list_master saltenv=base，看输出里有没有你的 sls 文件名（不含 .sls 后缀） - 确认 top.sls 里写的环境名和实际调用一致，比如
salt '*' state.apply web saltenv=prod，那 top.sls 里必须有prod:段落 - sls 文件路径要和
file_roots配置对齐，例如file_roots: {base: [/srv/salt]}，那nginx/init.sls就得放在/srv/salt/nginx/init.sls - 常见错误：把
top.sls放在/srv/salt/top.sls，但没在master配置里声明它属于哪个 saltenv，导致完全不加载
批量推送大文件（如 JDK 包）卡住或失败
默认的 cp.get_file 走的是 master 内存中转，几百 MB 的包容易触发超时或 OOM。别硬扛，换传输方式。
- 用
cp.push让 minion 主动上传到 master（适合小文件校验），但批量下发必须反着来 —— 改用archive.extracted直接从 HTTP/FTP 下载 - 示例：把 jdk-17.tgz 放到内网 Nginx 下，sls 里写
jdk_install: archive.extracted: - name: /opt/java - source: http://192.168.1.100/jdk-17.tgz - 避免用
file.managed+source: salt://...推大文件，master 日志会刷满File size exceeds maximum allowed - 如果非要用 salt://，务必在 master 配置里调大
max_event_size和timeout，但不如换方案来得稳
minion 启动失败，日志只显示 “Failed to load configuration”
大概率是 /etc/salt/minion 里 YAML 格式错了，比如多了一个空格、用了 tab、注释后多了字符。Salt 不报具体哪行错，只能靠排除。
- 用
python3 -c "import yaml; print(yaml.load(open('/etc/salt/minion'), Loader=yaml.FullLoader))"直接解析，Python 报错行就是问题所在 - 检查缩进：YAML 只认空格，tab 会导致整个文件失效；
master:和下面的值之间至少一个空格 - 特殊字符没引起来：比如
master: salt.example.com:4506没问题，但id: web-01.prod建议加引号，避免点号被误解析 - 最容易被忽略的是文件编码 —— Windows 下编辑保存的 UTF-8 with BOM 会让 salt 解析失败，用
file /etc/salt/minion确认是UTF-8 Unicode (with BOM)就重存为无 BOM
配置管理真正的难点不在写多少 state，而在每次变更前想清楚：这个操作在 1 台机器上能不能闭环验证？它的失败会不会阻断后续所有机器？很多线上事故，都是跳过了 salt-call --local 这一步。
