GitHub + ACR 全周期发布管控

适用于任何语言（Python / Go / Rust / Node…）的 Docker 化项目。 从"新建项目配置"到"发布后验证+下版本规划"，一条流水线管到底。

快速开始

一、核心概念

项目结构约定

{project-name}-v{X.Y.Z}/
├── {source}/                     ← 源码目录（可配置名）
├── data/
│   └── VERSIONS.json             ← 版本元数据（基石文件）
├── Dockerfile                    ← 可配置路径
├── docker-compose.yml            ← 可配置路径
├── VERSION                       ← 可选
├── .github/workflows/ci.yml      ← 可选（skill 可生成模板）
├── scripts/                      ← 工具脚本（skill 可生成）
│   ├── check_version_consistency.py
│   ├── smoke_test.py
│   ├── post_deploy_verify.py
│   └── full_release_check.py
└── ...（其他项目文件）

VERSIONS.json 标准结构

{
  "current": {
    "version": "X.Y.Z",
    "date": "YYYY-MM-DD",
    "notes": "描述",
    "data_version": 1,
    "digest": ""
  },
  "changelog": [
    {
      "version": "X.Y.Z",
      "date": "YYYY-MM-DD",
      "notes": "描述",
      "detail": {
        "sections": [
          { "type": "Added / 新增", "items": ["功能A", "功能B"] },
          { "type": "Fixed / 修复", "items": [] }
        ]
      }
    }
  ]
}

版本管理规则（红线）

1. 新建版本分支 → cp -r {project}-v{old} {project}-v{new}
2. 必须完整复制 data/ 目录（含 VERSIONS.json）
3. 只改 current.version 和 current.date
4. changelog 历史绝不动
5. 同版本多条 changelog → 合并为一条，日期取较早的，sections 按 type 去重
6. 新版本条目先空着（detail.sections 为空），等实际更新再填

二、交互式项目配置

当用户说"新建发布流程"时，进入以下问答流程：

第1轮：基本信息

第2轮：版本管理

第3轮：构建与容器化

第4轮：ACR 与部署模式

说明:

• local：纯本地 Docker (docker-compose)，无远程服务器，跳过后端部署与远端验证
• remote：传统远程服务器模型，需 SSH 权限和部署路径

第5轮：可持续性（可选但建议）

第6轮：汇总确认

展示完整配置摘要，用户确认后写入：

projects/{name}.json          ← 项目配置
scripts/                      ← 生成脚本模板（可选）

三、可持续性评分

每次发布前检查时，skill 对照配置中的可持续性字段，生成评分报告。

检查项总表

评分对话示例

Skill: 📊 可持续性评分：12/18

  ✅ 已具备：Dockerfile、VERSIONS.json、版本文件、...
  ⚠️ 建议补充：
    - scripts/ 目录（检查脚本框架）→ 发版前无法自动检测问题
    - 配置备份机制 → 配置损坏后无法自动恢复
  ❌ 应修复：无

  要补充缺失功能吗？
  - 是 → 我帮你生成脚本模板
  - 跳过 → 发布后可继续，但建议尽快补

四、全周期 13 步发布流程

阶段 A：发布流前（Pre-release）

阶段 B：发布流（Release）

阶段 C：发布流后（Post-release）

部署模式 local 时，Step 10 自动跳过，无远端验证环节。 | | 更新项目记忆文件 | | | | 询问用户：是否创建下一版本？版本号？ | | | | 是 → 进入 Step 0 | |

五、脚本模板

项目配置完成后，skill 可在 scripts/ 目录生成以下脚本（模板变量从配置中替换）：

5.1 check_version_consistency.py

扫描所有版本号源是否一致。支持 --verbose 和 --fix。

从配置读取：version.file、version.pattern、versions_json、docker.dockerfile、docker.compose_file。

5.2 smoke_test.py

API 冒烟测试。需要服务运行。

从配置读取：docker.port、验证 URL 路径。

5.3 post_deploy_verify.py

远程部署验证：容器状态 + API 可达 + 版本一致 + digest。

从配置读取：server.host、server.verify_url、项目名（作为容器名）。

⚠️ 部署模式为 local 时此脚本不生成，Step 10 自动跳过。

5.4 full_release_check.py

一键综合检查入口：版本一致性 → 代码基线 → 可持续性 → Git 状态。

六、热更新（Hotfix）

与标准发布的区别：

• 跳过版本号一致性检查（不改版本号）
• 版本号加 -hotfix.N 后缀
• 跳过 CHANGELOG 更新
• 不创建 GitHub Release
• 仅：语法检查 → 确认 → 编译 → 构建 → 推送 → 部署 → 验证

热更新步骤：

1. 快速语法检查
2. 确认 hotfix 版本号
3. 编译前端（若有）
4. git commit + push
5. workflow_dispatch 触发构建
6. ACR 推送
7. （仅 remote）远程更新
8. （仅 remote）验证

七、触发表

八、与 GitHub Actions 的关系

Skill 本地操作                          GitHub Actions
┌──────────────────────┐              ┌──────────────────┐
│ 1. 版本一致性检查       │              │                  │
│ 2. 可持续性评分         │              │ tag 推送触发 →   │
│ 3. 用户确认             │── 推代码 ──▶│ Build → Push ACR │
│ 4. 编译前端             │              │                  │
│ 5. git commit/tag/push │              │                  │
└──────────────────────┘              └──────────────────┘

GitHub Actions 只做"构建+推送"。版本控制、CHANGELOG、发布检查全部由 skill 在本地完成。

九、版本规划对话

发布完成后，skill 自动触发收尾对话：

Skill: ✅ 发布完成！vX.Y.Z 已部署上线。

  要开始下一版本的开发吗？

  预设版本号：
    - X.Y.{Z+1}（补丁）
    - X.{Y+1}.0（小版本）
    - {X+1}.0.0（大版本）

  若创建，我会：
  1. 复制当前版本文件夹
  2. 更新 VERSIONS.json 的 current 段
  3. 清空新版本 changelog 条目
  4. 同步版本号

  或者暂不创建，需要时再说"新建版本"。

十、注意事项

1. 敏感信息脱敏：日志/输出/推送中的密钥必须脱敏
2. 版本号一致性：5+ 个版本号源必须一致
3. 数据迁移安全：配置迁移走备份→合并→验证→回滚
4. 不自动执行：所有对外操作（push/tag/ssh/服务器更新）必须经用户确认
5. changelog 管理：同版本多条合并，sections 按 type 去重
6. Docker 构建策略：多阶段构建，自动压缩镜像
7. 部署模式感知：local 模式下自动跳过远程部署/远端验证步骤，不要强制执行 SSH 命令

十一、常用命令