create-dwy 0.5.0 → 0.6.0

package/templates/claude-global/skills/dwy-docker/scripts/query_dockerhub.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+查询 DockerHub 上某镜像的版本列表，自动剔除 latest / rc / beta / alpha / preview / nightly
+等不稳定标签和浮动 tag，并推荐使用「最新稳定 minor 的上一个 minor」（N-1）。
+
+用法：
+    python3 query_dockerhub.py <image> [--namespace library] [--top 20]
+
+示例：
+    python3 query_dockerhub.py nginx
+    python3 query_dockerhub.py postgres
+    python3 query_dockerhub.py mycompany/api --namespace mycompany
+"""
+
+import argparse
+import json
+import re
+import sys
+import urllib.request
+from collections import defaultdict
+from datetime import datetime
+from urllib.error import HTTPError, URLError
+
+DOCKERHUB_API = "https://hub.docker.com/v2/repositories/{namespace}/{image}/tags"
+
+UNSTABLE_KEYWORDS = (
+    "rc", "beta", "alpha", "preview", "nightly", "dev", "snapshot",
+    "experimental", "edge", "canary", "next", "unstable",
+)
+
+FLOATING_TAGS = {
+    "latest", "stable", "mainline", "current", "release",
+    "lts", "rolling", "main", "master", "head",
+}
+
+SEMVER_RE = re.compile(r"^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:[.\-+](.+))?$")
+
+
+def fetch_tags(namespace: str, image: str, page_size: int = 100, max_pages: int = 5):
+    """从 DockerHub API 拉取 tags，返回原始列表。"""
+    url = DOCKERHUB_API.format(namespace=namespace, image=image) + f"?page_size={page_size}"
+    tags = []
+    page = 1
+    while url and page <= max_pages:
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "dwy-docker-image-skill/1.0"})
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except HTTPError as e:
+            if e.code == 404:
+                print(f"错误：DockerHub 上找不到 {namespace}/{image}", file=sys.stderr)
+                sys.exit(2)
+            raise
+        except URLError as e:
+            print(f"错误：访问 DockerHub 失败：{e}", file=sys.stderr)
+            sys.exit(3)
+
+        tags.extend(data.get("results", []))
+        url = data.get("next")
+        page += 1
+    return tags
+
+
+def parse_version(tag: str):
+    """
+    解析 tag 中的版本号（major, minor, patch, suffix）。
+
+    返回 None 表示这个 tag 不能解析为版本号（比如 'alpine'、'bookworm'）。
+    """
+    cleaned = tag.lstrip("v")
+    m = SEMVER_RE.match(cleaned)
+    if not m:
+        return None
+    major = int(m.group(1))
+    minor = int(m.group(2)) if m.group(2) else 0
+    patch = int(m.group(3)) if m.group(3) else 0
+    suffix = m.group(4) or ""
+    return (major, minor, patch, suffix)
+
+
+def is_stable(tag_name: str) -> bool:
+    """判断 tag 是否为稳定版本。"""
+    name = tag_name.lower()
+    if name in FLOATING_TAGS:
+        return False
+    for kw in UNSTABLE_KEYWORDS:
+        if re.search(rf"[\-._]{kw}\b", name) or name.endswith(kw) or name.startswith(kw + "-"):
+            return False
+    return True
+
+
+def has_only_version(tag_name: str) -> bool:
+    """
+    tag 是否仅包含版本号且至少包含 major.minor 两段。
+
+    单段数字 tag（如 '1'、'17'）虽然看起来固定，实际是浮动 tag（指向该 major
+    系列最新 patch），不能用作固定版本，必须排除。
+    """
+    return bool(re.match(r"^v?\d+\.\d+(\.\d+)?$", tag_name))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="查询 DockerHub 镜像版本，推荐 N-1 minor")
+    parser.add_argument("image", help="镜像名，如 nginx、postgres")
+    parser.add_argument("--namespace", default="library", help="DockerHub 命名空间，默认 library")
+    parser.add_argument("--top", type=int, default=20, help="显示最近 N 个 tag，默认 20")
+    args = parser.parse_args()
+
+    print(f"查询 DockerHub: {args.namespace}/{args.image} ...\n", file=sys.stderr)
+    tags = fetch_tags(args.namespace, args.image)
+    if not tags:
+        print(f"未找到 {args.namespace}/{args.image} 的任何 tag", file=sys.stderr)
+        sys.exit(1)
+
+    # 过滤：稳定 + 纯版本号
+    pure_version_tags = []
+    for t in tags:
+        name = t.get("name", "")
+        if not is_stable(name):
+            continue
+        if not has_only_version(name):
+            continue
+        ver = parse_version(name)
+        if ver is None:
+            continue
+        pure_version_tags.append({
+            "name": name,
+            "version": ver,
+            "last_updated": t.get("last_updated", ""),
+        })
+
+    if not pure_version_tags:
+        print("未找到符合规范的稳定版本 tag。请手动确认。", file=sys.stderr)
+        sys.exit(1)
+
+    # 按 (major, minor) 分组，每组取最大 patch
+    minor_groups = defaultdict(list)
+    for item in pure_version_tags:
+        major, minor, _patch, _suffix = item["version"]
+        minor_groups[(major, minor)].append(item)
+
+    # 每组按版本号排序，取最大 patch 作为该 minor 的代表
+    minor_latest = {}
+    for key, items in minor_groups.items():
+        items.sort(key=lambda x: x["version"], reverse=True)
+        minor_latest[key] = items[0]
+
+    # 按 (major, minor) 倒序排列
+    sorted_minors = sorted(minor_latest.keys(), reverse=True)
+
+    if not sorted_minors:
+        print("无法识别任何 (major, minor) 系列", file=sys.stderr)
+        sys.exit(1)
+
+    latest_minor = sorted_minors[0]
+    latest_item = minor_latest[latest_minor]
+
+    # N-1：跳过仅有少量 patch 的快速被弃用版本，找真正的"上一个 minor"
+    n_minus_1_item = None
+    if len(sorted_minors) >= 2:
+        n_minus_1_minor = sorted_minors[1]
+        n_minus_1_item = minor_latest[n_minus_1_minor]
+
+    # 输出
+    print("=" * 60)
+    print(f"镜像: {args.namespace}/{args.image}")
+    print("=" * 60)
+    major, minor, patch, _ = latest_item["version"]
+    print(f"最新稳定 minor: {major}.{minor}")
+    print(f"  最新 patch: {latest_item['name']}  ({format_date(latest_item['last_updated'])})")
+    print()
+
+    if n_minus_1_item:
+        n_major, n_minor, n_patch, _ = n_minus_1_item["version"]
+        print(f"✅ 推荐 (N-1 minor): {args.image}:{n_minus_1_item['name']}")
+        print(f"   {n_major}.{n_minor} 系列最新 patch，发布于 {format_date(n_minus_1_item['last_updated'])}")
+    else:
+        print("⚠️  仅找到一个 minor 系列，无法推荐 N-1，请手动确认是否可降级 major")
+    print()
+
+    print(f"最近 {args.top} 个稳定 tag（每个 minor 取最新 patch）:")
+    n_minus_1_key = sorted_minors[1] if len(sorted_minors) >= 2 else None
+    for key in sorted_minors[:args.top]:
+        item = minor_latest[key]
+        marker = ""
+        if key == latest_minor:
+            marker = "  ← 最新"
+        elif key == n_minus_1_key:
+            marker = "  ← 推荐 (N-1)"
+        print(f"  {item['name']:20s}  {format_date(item['last_updated'])}{marker}")
+
+
+def format_date(iso: str) -> str:
+    if not iso:
+        return "-"
+    try:
+        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+        return dt.strftime("%Y-%m-%d")
+    except ValueError:
+        return iso[:10]
+
+
+if __name__ == "__main__":
+    main()

package/templates/claude-global/skills/dwy-docker/scripts/scan_images.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# 扫描项目中所有 Docker 镜像引用，输出违规清单（latest / 浮动 tag / 缺 tag）。
+#
+# 用法：
+#     bash scan_images.sh [project-path]
+#
+# 不传路径则扫描当前目录。脚本只读不写，仅输出报告，不修改任何文件。
+
+set -euo pipefail
+
+ROOT="${1:-.}"
+
+if [ ! -d "$ROOT" ]; then
+    echo "错误：路径不存在或不是目录：$ROOT" >&2
+    exit 2
+fi
+
+# 浮动 tag 黑名单（不含版本号的纯字符串 tag）
+FLOATING_TAGS_RE='^(latest|stable|mainline|current|release|lts|rolling|main|master|head|edge|nightly|alpine|slim|bookworm|bullseye|buster|jammy|focal|noble|trixie)$'
+
+# 临时输出文件
+TMP_OUT="$(mktemp)"
+trap 'rm -f "$TMP_OUT"' EXIT
+
+count_critical=0
+count_high=0
+count_low=0
+
+# 工具函数：分级记录
+record() {
+    local level="$1"
+    local file="$2"
+    local line="$3"
+    local content="$4"
+    local hint="$5"
+    printf "[%s] %s:%s\n  %s\n  → %s\n\n" "$level" "$file" "$line" "$content" "$hint" >> "$TMP_OUT"
+    case "$level" in
+        critical) count_critical=$((count_critical + 1)) ;;
+        high) count_high=$((count_high + 1)) ;;
+        low) count_low=$((count_low + 1)) ;;
+    esac
+}
+
+# 解析 image 字符串，返回违规级别和提示
+# 输入：image_ref（如 nginx:latest、postgres、redis:7）
+# 输出：通过 record 函数记录
+analyze_image() {
+    local image_ref="$1"
+    local file="$2"
+    local line="$3"
+    local raw_line="$4"
+
+    # 去掉 digest 部分（@sha256:...）参与 tag 分析
+    local without_digest="${image_ref%@sha256:*}"
+
+    # 拆分 image 和 tag
+    local image_part tag_part
+    if [[ "$without_digest" == *:* ]]; then
+        # 注意 registry 可能含端口（如 registry.example.com:5000/image:tag）
+        # 用最后一个冒号分隔
+        image_part="${without_digest%:*}"
+        tag_part="${without_digest##*:}"
+    else
+        image_part="$without_digest"
+        tag_part=""
+    fi
+
+    # 1. 缺 tag（等同于 latest）
+    if [ -z "$tag_part" ]; then
+        record "critical" "$file" "$line" "$raw_line" "镜像 $image_part 未指定 tag（等同于 latest），改为固定版本如 $image_part:<N-1-minor>"
+        return
+    fi
+
+    # 2. 显式 latest
+    if [ "$tag_part" = "latest" ]; then
+        record "critical" "$file" "$line" "$raw_line" "禁止使用 latest，改为固定版本如 $image_part:<N-1-minor>（用 query_dockerhub.py 查推荐版本）"
+        return
+    fi
+
+    # 3. 浮动 tag（不含数字）
+    if [[ "$tag_part" =~ $FLOATING_TAGS_RE ]]; then
+        record "high" "$file" "$line" "$raw_line" "tag '$tag_part' 是浮动 tag，会随上游更新漂移，改为带版本号的具体 tag"
+        return
+    fi
+
+    # 4. 单段数字（如 redis:7、postgres:17）
+    if [[ "$tag_part" =~ ^v?[0-9]+$ ]]; then
+        record "high" "$file" "$line" "$raw_line" "单段版本号 '$tag_part' 实际是浮动 tag（指向该 major 最新），钉到 minor 或 patch"
+        return
+    fi
+
+    # 5. 看起来固定但没有 digest（仅作为低优先级提醒）
+    if [[ "$tag_part" =~ ^v?[0-9]+\.[0-9]+ ]] && [[ ! "$image_ref" =~ @sha256: ]]; then
+        # 不是所有 image 都需要 digest，这里只对常见生产关键服务提醒
+        if [[ "$image_part" =~ (postgres|mysql|mariadb|mongo|redis|kafka|rabbitmq|elasticsearch|nginx|envoyproxy)$ ]]; then
+            record "low" "$file" "$line" "$raw_line" "生产关键服务建议追加 @sha256:... digest，让 image 完全不可篡改"
+        fi
+    fi
+}
+
+# 扫描 Dockerfile 风格文件
+scan_dockerfiles() {
+    while IFS= read -r -d '' f; do
+        local lineno=0
+        while IFS= read -r line; do
+            lineno=$((lineno + 1))
+            # 匹配 FROM 指令，去掉 AS 别名
+            if [[ "$line" =~ ^[[:space:]]*FROM[[:space:]]+([^[:space:]]+) ]]; then
+                local image_ref="${BASH_REMATCH[1]}"
+                # 跳过参数化的 FROM（如 FROM ${BASE_IMAGE}）
+                if [[ "$image_ref" =~ ^\$\{ ]] || [[ "$image_ref" =~ ^\$[A-Z_] ]]; then
+                    continue
+                fi
+                # 跳过 scratch
+                if [ "$image_ref" = "scratch" ]; then
+                    continue
+                fi
+                analyze_image "$image_ref" "$f" "$lineno" "$(echo "$line" | sed 's/^[[:space:]]*//')"
+            fi
+        done < "$f"
+    done < <(find "$ROOT" \
+        \( -name "Dockerfile" -o -name "Dockerfile.*" -o -name "*.Dockerfile" \) \
+        -not -path "*/node_modules/*" \
+        -not -path "*/.git/*" \
+        -print0)
+}
+
+# 扫描 yaml 风格文件（compose / k8s / CI）
+scan_yaml_files() {
+    while IFS= read -r -d '' f; do
+        local lineno=0
+        while IFS= read -r line; do
+            lineno=$((lineno + 1))
+            # 匹配 image: xxx 或 image: "xxx"
+            if [[ "$line" =~ ^[[:space:]]*image:[[:space:]]*[\"\']?([^[:space:]\"\'#]+) ]]; then
+                local image_ref="${BASH_REMATCH[1]}"
+                # 跳过模板变量
+                if [[ "$image_ref" =~ ^\$\{ ]] || [[ "$image_ref" =~ ^\$[A-Z_] ]] || [[ "$image_ref" =~ \{\{ ]]; then
+                    continue
+                fi
+                analyze_image "$image_ref" "$f" "$lineno" "$(echo "$line" | sed 's/^[[:space:]]*//')"
+            fi
+        done < "$f"
+    done < <(find "$ROOT" \
+        \( -name "docker-compose*.yml" -o -name "docker-compose*.yaml" \
+           -o -name "compose.yml" -o -name "compose.yaml" \
+           -o -name "*.yaml" -o -name "*.yml" \) \
+        -not -path "*/node_modules/*" \
+        -not -path "*/.git/*" \
+        -not -path "*/dist/*" \
+        -not -path "*/build/*" \
+        -print0)
+}
+
+echo "扫描目录: $ROOT" >&2
+echo "" >&2
+
+scan_dockerfiles
+scan_yaml_files
+
+# 输出结果
+total=$((count_critical + count_high + count_low))
+
+if [ "$total" -eq 0 ]; then
+    echo "✅ 未发现违规：所有镜像都已固定到具体版本。"
+    exit 0
+fi
+
+cat "$TMP_OUT"
+
+echo "----------------------------------------"
+echo "汇总: $total 项问题"
+echo "  critical: $count_critical  (latest / 缺 tag)"
+echo "  high:     $count_high      (浮动 tag / 单段版本号)"
+echo "  low:      $count_low       (建议补 digest)"
+echo ""
+echo "下一步："
+echo "  1. 用 query_dockerhub.py <image> 查每个违规镜像的推荐版本"
+echo "  2. 用 Edit 工具逐项修复，不要批量替换（不同环境可能用不同 tag 变体）"
+
+# 有 critical 或 high 时返回非零，方便 CI 集成
+if [ "$count_critical" -gt 0 ] || [ "$count_high" -gt 0 ]; then
+    exit 1
+fi
+exit 0