GitHub + ACR 项目发布流程

概述

管理项目的完整发布流程，同时覆盖 GitHub Release 和阿里云 ACR Docker 镜像推送，支持两种模式：

• 标准发布：代码检查 → 版本确认 → GitHub 打 tag → GitHub Actions 构建镜像 → GitHub Release → ACR 镜像推送 → 服务器更新（可选）
• 热更新：代码检查 → 推代码到 GitHub → GitHub Actions 构建镜像 → ACR 镜像推送 → 服务器更新（可选）（版本号加 -hotfix.N 后缀，跳过 GitHub Release）

核心原则

1. 所有正式发布均通过 GitHub Actions 构建镜像，不本地构建。热更新与标准发布的区别仅在于是否打 tag 和是否创建 Release。
2. 版本号一致性：代码版本号（__version__.py）、data/VERSIONS.json 中 current.version、GitHub tag 必须一致。
3. 推送到 GitHub 前更新 VERSIONS.json：更新 current 段，追加当前版本 changelog 条目，不动历史记录。

项目发布流配置文件

每个项目的发布流配置存储在：

~/.openclaw/workspace/skills/github-acr-release/projects/{project-name}.json

配置结构

{
  "name": "my-project",
  "description": "项目描述",
  "created_at": "2026-06-09",
  "project_dir": "/home/openclaw/workspace/my-project",
  "version": {
    "file": "backend/__version__.py",
    "pattern": "__version__ = \"X.Y.Z\"",
    "format": "semantic"
  },
  "versions_json": "data/VERSIONS.json",
  "source_lang": "python",
  "has_frontend": true,
  "frontend_build_cmd": "cd frontend && node compile.js",
  "docker": {
    "compose_file": "docker-compose.yml",
    "Dockerfile": "Dockerfile",
    "acr": {
      "registry": "registry.cn-hangzhou.aliyuncs.com",
      "namespace": "my-project",
      "repo": "my-project",
      "image_url": "registry.cn-hangzhou.aliyuncs.com/my-project/my-project"
    },
    "port": 8765
  },
  "server": {
    "enabled": false,
    "user": "",
    "host": "",
    "project_dir": "",
    "verify_url": ""
  },
  "repo": {
    "branch": "main",
    "remote": "origin"
  }
}

新建发布流程：交互式问询

当用户说"新建发布流程"、"搭建发布流"、"创建发布配置"等时，进入交互式问询流程。

第一轮：基本信息

• 项目名称（英文小写，用作配置文件名）
• 项目路径（本地工作目录）
• 项目描述（一句话）

第二轮：版本管理

• 版本记录文件路径
• 版本号格式（语义化 X.Y.Z）
• 版本更新日志文件路径（data/VERSIONS.json）
• 当前版本号

第三轮：构建与部署

• 编程语言（Python / Go / Rust / Node.js）
• 是否有前端
• 前端构建命令（如有）
• Docker 端口

第四轮：远程配置

• ACR 命名空间
• ACR 镜像名
• 是否有远程服务器（yes / no）
• 服务器地址、部署路径、验证 URL

确认环节

收集完毕后生成配置摘要展示给用户，等待确认后写入配置文件。

确认后写入配置，告知用户：

✅ "{项目名}" 发布流已创建。后续说"发布"或"热更新"即可触发。

流程执行

触发条件

注意：如果项目还没有发布流配置文件（projects/{project-name}.json 不存在），提示用户先"新建发布流程"。

标准发布流程

Phase 1: 预发布检查（强制执行）

Step 1.1: 代码质量检查

• Python: python3 -m py_compile
• Go: go vet ./...
• Rust: cargo check
• Node.js: node -c
• 如有静态分析工具（pylint/flake8/eslint/clippy），推荐执行但非强制
• 通过标准：无编译/语法错误

Step 1.2: 版本信息验证

1. 从版本文件中提取当前版本号（__version__.py），确认 X.Y.Z 格式
2. 从版本日志（data/VERSIONS.json）中读取 current.version
3. 确认两者一致。不一致则报错中止，要求先更新 current.version

• 通过标准：格式正确，JSON 有效，版本号一致

Step 1.3: 生成发布说明并更新 VERSIONS.json 根据本次发布内容，生成 changelog 条目，格式化为：

## {VERSION} ({DATE})

### 概述
{NOTES}

### Added / 新增
- {item}

### Changed / 优化
- {item}

