GitLab Stack Validator

GitLab Stack 验证器

此技能用于验证 GitLab Stack 项目，确保其遵循正确的架构模式并已准备好部署。重点是检测和报告问题，并与配套技能（stack-creator、secrets-manager）协同进行修复。

何时使用此技能

用户提出以下请求时，请启用此技能：

• 验证 GitLab Stack 项目
• 在部署前检查 Stack 配置
• 验证 Stack 架构和结构
• 审核 Stack 是否符合最佳实践
• 确保 Stack 遵循正确的模式
• 执行部署前验证检查
• 检查 Stack 的健康状况或就绪状态

核心验证原则

此技能验证遵循以下架构原则的 Stack：

1. 配置管理：所有配置均通过 docker-compose.yml 和 ./config 目录管理
2. 密钥管理：密钥存储在 ./secrets 中，并通过 Docker secrets 引用
3. 环境变量：使用 .env 文件，并提供与之匹配的 .env.example 模板
4. 尽量减少自定义脚本：仅当容器不支持原生密钥时，才使用 docker-entrypoint.sh
5. 正确的所有权：不得有归 root 所有的文件（所有文件均由 Docker 用户所有）
6. 临时文件：将临时文件存放在 _temporary 目录中，使用后清理
7. Docker 最佳实践：借助 docker-validation 技能执行 Docker 专项检查

验证工作流

用户请求验证 Stack 时，请遵循以下完整工作流：

阶段 1：预检

步骤 1：验证 Stack 项目

1. 检查当前目录是否看起来是一个 Stack 项目
2. 查找关键标志：
   • 是否存在 docker-compose.yml
   • 是否存在 ./config、./secrets 或 ./_temporary 目录
   • 是否存在 .env 文件
3. 如果不是 Stack 项目，请报告检查结果，并询问用户是否要初始化一个项目

步骤 2：收集上下文

1. 如有需要，询问用户验证范围：
   • 完整验证还是针对性检查？
   • 严格模式还是宽松模式？
   • 偏好的输出格式（文本报告还是 JSON）？
2. 检查是否存在用于自定义规则的 .stack-validator.yml
3. 记录用于报告的工作目录

阶段 2：目录结构验证

步骤 1：必需目录

1. 检查是否存在以下必需目录：
   • ./config - 配置文件目录
   • ./secrets - 密钥存储目录
   • ./_temporary - 临时文件目录
2. 对于每个缺失的目录，记录：
   • 目录名称
   • 用途及其必要原因
   • 对 Stack 功能的影响

步骤 2：目录权限

1. 检查 ./secrets 是否具有受限权限（700 或 600）
2. 验证其他目录是否具有适当的权限
3. 报告任何存在安全影响的权限问题

步骤 3：目录所有权

1. 扫描项目中的所有目录，检查所有权
2. 标记任何归 root 所有的目录：
   • 目录路径
   • 当前所有者
   • 预期所有者（当前用户或 Docker 用户）
3. 标记所有权异常的文件

步骤 4：.gitignore 验证

