fluentbit-validator

Fluent Bit 验证器

使用此技能对 Fluent Bit 经典模式配置执行确定性、可重复的验证。

触发短语

当提示类似以下内容时，使用此技能：

• “部署前验证此 fluent-bit.conf”
• “检查我的 Fluent Bit 配置并报告问题”
• “检查 Fluent Bit 中的标签路由和输出匹配”
• “对 Fluent Bit 配置运行安全检查”
• “试运行 Fluent Bit 配置并告诉我哪些检查失败”

执行模型

按顺序运行各个步骤。不要跳过阶段 0。

阶段 0：预检（必需）

从技能目录运行：

cd devops-skills-plugin/skills/fluentbit-validator

检查必需和可选二进制文件：

command -v python3 >/dev/null 2>&1 && echo "python3: available" || echo "python3: missing"
command -v fluent-bit >/dev/null 2>&1 && echo "fluent-bit: available" || echo "fluent-bit: missing (dry-run will be skipped)"

预检流程：

• 如果缺少 python3：停止基于脚本的验证，报告阻碍，并仅切换到手动配置审查。
• 如果缺少 fluent-bit：继续静态检查，跳过试运行，并记录一条说明跳过原因和后续步骤的 Recommendation。

阶段 1：静态验证（必需）

默认命令：

python3 scripts/validate_config.py --file <config-file> --check all

仅在用户请求时使用针对性检查：

python3 scripts/validate_config.py --file <config-file> --check structure
python3 scripts/validate_config.py --file <config-file> --check sections
python3 scripts/validate_config.py --file <config-file> --check tags
python3 scripts/validate_config.py --file <config-file> --check security
python3 scripts/validate_config.py --file <config-file> --check performance
python3 scripts/validate_config.py --file <config-file> --check best-practices
python3 scripts/validate_config.py --file <config-file> --check dry-run

严格 CI 门禁（可选）：

python3 scripts/validate_config.py --file <config-file> --check all --fail-on-warning

阶段 2：试运行处理（有条件）

试运行命令：

fluent-bit -c <config-file> --dry-run

跳过流程：

• 如果无法使用 fluent-bit，默认不要因此判定静态验证失败。
• 明确报告一条发现：
  • Recommendation: Dry-run skipped because fluent-bit binary is not available in PATH; run dry-run in CI or a Fluent Bit runtime image.
• 如果用户明确要求将试运行作为发布门禁，运行：

python3 scripts/validate_config.py --file <config-file> --check dry-run --require-dry-run

• 在发布门禁模式下，缺少 fluent-bit 必须报告为 Error。

阶段 3：参考资料查询（可选）

仅当本地检查后插件或参数的行为仍不明确时使用。

查询顺序：

1. Context7 Fluent Bit 文档。
2. docs.fluentbit.io 上的官方文档。
3. 范围仅限官方来源或插件来源的更广泛网络搜索。

仅收集：

• 必需字段，
• 允许的值和默认值，
• 与用户配置相关的版本注意事项。

阶段 4：报告和修复（必需）

严格使用以下严重性标签：

• Error
• Warning
• Recommendation

不要引入其他标签（如 Info、Best Practice、Critical 等）。

报告格式：

Validation Report: <config-file>

Error:
- <blocking issue>

Warning:
- <non-blocking risk>

Recommendation:
- <improvement or skipped-step guidance>

修复流程：

1. 在可能的情况下，提供包含文件和行号上下文的问题。
2. 修改用户文件前先征求批准。
3. 应用已批准的更改。
4. 重新运行相同的验证命令。
5. 返回差异：更改内容、剩余问题和最终状态。

无问题时的快速处理：

• 如果没有发现问题，简短报告通过情况，并说明试运行已执行还是已跳过。

回退矩阵

约束	处理方式
缺少 python3	停止脚本验证器，将阻碍报告为 Error，并仅提供手动审查结果。
缺少 fluent-bit	继续静态检查，跳过试运行，并发出一条包含后续步骤的 Recommendation。
无法访问网络或文档	继续本地验证，将未知的插件详情报告为 Warning，并明确注明“doc lookup deferred”。
用户要求仅提供报告	不要编辑文件；返回问题和建议重新运行的命令。

规范流程

完整验证流程

bash scripts/validate.sh --precheck
python3 scripts/validate_config.py --file tests/valid-basic.conf --check all

受限环境流程（无法使用 fluent-bit）

bash scripts/validate.sh --precheck
python3 scripts/validate_config.py --file tests/invalid-security-issues.conf --check all --json

预期结果：

• 仍会生成静态检查结果。
• 跳过试运行，并在 Recommendation 下报告。

完成标准

只有满足以下所有条件，工作才算完成：

• 已执行预检，并明确说明二进制文件是否可用。
• 验证命令和范围清晰且可复现。
• 所有问题仅使用 Error、Warning、Recommendation 标签。
• 明确说明试运行路径：已执行，或因何原因跳过。
• 输出中已记录工具或运行时受限时的回退处理方式。
• 如果已应用修复，则已重新运行验证并报告修复后的状态。

本地资源

• scripts/validate_config.py：主验证器。
• scripts/validate.sh：包装脚本和环境预检辅助工具。
• tests/*.conf：有效和无效配置示例。
• tests/test_validate_config.py：解析器和严重性行为的回归测试。