GitHub + ACR 全周期发布管控#

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

快速开始#

你说Skill 执行新建发布流程 / 搭建发布流交互式问询 → 生成项目配置 → 初始化骨架检查 / 检查发布仅流前检查（版本一致性+代码基线+可持续性评分）发布 / 发版 / push完整发布（流前检查→确认→构建→推送→部署→验证→收尾）热更新 / hotfix快速修复发布（跳过版本号+CHANGELOG）下个版本 / 下版本进入版本规划对话

---

一、核心概念#

项目结构约定#

text

{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 标准结构#

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轮：基本信息#

字段必填示例项目名（英文小写）✅my-app一句话描述✅XX应用GitHub 仓库 URL✅github.com/user/my-app

第2轮：版本管理#

字段必填示例当前版本目录（完整路径）✅/home/.../my-app-v1.0.0版本文件路径（相对项目根）✅backend/__version__.py版本号提取模板✅__version__ = "{version}" → 提取 "1.0.0"版本格式✅semantic（X.Y.Z）是否有 VERSIONS.json✅yes / no

第3轮：构建与容器化#

字段必填示例编程语言✅python / go / rust / node / java是否有前端✅yes / no前端编译命令条件cd frontend && node compile.jsDockerfile 路径✅Dockerfiledocker-compose 路径✅docker-compose.yml服务端口✅8765前端编译后产物路径条件frontend/assets/

第4轮：ACR 与部署模式#

字段必填示例ACR 仓库地址✅registry.cn-hangzhou.aliyuncs.comACR 命名空间✅my-teamACR 镜像名✅my-app部署模式✅local / remote服务器地址条件（ remote 时需要）10.0.1.138服务器部署路径条件（ remote 时需要）~/docker/my-app/验证 URL条件（ remote 时需要）http://10.0.1.138:8765/api/versions

说明:

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

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

字段默认值说明是否有数据迁移框架nodata_manager.py + migrations/是否有配置备份/回滚no配置保存时自动备份是否有启动健康检查no容器启动时自检是否有版本一致性脚本noscripts/check_version_consistency.py是否有冒烟测试脚本noscripts/smoke_test.py是否有发布后验证脚本noscripts/post_deploy_verify.py

第6轮：汇总确认#

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

text

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

---

三、可持续性评分#

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

检查项总表#

类别检查项级别不带的影响🏗 骨架scripts/ 目录⚠️ 建议无自动化检查框架.github/workflows/ci.yml⚠️ 建议GitHub Actions 无法自动构建Dockerfile❌ 必须无法容器化部署docker-compose.yml⚠️ 建议本地开发测试不便.gitignore⚠️ 建议可能误传敏感文件📦 版本VERSIONS.json❌ 必须无版本追踪，无法做迁移版本号一致性❌ 必须发布版本号错乱版本文件❌ 必须无法从代码读版本号🔒 数据配置备份/回滚⚠️ 建议配置损坏无法恢复数据迁移脚本⚠️ 建议跨版本升级旧数据不可用数据版本号⚠️ 建议无法判断是否需迁移🛡 运维启动健康检查⚠️ 建议异常无声版本一致性脚本⚠️ 建议发版前无法自动检测冒烟测试脚本⚠️ 建议发布后无法自动验证发布后验证脚本⚠️ 建议远程部署无法确认🧪 测试模块冒烟测试⭐ 可选核心逻辑变更无快速验证单元测试框架⭐ 可选严重回退风险

评分对话示例#

text

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

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

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

---

四、全周期 13 步发布流程#

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

步骤操作自动化Step 0版本分支创建： cp -r {项目}-v{旧} {项目}-v{新}手动完整复制 data/（含 VERSIONS.json）检查脚本校验只改 current.version + current.date，changelog 历史不动新版本 changelog 条目先空着Step 1版本号原点同步检查check_version_consistency.py扫描：版本文件 / VERSIONS.json / Dockerfile / docker-compose / VERSION不一致 → 中止； --fix 可自动修正Step 2代码基线检查（按语言）Python: python -m py_compileGo: go vet ./...Rust: cargo checkNode: node -cJava: javac / mvn compileStep 3可持续性评分对照配置清单展示缺失项 + 不带的影响询问用户：补充 or 跳过Step 4预发布确认展示：版本号 + 检查结果 + 评分用户确认 → 进入发布

阶段 B：发布流（Release）#

步骤操作Step 5更新 VERSIONS.json：追加 changelog 条目Step 6编译前端（若有）Step 7git add -A → git commit → git pushStep 8git tag -a v{版本} → git push --tags → GitHub Actions 自动构建Step 9****（仅 remote 模式） 远程服务器部署：SSH → docker compose pull && up -d说明: 部署模式在交互配置第4轮设定。 local 模式自动跳过 Step 9（无远程服务器）。

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

步骤操作自动化适用Step 10远端验证：容器状态 + API + 版本一致性 + digestpost_deploy_verify.py仅 remote****Step 11镜像 digest 同步：获取 ACR digest → 写入 VERSIONS.json可选（local 也支持）Step 12环境清理：旧镜像 + 构建缓存通用Step 13收尾 + 下版本规划交互通用

部署模式 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
• 仅：语法检查 → 确认 → 编译 → 构建 → 推送 → 部署 → 验证

热更新步骤：

text

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

---

七、触发表#

用户说触发动作新建发布流程 / 搭建发布流交互式问询 → 生成配置 → 初始化骨架检查 / 检查发布仅流前检查（不发布）发布 / 发版 / push标准完整发布热更新 / hotfix快速修复发布下个版本 / 下版本版本规划对话检查项目可持续性评分 + 缺失项报告

---

八、与 GitHub Actions 的关系#

text

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

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

---

九、版本规划对话#

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

text

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 命令

十一、常用命令#

操作命令流前全检python3 scripts/full_release_check.py版本一致性检查python3 scripts/check_version_consistency.py版本一致性检查+修正python3 scripts/check_version_consistency.py --fixAPI 冒烟测试python3 scripts/smoke_test.py --base-url http://localhost:PORT发布后验证python3 scripts/post_deploy_verify.py --target HOST --ssh前端编译cd frontend && node compile.js本地构建测试docker build -t {name}:dev .远程服务器更新ssh root@HOST "cd PATH && docker compose pull && up -d"