1. 检查是否存在 .gitignore
2. 验证其中是否排除了：
   • ./secrets 或 ./secrets/*
   • ./_temporary 或 ./_temporary/*
   • .env（不应提交到 git）
3. 报告缺少的排除项及其安全影响

阶段 3：环境变量验证

步骤 1：.env 文件验证

1. 检查 .env 文件是否存在
2. 解析 .env 文件，检查：
   • 语法错误
   • 重复定义的变量
   • 可能为必填项的空值
3. 记录发现的所有环境变量名称

步骤 2：.env.example 验证

1. 检查 .env.example 是否存在
2. 如果缺失，这是一个严重问题——记录其必要性
3. 解析 .env.example，提取变量名称

步骤 3：.env 同步检查

1. 比较 .env 与 .env.example 中的变量：
   • 存在于 .env 但不存在于 .env.example 的变量
   • 存在于 .env.example 但不存在于 .env 的变量
2. 这是一个关键验证点——两者必须匹配
3. 报告所有不匹配项，并列出具体变量名称

步骤 4：环境变量安全

1. 扫描 .env 中的潜在密钥：
   • 名称包含 password、secret、key、token、api 的变量
   • 看起来经过 Base64 编码的值
   • 较长的随机字符串
2. 如果在 .env 中检测到密钥，将其标记为安全问题
3. 建议改用 ./secrets 和 Docker secrets

阶段 4：Docker 配置验证

步骤 1：调用 docker-validation 技能

1. 使用 docker-validation 技能验证：
   • docker-compose.yml 语法和最佳实践
   • Dockerfile（如果存在）
   • 多阶段构建
   • 安全配置
2. 汇总 docker-validation 的所有发现
3. 将其整合到整体技术栈验证报告中

步骤 2：针对技术栈的 Docker 检查

1. 检查 docker-compose.yml 中的技术栈模式：
   • 在顶层 secrets: 部分定义密钥
   • 服务通过 secrets: 键引用密钥（而非环境变量）
   • 卷挂载遵循相应模式（./config、./secrets、./_temporary）
   • 如果包含多个服务，则正确定义网络
   • 正确使用 depends_on 设置服务依赖关系

步骤 3：版本检查

1. 确保 docker-compose.yml 顶部没有 version 字段
2. 这符合现代 Docker Compose 规范
3. 如果存在 version 字段，标记为需要移除

阶段 5：密钥管理验证

步骤 1：密钥目录检查

1. 验证 ./secrets 目录是否存在
2. 检查权限是否严格限制（700）
3. 验证该目录已从 Git 中排除

步骤 2：Docker secrets 验证

1. 解析 docker-compose.yml 中的 secrets 定义
2. 对每项密钥定义：
   • 验证 ./secrets 中是否存在相应的密钥文件
   • 检查文件权限（600 或 400）
   • 验证该文件未被 Git 跟踪
3. 报告缺失的密钥文件

步骤 3：密钥引用验证

1. 检查每个服务的 secrets: 部分
2. 验证所引用的密钥已在顶层 secrets 中定义
3. 标记所有未定义的密钥引用

步骤 4：环境变量与密钥

1. 扫描服务环境变量，查找潜在密钥
2. 查找以下模式：
   • *_PASSWORD
   • *_SECRET
   • *_KEY
   • *_TOKEN
   • API_*
3. 如果环境变量中包含敏感数据，建议改用 secrets

步骤 5：密钥暴露检查

1. 检查以下位置是否包含密钥：
   • docker-compose.yml（硬编码值）
   • .env 文件（应改放在 ./secrets 中）
   • ./config 中的配置文件
   • 任何 Shell 脚本
2. 将发现的任何暴露密钥报告为严重安全问题

阶段 6：配置文件验证

步骤 1：配置目录结构

1. 列出 ./config 目录中的所有文件
2. 按服务整理（如适用）
3. 检查组织方式是否合理

步骤 2：配置文件验证

1. 验证常见配置文件类型的语法：
   • YAML 文件（.yml、.yaml）
   • JSON 文件（.json）
   • INI 文件（.ini、.conf）
   • TOML 文件（.toml）
2. 报告所有语法错误

步骤 3：配置与密钥分离

1. 扫描配置文件，查找潜在密钥
2. 查找硬编码的密码、令牌和密钥
3. 将应改放在 ./secrets 中的密钥标记出来

步骤 4：配置文件所有权

1. 检查所有配置文件的所有权
2. 标记所有归 root 所有的配置文件
3. 报告预期的所有权（当前用户）

阶段 7：脚本验证

步骤 1：检测 docker-entrypoint.sh

1. 搜索 docker-entrypoint.sh 文件
2. 对每个找到的文件：
   • 记录位置
   • 检查是否确实有必要
3. 验证仅在容器不支持原生机密时才使用它

步骤 2：脚本权限

1. 检查 docker-entrypoint.sh 是否可执行（chmod +x）
2. 验证所有权（不应属于 root）
3. 报告权限问题

步骤 3：脚本内容验证

1. 扫描脚本，检查以下内容：
   • 硬编码的机密（严重问题）
   • 是否正确处理来自 /run/secrets/ 的机密
   • 错误处理
   • 语法错误（如果是 bash/sh）
2. 报告发现的任何问题

步骤 4：必要性检查

1. 检查是否确实需要 docker-entrypoint.sh
2. 检查服务是否支持原生 Docker 机密
3. 如无必要，建议移除

阶段 8：临时目录验证

步骤 1：目录检查

1. 验证 ./_temporary 是否存在
2. 检查它是否已列入 .gitignore
3. 验证权限

步骤 2：内容检查

1. 列出 ./_temporary 的内容
2. 检查以下内容：
   • 应清理但遗留的文件
   • 占用空间的大文件
   • 旧文件（超过 7 天）
3. 如果目录非空，报告详细信息

步骤 3：使用情况验证

1. 检查 ./_temporary 是否已在 docker-compose.yml 中正确挂载
2. 验证服务是否使用它存放临时文件
3. 如果未使用，则标记出来

阶段 9：文件所有权审计

步骤 1：全面扫描文件所有权

1. 使用 find . -type f -user root 2>/dev/null 查找属于 root 的文件
2. 排除预期目录（.git、node_modules、vendor）
3. 列出找到的所有 root 所有文件

步骤 2：问题分类

1. 按目录分组：
   • 属于 root 的 ./config 文件
   • 属于 root 的 ./secrets 文件
   • 属于 root 的应用程序文件
2. 报告具体路径

步骤 3：影响评估

1. 对于每个属于 root 的文件：
   • 说明这为什么会造成问题
   • 说明对堆栈操作的影响
   • 说明可能出现的错误

阶段 10：生成报告

步骤 1：汇总所有发现

1. 按类别整理发现：
   • 目录结构
   • 环境变量（.env 同步）
   • Docker 配置
   • 机密管理
   • 配置文件
   • 脚本（docker-entrypoint.sh）
   • 临时目录
   • 文件所有权
2. 指定严重级别：
   • ❌ 严重：安全问题、缺少必需组件、.env 不匹配
   • ⚠️ 警告：违反最佳实践、潜在问题
   • ✅ 通过：未发现问题

步骤 2：生成验证报告

按照以下结构创建全面的报告：

🔍 GitLab Stack Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stack: [directory name]
Date: [timestamp]
Mode: [strict/permissive]

📊 SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Passed: [count]
⚠️  Warnings: [count]
❌ Critical: [count]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 DETAILED FINDINGS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[For each validation category]

[Category Icon] [Category Name]: [STATUS]
[If issues found:]
   ❌ [Issue description]
      Location: [file/directory path]
      Impact: [what this affects]
      Details: [specific information]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 OVERALL STATUS: [PASSED/FAILED/WARNINGS]

[If failures or warnings:]
🔧 RECOMMENDED ACTIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Prioritized list of actions needed]
1. [Most critical action]
2. [Next action]
...

💡 NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Use stack-creator skill to fix structural issues
- Use secrets-manager skill to properly configure secrets
- Re-run validation after fixes

步骤 3：提供可执行的指导

1. 对于每个问题，提供：
   • 清晰描述问题
   • 说明问题的重要性
   • 说明可以帮助修复问题的配套技能
   • 一般性指导（但不提供实际修复命令）
2. 按严重级别排列问题优先级
3. 将相关问题归为一组

步骤 4：导出选项

1. 如果用户要求 JSON 输出，则导出为：

   {
     "stack": "directory-name",
     "timestamp": "ISO-8601",
     "summary": {
       "passed": 5,
       "warnings": 2,
       "critical": 1,
       "status": "failed"
     },
     "findings": [
       {
         "category": "environment-variables",
         "status": "critical",
         "issues": [...]
       }
     ]
   }
   

验证类别参考

1. 目录结构

• 必需目录存在
• 权限正确
• .gitignore 覆盖范围
• 所有权正确

2. 环境变量

• .env 文件存在且有效
• .env.example 存在
• 严重：.env 和 .env.example 保持同步
• .env 中没有机密

3. Docker 配置

• docker-compose.yml 有效（通过 docker-validation 技能验证）
• 没有 version 字段
• 机密定义正确
• 卷符合模式要求
• 服务依赖关系正确

4. 机密管理

• ./secrets 目录安全
• 所有引用的机密均存在
• 权限正确
• 没有暴露的机密
• 环境变量不包含机密

5. 配置文件

• 组织结构正确
• 语法有效
• 没有嵌入的机密
• 所有权正确

6. 脚本

• 仅在必要时使用 docker-entrypoint.sh
• 具有可执行权限
• 没有硬编码的机密
• 机密处理正确

7. 临时目录

• 已存在且位于 .gitignore 中
• 为空或仅包含预期的临时文件
• 在 compose 文件中得到正确使用

8. 文件所有权

• 没有由 root 拥有的文件
• 所有权一致
• 用户/组设置正确

与配套技能集成

stack-creator

• 推荐用于：创建缺失的目录、初始化结构
• 负责：设置新堆栈、修复结构问题

secrets-manager

• 推荐用于：密钥配置、密钥文件管理
• 负责：创建/更新密钥、正确设置密钥

docker-validation

• 在验证期间直接使用，执行 Docker 专项检查
• 提供：Docker Compose 和 Dockerfile 验证
• 集成到堆栈验证报告中

验证模式

标准模式（默认）

• 将所有问题报告为警告或错误
• 提供全面的检查结果
• 建议改进措施

严格模式

• 遇到警告即失败
• 要求遵循所有最佳实践
• 零容忍偏差

宽松模式

• 仅在出现严重问题时失败
• 允许警告
• 对最佳实践的要求更宽松

配置支持

如果项目根目录中存在 .stack-validator.yml，请遵循以下设置：

# Validation mode
strict_mode: false

# Whether warnings should fail validation
fail_on_warnings: false

# Paths to exclude from validation
exclude_paths:
  - ./vendor
  - ./node_modules
  - ./_temporary/cache

# Custom validation scripts to run
custom_checks:
  - ./scripts/custom-validation.sh

# Specific checks to skip
skip_checks:
  - temporary-directory-empty

沟通风格

报告验证结果时：

1. 清晰直接：直截了当地说明问题，不要含糊其辞
2. 具体明确：提供准确的文件路径、行号和变量名
3. 可执行：说明需要做什么（但不要代为执行）
4. 乐于助人：指出可以修复问题的配套技能
5. 条理清晰：将相关问题分组，并按严重程度排序
6. 注重说明：解释问题所在
7. 简洁明了：避免过多细节，但要全面

关键验证项

以下是生产环境堆栈必须通过的条件：

1. ✅ .env 和 .env.example 完全同步
2. ✅ docker-compose.yml 环境变量中没有密钥
3. ✅ ./secrets 目录存在且权限受限
4. ✅ 所有引用的密钥均存在
5. ✅ ./secrets 和 ./_temporary 位于 .gitignore 中
6. ✅ 没有由 root 拥有的文件
7. ✅ docker-compose.yml 通过 docker-validation 验证
8. ✅ git 中没有泄露密钥
9. ✅ .env 文件未被 git 跟踪

重要说明

• 只读：此技能绝不会修改文件，仅进行验证
• 专注检测：报告问题，不要修复问题
• 全面检查：系统地检查所有方面
• 快速：数秒内完成验证
• 集成：使用 docker-validation 技能执行 Docker 检查
• 了解配套技能：引导用户使用适当的技能修复问题

验证流程示例

User: "Validate my stack"

1. Check if docker-compose.yml exists ✅
2. Verify directory structure
   - ./config ✅
   - ./secrets ✅
   - ./_temporary ⚠️ (not in .gitignore)
3. Validate .env configuration
   - .env exists ✅
   - .env.example exists ❌ CRITICAL
4. Run docker-validation skill
   - docker-compose.yml syntax ✅
   - Secrets configuration ⚠️ (using environment vars)
5. Check secrets management
   - ./secrets permissions ✅
   - Secret files exist ✅
6. Scan for ownership issues
   - Found 3 root-owned files in ./config ❌
7. Generate report with findings
8. Suggest: Use stack-creator to add .env.example and fix .gitignore

---

此技能通过全面验证，确保堆栈的质量、安全性和部署就绪状态。