### Fixed / 修复
- {item}

在用户确认前，先更新 data/VERSIONS.json：

1. 将当前版本的 changelog 条目（含 detail sections）追加到 changelog 数组头部
2. 更新 current 段：version、date、notes 改为本次发布信息
3. changelog 中的历史记录不动

展示格式化后的 Release Notes 给用户，等待明确确认后继续。

Phase 2: 构建与发布（用户确认后执行）

Step 2.1: 编译前端（如有）

cd frontend && node compile.js

Step 2.2: 推代码到 GitHub

cd {project_dir}
git add -A
git commit -m "release: v{VERSION} — {NOTES摘要}"
git push {remote} {branch}

VERSIONS.json 已在此前更新，一并推送到 GitHub。镜像通过 GitHub Actions 构建。

Step 2.3: 打 Tag 并推送（标准发布执行，热更新跳过）

git tag -a v{VERSION} -m "Release v{VERSION}"
git push {remote} {branch} --tags

GitHub Actions 自动监听 tag 事件触发构建。

Step 2.4: 等待 GitHub Actions 构建完成

• 标准发布：on: push: tags 自动触发
• 构建完成后推送镜像到 ACR（ACR 已在 Workflow 中配置凭据）

Step 2.5: 创建 GitHub Release 在 GitHub 页面创建 Release，粘贴格式化后的 Release Notes。

Step 2.6: 远程服务器更新（如有）

ssh {user}@{host}
cd {project_dir}
docker compose pull
docker compose up -d
docker compose ps
curl -s {verify_url}

Step 2.7: 更新记忆与文档

热更新流程

与标准发布区别：

• 跳过发布说明格式化，改为简单确认
• 跳过 GitHub tag 和 Release
• 版本号加 -hotfix.N 后缀（N 从 1 递增）

执行步骤：

1. 快速代码检查（仅语法检查）
2. 确认当前版本号，生成 hotfix 版本号（如 1.0.2-hotfix.1）
3. 简单确认（不格式化 Release Notes）
4. 编译前端（如有）
5. 推代码到 GitHub（不 tag）：

   cd {project_dir}
   git add -A
   git commit -m "hotfix: v{HOTFIX_VERSION}"
   git push {remote} {branch}
   

6. 触发 GitHub Actions 构建：
   • 通过 workflow_dispatch 手动触发
   • 或配置 push 事件自动触发
7. 镜像推送到 ACR（由 GitHub Actions 自动完成）
8. 服务器更新：

   ssh {user}@{host}
   cd {project_dir}
   docker compose pull
   docker compose up -d
   curl -s {verify_url}
   

9. 验证服务

本地构建（仅开发调试）

正式发布和热更新均通过 GitHub Actions 构建。本地构建仅用于开发调试：

docker build -t {acr.image_url}:{VERSION} .
docker run -p {port}:{port} {acr.image_url}:{VERSION}

构建与 GitHub Actions

构建规则

1. 所有镜像构建通过 GitHub Actions，确保构建可复现
2. GitHub Actions 中使用多阶段构建压缩镜像体积
3. 版本信息通过 BUILD_VERSION 构建参数传入 Dockerfile
4. ACR 凭据在 GitHub Secrets 中配置

Workflow 示例

name: Docker

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:
    inputs:
      version:
        description: 'Build version'
        required: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Login to ACR
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.ACR_REGISTRY }}
          username: ${{ secrets.ACR_USERNAME }}
          password: ${{ secrets.ACR_PASSWORD }}
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ secrets.ACR_IMAGE }}:latest
            ${{ secrets.ACR_IMAGE }}:v${{ inputs.version || github.ref_name }}

环境变量配置

注意事项

1. 敏感信息脱敏（密钥、token、密码：前4位+...+后4位）
2. 所有正式发布均通过 GitHub Actions 构建，不本地构建
3. 始终使用多阶段构建，压缩镜像体积
4. 版本号一致性：代码版本号、data/VERSIONS.json 的 current.version、GitHub tag 必须一致
5. 推送到 GitHub 前更新 VERSIONS.json：更新 current 段，追加当前版本 changelog 条目，不动历史记录
6. 不自动执行，除非用户明确说"发布"、"热更新"
7. 标准发布预发布检查强制：代码检查 + 版本验证 + 二次确认
8. 项目信息缺失时通过问询补全，不要猜测
9. 热更新不产生 GitHub Release，版本号加 -hotfix.N 后缀