feat: automate version releases

Author: vastsa

.github/workflows/docker-image.yml

@@ -2,6 +2,11 @@ name: Build and push Docker image
 
 on:
   workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Optional release tag created by Release Please
+        required: false
+        type: string
   push:
     branches:
       - master
@@ -20,21 +25,71 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          ref: ${{ inputs.release_tag || github.ref }}
           submodules: true
 
       - name: Extract metadata
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY_IMAGE }}
+          flavor: |
+            latest=false
           tags: |
-            type=ref,event=branch
-            type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
+            type=ref,event=branch,enable=${{ inputs.release_tag == '' }}
+            type=ref,event=pr,enable=${{ inputs.release_tag == '' }}
+            type=semver,pattern={{version}},enable=${{ inputs.release_tag == '' }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ inputs.release_tag == '' }}
+            type=semver,value=${{ inputs.release_tag }},pattern={{version}},enable=${{ inputs.release_tag != '' }}
+            type=semver,value=${{ inputs.release_tag }},pattern={{major}}.{{minor}},enable=${{ inputs.release_tag != '' }}
             type=raw,value=dev,enable=${{ github.ref == 'refs/heads/dev' }}
-            type=raw,value=beta,enable={{is_default_branch}}
-            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=edge-,enable=${{ github.ref == 'refs/heads/master' && inputs.release_tag == '' }}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') || inputs.release_tag != '' }}
+
+      - name: Verify release version
+        if: ${{ startsWith(github.ref, 'refs/tags/v') || inputs.release_tag != '' }}
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
+        run: |
+          source_version="$(tr -d '[:space:]' < VERSION)"
+          tag_version="${RELEASE_TAG#v}"
+          test "$source_version" = "$tag_version" || {
+            echo "Version mismatch: VERSION=$source_version, tag=$tag_version" >&2
+            exit 1
+          }
+
+      - name: Resolve source revision
+        id: source-revision
+        shell: bash
+        run: |
+          revision="$(git rev-parse HEAD)"
+          echo "value=$revision" >> "$GITHUB_OUTPUT"
+          echo "short=${revision::12}" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve latest frontend revisions
+        id: frontend-revisions
+        shell: bash
+        run: |
+          frontend_2024_ref="$(git ls-remote https://github.com/vastsa/FileCodeBoxFronted.git HEAD | cut -f1)"
+          frontend_2023_ref="$(git ls-remote https://github.com/vastsa/FileCodeBoxFronted2023.git HEAD | cut -f1)"
+          test -n "$frontend_2024_ref"
+          test -n "$frontend_2023_ref"
+          echo "frontend_2024=$frontend_2024_ref" >> "$GITHUB_OUTPUT"
+          echo "frontend_2023=$frontend_2023_ref" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve application version
+        id: app-version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ inputs.release_tag }}
+        run: |
+          source_version="$(tr -d '[:space:]' < VERSION)"
+          if [[ "$GITHUB_REF" == refs/tags/v* || -n "$RELEASE_TAG" ]]; then
+            echo "value=$source_version" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=${source_version}-dev+${{ steps.source-revision.outputs.short }}" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
@@ -60,6 +115,11 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APP_VERSION=${{ steps.app-version.outputs.value }}
+            VCS_REF=${{ steps.source-revision.outputs.value }}
+            FRONTEND_2024_REF=${{ steps.frontend-revisions.outputs.frontend_2024 }}
+            FRONTEND_2023_REF=${{ steps.frontend-revisions.outputs.frontend_2023 }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
           provenance: false

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Create release
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Create or update release
+        id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Merge release pull request
+        if: ${{ steps.release.outputs.prs_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_PR: ${{ fromJSON(steps.release.outputs.pr).number }}
+        run: |
+          for attempt in {1..120}; do
+            if gh pr merge "$RELEASE_PR" --squash --delete-branch; then
+              break
+            fi
+            if [[ "$attempt" -eq 120 ]]; then
+              echo "Timed out waiting for release PR #$RELEASE_PR to merge" >&2
+              exit 1
+            fi
+            sleep 10
+          done
+          gh workflow run release.yml --ref master
+
+      - name: Publish release image
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.release.outputs.tag_name }}
+        run: gh workflow run docker-image.yml --ref master -f release_tag="$RELEASE_TAG"

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.4.0"
+}

Dockerfile

@@ -2,35 +2,53 @@
 # 前端产物与 CPU 架构无关，使用原生构建平台避免在 QEMU 中运行 Node/pnpm。
 FROM --platform=$BUILDPLATFORM node:20-alpine AS frontend-builder
 
+ARG FRONTEND_2024_REF=main
+ARG FRONTEND_2023_REF=main
+
 RUN apk add --no-cache git python3 make g++
 
 RUN corepack enable && \
     corepack prepare pnpm@9.15.9 --activate
 
 WORKDIR /build
 
-# 克隆并构建 2024 主题
-RUN git clone --depth 1 https://github.com/vastsa/FileCodeBoxFronted.git /build/fronted-2024 && \
+# 克隆并构建固定版本的 2024 主题
+RUN git clone --filter=blob:none --no-checkout https://github.com/vastsa/FileCodeBoxFronted.git /build/fronted-2024 && \
     cd /build/fronted-2024 && \
+    git fetch --depth 1 origin "${FRONTEND_2024_REF}" && \
+    git checkout --detach FETCH_HEAD && \
     pnpm install --frozen-lockfile --prod=false && \
