state.apply执行失败但无报错，主因是highstate缓存未刷新或pillar加载时机不当；需手动执行saltutil.refresh_pillar、验证pillar.items，并注意jinja变量存在性判断及include作用域隔离。
state.apply 执行失败但没报错？检查 highstate 缓存和 pillar 加载时机
SaltStack 的 state.apply 看似执行成功，实际没生效，大概率是 highstate 缓存没刷新，或 pillar 在 state 渲染前未加载。Salt 默认会缓存 pillar 数据（尤其在 master 配置了 pillar_cache: True），而 salt '*' state.apply 不强制刷新它。
- 执行前手动刷新 pillar：
salt '*' saltutil.refresh_pillar，再跑 state - 确认 minion 是否真正拉取到 pillar：
salt '*' pillar.items，对比你期望的 key 是否存在、类型是否正确（比如字符串被 YAML 解析成 bool） - 避免在
init.sls里直接引用{{ pillar['xxx'] }}前，先用{% if pillar.get('xxx') %}做存在性判断，否则渲染阶段就报Jinja variable 'pillar' has no attribute 'xxx' - 如果用了
top.sls的include:，注意被 include 的 sls 文件不会自动继承父级的context或defaults，变量作用域是隔离的
写自定义 module 时 ImportError 怎么定位？路径、依赖和 reload 三步查清
在 /srv/salt/_modules/ 下放了 myutils.py，执行 salt '*' myutils.do_something 却提示 ImportError: No module named xxx，问题通常不在代码本身，而在 Salt 的模块加载机制。
- 确保文件权限为 644，且属主是运行 salt-minion 的用户（常被忽略：minion 进程不是 root 时读不了 root 写的 _modules）
- 模块内 import 第三方库（如
requests）前，先在 minion 上用salt '*' cmd.run "python3 -c 'import requests'"验证是否全局可导入；不要假设 virtualenv 路径对 minion 有效 - 修改后必须执行
salt '*' saltutil.sync_modules，否则 minion 仍用旧字节码；若已加载过同名模块，还得加salt '*' sys.reload_modules - 函数名不能以下划线开头（如
_helper()），Salt 会跳过它们——这不是 bug，是设计行为
targeting 用正则匹配 minion ID 失败？别漏掉 -E 参数和 shell 元字符转义
想用 salt -E 'webd+' test.ping 匹配 web1、web12，结果返回空，常见原因是参数解析层级混乱或正则语法不兼容。
-
-E是 salt CLI 的参数，必须紧贴命令，不能写成salt --regex 'webd+' test.ping（这个 --regex 不存在） - bash 会提前处理
d，实际传给 Salt 的可能是d；改用salt -E 'web[0-9]+'或双反斜杠：salt -E 'web\d+' - 如果 minion ID 含点号（如
db.prod.example.com），正则中要写成db.prod..*，否则.被当通配符 - 更稳的方式是用 grains：
salt -G 'roles:web' test.ping，比正则 target 更可靠，也方便后续做条件 state
highstate 执行卡住不动？优先看 file_tree 和 gitfs 的同步阻塞
运行 salt '*' state.highstate 后长时间无响应，90% 情况不是网络或 CPU 问题，而是 Salt 的外部 fileserver（尤其是 gitfs 或 file_tree）在后台同步时锁住了整个渲染流程。
- 检查 master 日志：
tail -f /var/log/salt/master | grep -i 'gitfs|file_tree'，看是否有Updating gitfs remote长时间未结束 - 临时禁用 gitfs 排查：
sed -i '/^gitfs:/,/^$/d' /etc/salt/master，然后salt-master -t 3测试是否恢复 - 如果用了多个 gitfs remote，Salt 默认串行拉取；改成并行需显式配置
gitfs_update_interval: 60并设gitfs_remotes_update_method: parallel - file_tree backend 如果目录下有大量小文件（>10k），首次索引会明显拖慢 highstate 启动——建议用
file_list_cache_time缓存结果，或改用 roots + rsync 同步
复杂环境里，fileserver 的延迟不是“慢”，而是“不可见”；它不报错，也不进 state 日志，只让 highstate 停在第一步。盯日志比猜 timeout 更有效。