-    pnpm run build
+    VITE_GIT_COMMIT="$(git rev-parse HEAD)" pnpm run build
 
-# 克隆并构建 2023 主题
-RUN git clone --depth 1 https://github.com/vastsa/FileCodeBoxFronted2023.git /build/fronted-2023 && \
+# 克隆并构建固定版本的 2023 主题
+RUN git clone --filter=blob:none --no-checkout https://github.com/vastsa/FileCodeBoxFronted2023.git /build/fronted-2023 && \
     cd /build/fronted-2023 && \
+    git fetch --depth 1 origin "${FRONTEND_2023_REF}" && \
+    git checkout --detach FETCH_HEAD && \
     npm install --legacy-peer-deps && \
     npm run build
 
 # 第二阶段：构建最终镜像
 FROM python:3.12-slim-bookworm
+ARG APP_VERSION
+ARG VCS_REF=unknown
+ARG FRONTEND_2024_REF=main
+ARG FRONTEND_2023_REF=main
 LABEL author="Lan"
 LABEL email="xzu@live.com"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+LABEL org.opencontainers.image.revision="${VCS_REF}"
+LABEL org.opencontainers.image.filecodebox.frontend-2024-revision="${FRONTEND_2024_REF}"
+LABEL org.opencontainers.image.filecodebox.frontend-2023-revision="${FRONTEND_2023_REF}"
 
 WORKDIR /app
 
 # 复制项目文件（通过 .dockerignore 排除不必要的文件）
 COPY . .
 
+# 分支镜像使用带提交号的开发版本；正式镜像使用 VERSION 中的版本。
+ENV APP_VERSION="${APP_VERSION}"
+
 # 设置时区
 RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
     echo 'Asia/Shanghai' > /etc/timezone

VERSION

@@ -0,0 +1 @@
+2.4.0

core/version.py

@@ -1 +1,20 @@
-APP_VERSION = "2.4.0"
+import os
+import re
+from pathlib import Path
+
+
+VERSION_FILE = Path(__file__).resolve().parents[1] / "VERSION"
+VERSION_PATTERN = re.compile(
+    r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$"
+)
+
+
+def load_app_version() -> str:
+    version = os.getenv("APP_VERSION") or VERSION_FILE.read_text(encoding="utf-8")
+    version = version.strip()
+    if not VERSION_PATTERN.fullmatch(version):
+        raise RuntimeError(f"无效的应用版本号: {version!r}")
+    return version
+
+
+APP_VERSION = load_app_version()

docker-compose.yml

@@ -1,12 +1,12 @@
 version: "3"
 services:
   file-code-box:
-    image: lanol/filecodebox:latest
+    image: lanol/filecodebox:2.4.0 # x-release-please-version
     volumes:
       - fcb-data:/app/data:rw
     restart: unless-stopped
     ports:
       - "12345:12345"
 volumes:
   fcb-data:
-    external: false
+    external: false

docs/.vitepress/config.mts

@@ -55,6 +55,7 @@ export default defineConfig({
                 { text: '存储配置', link: '/guide/storage' },
                 { text: '安全设置', link: '/guide/security' },
                 { text: '系统配置', link: '/guide/configuration' },
+                { text: '版本发布', link: '/guide/releasing' },
               ],
             },
           ],
@@ -148,6 +149,7 @@ export default defineConfig({
                   text: 'System Configuration',
                   link: '/en/guide/configuration',
                 },
+                { text: 'Releasing', link: '/en/guide/releasing' },
               ],
             },
           ],

docs/en/changelog.md

@@ -1,5 +1,7 @@
 ## [Unreleased]
 
+<!-- Current release: 2.4.0 x-release-please-version -->
+
 ### Added
 
 - Added a global storage capacity limit with concurrency-safe reservations for regular, chunked, presigned, and admin file uploads.

docs/en/guide/releasing.md

@@ -0,0 +1,25 @@
+# Releasing
+
+The project uses Semantic Versioning and Conventional Commits.
+
+Complete these settings once in both GitHub repositories:
+
+- In `Settings → Actions → General → Workflow permissions`, grant read/write
+  access and allow GitHub Actions to create pull requests.
+- Keep squash merging enabled. The release workflow waits for required checks
+  before merging the release pull request.
+- Add `DOCKER_USERNAME` and `DOCKER_PASSWORD` Actions secrets to the backend repository.
+
+1. Merge commits using Conventional Commit types such as `feat:` and `fix:` into the default branch.
+2. Release Please creates and merges the release pull request and updates `VERSION` and the changelog.
+3. The workflow then creates `vX.Y.Z`, a GitHub Release, and dispatches the production image build.
+4. Releases publish `X.Y.Z`, `X.Y`, and `latest`; branches publish `dev` or `edge-*` images.
+5. Each image build resolves the latest commit from both frontend default branches automatically.
+
+Every `fix:`, `feat:`, or breaking change merged into the default branch therefore
+creates a Patch, Minor, or Major release automatically. Non-release commits such
+as `docs:` and `chore:` do not publish a release on their own.
+
+The backend runtime version comes from `VERSION`. Container branch builds inject a
+commit-qualified development version through `APP_VERSION`; release tags must exactly
+match `VERSION`. OCI image labels record the resolved backend and frontend commits for traceability.