新增 CI 和 Release 流水线，优化构建与发布流程，添加 VERSION 文件以统一版本管理

.gitea/workflows/ci.yaml

@@ -1,230 +0,0 @@
-# .gitea/workflows/ci.yaml
-name: Build and Release
-
-on:
-  push:
-    branches: [main, develop]
-    tags: ['*']
-
-env:
-  DOCKER_BUILDKIT: "1"
-  PRODUCT_NAME: "xxxig"
-  PACKAGE_VERSION: "6.26.0"
-  BUILDX_NO_DEFAULT_ATTESTATIONS: "1"
-
-jobs:
-  build-and-test:
-    runs-on: ${{ matrix.arch == 'amd64' && 'ubuntu-latest-amd64' || 'ubuntu-latest-arm64' }}
-    strategy:
-      matrix:
-        arch: [amd64, arm64]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Docker Buildx
-        run: |
-          # 创建 buildx builder（原生构建不需要 QEMU）
-          docker buildx create --use --name native-builder \
-            --driver docker-container \
-            --driver-opt network=host \
-            --driver-opt env.BUILDKIT_STEP_LOG_MAX_SIZE=50000000 \
-            --driver-opt env.BUILDKIT_STEP_LOG_MAX_SPEED=10000000 \
-            || true
-          docker buildx inspect --bootstrap
-
-      - name: Build binaries
-        run: |
-          XXXIG_VERSION=v${PACKAGE_VERSION}   # 上游源码 git tag 带 v 前缀，需补回
-          PLATFORM="linux/${{ matrix.arch }}"
-
-          echo "🏗️ Building ${PLATFORM} on native ${{ matrix.arch }} runner"
-          echo "📦 Build: musl 全静态 (docker/Dockerfile, 基于 alpine)"
-
-          # 设置 BuildKit 优化参数
-          export BUILDKIT_PROGRESS=plain
-
-          docker buildx build --pull \
-            --platform ${PLATFORM} \
-            --build-arg XXXIG_VERSION=${XXXIG_VERSION} \
-            --output type=local,dest=./output \
-            -f docker/Dockerfile .
-
-      - name: Package and test
-        run: |
-          DIR="./output/linux_${{ matrix.arch }}"
-
-          if [ ! -d "$DIR" ]; then
-            echo "❌ 构建输出目录不存在: $DIR"
-            exit 1
-          fi
-
-          TARGZ="${PRODUCT_NAME}-${{ matrix.arch }}-linux-static-${PACKAGE_VERSION}.tar.gz"
-          tar -czf "${TARGZ}" -C "$DIR" .
-
-          echo "📦 Created package: ${TARGZ}"
-          ls -lh "${TARGZ}"
-
-          # 快速验证
-          mkdir -p test && tar -xzf "${TARGZ}" -C test
-          test/xxxigDaemon --version 2>/dev/null || echo "⚠️ 跳过版本检查"
-          rm -rf test
-
-      - name: Build Debian package
-        run: |
-          # 安装 dpkg-deb（如果需要）
-          sudo apt-get update && sudo apt-get install -y dpkg-dev
-
-          TARGZ="${PRODUCT_NAME}-${{ matrix.arch }}-linux-static-${PACKAGE_VERSION}.tar.gz"
-
-          echo "📦 Building Debian package for ${{ matrix.arch }}..."
-          chmod +x debian/build-deb.sh
-          ./debian/build-deb.sh ${{ matrix.arch }} ${PACKAGE_VERSION} "${TARGZ}"
-
-          ls -lh *.deb
-
-      - uses: https://github.com/ChristopherHX/gitea-upload-artifact@v4
-        with:
-          name: binaries-${{ matrix.arch }}
-          path: |
-            *.tar.gz
-            *.deb
-          retention-days: 1
-
-  release:
-    runs-on: ubuntu-latest-amd64
-    needs: build-and-test
-    if: startsWith(github.ref, 'refs/tags/')
-    steps:
-      - uses: https://github.com/ChristopherHX/gitea-download-artifact@v4
-        with:
-          pattern: binaries-*
-          path: ./packages
-          merge-multiple: true
-
-      - name: Upload packages and create release
-        env:
-          TOKEN: ${{ secrets.BUILD_TOKEN }}
-          TAG: ${{ github.ref_name }}
-        run: |
-          cd packages
-
-          # 提取仓库信息（移除 https:// 前缀和仓库路径）
-          REGISTRY=$(echo "${{ gitea.server_url }}" | sed 's|https\?://||')
-          OWNER="${{ gitea.repository_owner }}"
-          REPO_NAME=$(echo "${{ gitea.repository }}" | cut -d'/' -f2)
-          VERSION="${TAG#v}"   # 包版本：去掉 git tag 的 v 前缀（registry 路径/下载名/Release 标题用）
-
-          echo "📦 上传包到 Generic Package Registry..."
-          echo "  Registry: ${REGISTRY}"
-          echo "  Owner: ${OWNER}"
-          echo "  Package: ${PRODUCT_NAME}"
-          echo "  Version: ${VERSION}"
-
-          # 上传所有 tar.gz 包到 Generic Package Registry
-          for file in *.tar.gz; do
-            [ ! -f "$file" ] && continue
-            echo "  ⬆️  $file"
-            curl -fsSL -X PUT \
-              -H "Authorization: token ${TOKEN}" \
-              --upload-file "$file" \
-              "https://${REGISTRY}/api/packages/${OWNER}/generic/${PRODUCT_NAME}/${VERSION}/$file" || {
-              echo "❌ 上传失败: $file"
-              exit 1
-            }
-          done
-
-          # 上传 Debian 包到 Debian Package Registry (通用稳定版)
-          echo ""
-          echo "📦 上传 Debian 包到 Debian Package Registry..."
-          for file in *.deb; do
-            [ ! -f "$file" ] && continue
-
-            # 上传到 stable (通用稳定版)
-            echo "  ⬆️  $file → stable"
-            curl -fsSL -X PUT \
-              -H "Authorization: token ${TOKEN}" \
-              --upload-file "$file" \
-              "https://${REGISTRY}/api/packages/${OWNER}/debian/pool/stable/main/upload" || {
-              echo "❌ Debian 包上传失败: $file (stable)"
-              exit 1
-            }
-          done
-
-          # 生成 Release 描述
-          echo ""
-          echo "📝 生成 Release..."
-
-          # 拼接 tar.gz 下载链接
-          ASSETS=$(for f in *.tar.gz; do
-            [ -f "$f" ] || continue
-            echo "- [\`$f\`](https://${REGISTRY}/api/packages/${OWNER}/generic/${PRODUCT_NAME}/${VERSION}/$f)"
-          done)
-
-          BODY=$(cat <<EOF
-          ## Release ${VERSION}
-
-          ### 📥 Debian/Ubuntu 安装
-
-          \`\`\`bash
-          sudo curl https://${REGISTRY}/api/packages/${OWNER}/debian/repository.key -o /etc/apt/keyrings/gitea-${OWNER}.asc
-          echo "deb [signed-by=/etc/apt/keyrings/gitea-${OWNER}.asc] https://${REGISTRY}/api/packages/${OWNER}/debian stable main" | sudo tee /etc/apt/sources.list.d/${OWNER}.list
-          sudo apt-get update && sudo apt-get install xxxig
-          \`\`\`
-
-          ### 📦 tar.gz 下载
-
-          ${ASSETS}
-          EOF
-          )
-
-          RELEASE_DATA=$(jq -n --arg tag "$TAG" --arg ver "$VERSION" --arg body "$BODY" \
-            '{tag_name: $tag, name: "Release \($ver)", body: $body, draft: false, prerelease: false}')
-
-          # 创建 Release
-          echo ""
-          echo "🎉 创建 Release..."
-          RESPONSE=$(curl -fsSL -w "\n%{http_code}" -X POST \
-            -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            "https://${REGISTRY}/api/v1/repos/${{ gitea.repository }}/releases" \
-            -d "${RELEASE_DATA}")
-
-          HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-          RESPONSE_BODY=$(echo "$RESPONSE" | head -n-1)
-
-          if [ "$HTTP_CODE" = "201" ]; then
-            echo "✅ Release 创建成功"
-            RELEASE_ID=$(echo "$RESPONSE_BODY" | grep -o '"id":[0-9]*' | head -1 | cut -d':' -f2)
-            echo "  Release ID: ${RELEASE_ID}"
-          elif [ "$HTTP_CODE" = "409" ]; then
-            echo "⚠️  Release 已存在，获取现有 Release ID..."
-            RELEASE_ID=$(curl -fsSL \
-              -H "Authorization: token ${TOKEN}" \
-              "https://${REGISTRY}/api/v1/repos/${{ gitea.repository }}/releases/tags/${TAG}" | \
-              grep -o '"id":[0-9]*' | head -1 | cut -d':' -f2)
-            echo "  Release ID: ${RELEASE_ID}"
-          else
-            echo "❌ 创建 Release 失败 (HTTP ${HTTP_CODE})"
-            echo "$RESPONSE_BODY"
-            exit 1
-          fi
-
-          # 上传文件作为 Release 附件
-          echo ""
-          echo "📎 上传文件作为 Release 附件..."
-          for file in *.tar.gz *.deb; do
-            [ ! -f "$file" ] && continue
-            echo "  ⬆️  $file"
-
-            # 使用 multipart/form-data 上传附件
-            curl -fsSL -X POST \
-              -H "Authorization: token ${TOKEN}" \
-              -F "attachment=@${file}" \
-              "https://${REGISTRY}/api/v1/repos/${{ gitea.repository }}/releases/${RELEASE_ID}/assets?name=${file}" || {
-              echo "  ⚠️  附件上传失败: $file（可能已存在）"
-            }
-          done
-
-          echo ""
-          echo "✅ Release 创建完成！"
-          echo "🔗 访问: https://${REGISTRY}/${{ gitea.repository }}/releases/tag/${TAG}"

.gitea/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+# 分支推送只做校验和原生构建；tag 发布由 release.yml 独立处理。
+on:
+  push:
+    branches: ["**"]
+
+env:
+  DOCKER_BUILDKIT: "1"
+  BUILDX_NO_DEFAULT_ATTESTATIONS: "1"
+  BUILDKIT_PROGRESS: plain
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest-amd64
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 校验版本和脚本语法
+        run: |
+          VERSION=$(tr -d '\r\n' < VERSION)
+          [[ "${VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          bash -n script/*.sh debian/build-deb.sh
+          sh -n debian/postinst debian/prerm debian/postrm
+          sh -n debian/xxxig-enable-1gb-pages
+
+  build:
+    needs: validate
+    runs-on: ${{ matrix.arch == 'amd64' && 'ubuntu-latest-amd64' || 'ubuntu-latest-arm64' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [amd64, arm64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 准备原生 Buildx
+        run: |
+          BUILDER=$(docker buildx create --use \
+            --driver docker-container \
+            --driver-opt network=host)
+          echo "BUILDER=${BUILDER}" >> "$GITHUB_ENV"
+          docker buildx inspect --bootstrap
+
+      - name: 构建 ${{ matrix.arch }} 二进制
+        run: |
+          VERSION=$(tr -d '\r\n' < VERSION)
+          docker buildx build --pull \
+            --platform "linux/${{ matrix.arch }}" \
+            --build-arg "XXXIG_VERSION=v${VERSION}" \
+            --output type=local,dest=./output \
+            -f docker/Dockerfile .
+
+      - name: 冒烟测试
+        run: |
+          DIR="./output/linux_${{ matrix.arch }}"
+          test -x "${DIR}/xxxigDaemon"
+          test -x "${DIR}/xxxig"
+          test -x "${DIR}/xxxigServer"
+          test -f "${DIR}/config.json"
+          test -f "${DIR}/config_cc.json"
+          "${DIR}/xxxigDaemon" --version
+
+      - name: 验证 Debian 打包
+        run: |
+          VERSION=$(tr -d '\r\n' < VERSION)
+          TARGZ="xxxig-${{ matrix.arch }}-linux-static-${VERSION}.tar.gz"
+          tar -czf "${TARGZ}" -C "./output/linux_${{ matrix.arch }}" .
+          if ! command -v dpkg-deb >/dev/null; then
+            sudo apt-get update
+            sudo apt-get install -y dpkg-dev
+          fi
+          ./debian/build-deb.sh "${{ matrix.arch }}" "${VERSION}" "${TARGZ}"
+          DEB="xxxig_${VERSION}_${{ matrix.arch }}.deb"
+          CONTENTS=$(dpkg-deb --contents "${DEB}")
+          grep -Fq 'usr/libexec/xxxig-enable-1gb-pages' <<<"${CONTENTS}"
+          grep -Fq 'lib/systemd/system/xxxig-hugepages.service' <<<"${CONTENTS}"
+
+      - name: 清理 Buildx
+        if: always()
+        run: docker buildx rm "${BUILDER}" || true

.gitea/workflows/release.yml

@@ -0,0 +1,163 @@
+name: Release
+
+on:
+  push:
+    tags: ["*"]
+
+env:
+  DOCKER_BUILDKIT: "1"
+  BUILDX_NO_DEFAULT_ATTESTATIONS: "1"
+  BUILDKIT_PROGRESS: plain
+  PRODUCT_NAME: xxxig
+
+jobs:
+  build:
+    runs-on: ${{ matrix.arch == 'amd64' && 'ubuntu-latest-amd64' || 'ubuntu-latest-arm64' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [amd64, arm64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 校验 tag 与源码版本
+        env:
+          TAG: ${{ gitea.ref_name }}
+        run: |
+          VERSION=$(tr -d '\r\n' < VERSION)
+          TAG_VERSION="${TAG#v}"
+          [[ "${TAG_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          [ "${TAG_VERSION}" = "${VERSION}" ] || {
+            echo "tag ${TAG_VERSION} 与 VERSION ${VERSION} 不一致"
+            exit 1
+          }
+          echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
+
+      - name: 准备原生 Buildx
+        run: |
+          BUILDER=$(docker buildx create --use \
+            --driver docker-container \
+            --driver-opt network=host)
+          echo "BUILDER=${BUILDER}" >> "$GITHUB_ENV"
+          docker buildx inspect --bootstrap
+
+      - name: 构建 ${{ matrix.arch }} 二进制
+        run: |
+          docker buildx build --pull \
+            --platform "linux/${{ matrix.arch }}" \
+            --build-arg "XXXIG_VERSION=v${VERSION}" \
+            --output type=local,dest=./output \
+            -f docker/Dockerfile .
+
+      - name: 打包并冒烟测试
+        run: |
+          DIR="./output/linux_${{ matrix.arch }}"
+          TARGZ="${PRODUCT_NAME}-${{ matrix.arch }}-linux-static-${VERSION}.tar.gz"
+          test -x "${DIR}/xxxigDaemon"
+          test -x "${DIR}/xxxig"
+          test -x "${DIR}/xxxigServer"
+          tar -czf "${TARGZ}" -C "${DIR}" .
+          TEST_DIR=$(mktemp -d)
+          trap 'rm -rf "${TEST_DIR}"' EXIT
+          tar -xzf "${TARGZ}" -C "${TEST_DIR}"
+          "${TEST_DIR}/xxxigDaemon" --version
+
+      - name: 构建 Debian 包
+        run: |
+          if ! command -v dpkg-deb >/dev/null; then
+            sudo apt-get update
+            sudo apt-get install -y dpkg-dev
+          fi
+          TARGZ="${PRODUCT_NAME}-${{ matrix.arch }}-linux-static-${VERSION}.tar.gz"
+          ./debian/build-deb.sh "${{ matrix.arch }}" "${VERSION}" "${TARGZ}"
+          DEB="${PRODUCT_NAME}_${VERSION}_${{ matrix.arch }}.deb"
+          CONTENTS=$(dpkg-deb --contents "${DEB}")
+          grep -Fq 'usr/libexec/xxxig-enable-1gb-pages' <<<"${CONTENTS}"
+          grep -Fq 'lib/systemd/system/xxxig-hugepages.service' <<<"${CONTENTS}"
+
+      - uses: https://github.com/ChristopherHX/gitea-upload-artifact@v4
+        with:
+          name: packages-${{ matrix.arch }}
+          path: |
+            *.tar.gz
+            *.deb
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: 清理 Buildx
+        if: always()
+        run: docker buildx rm "${BUILDER}" || true
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest-amd64
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: https://github.com/ChristopherHX/gitea-download-artifact@v4
+        with:
+          pattern: packages-*
+          path: ./packages
+          merge-multiple: true
+
+      - name: 校验发布文件并生成校验和
+        env:
+          TAG: ${{ gitea.ref_name }}
+        run: |
+          VERSION=$(tr -d '\r\n' < VERSION)
+          TAG_VERSION="${TAG#v}"
+          [ "${TAG_VERSION}" = "${VERSION}" ]
+          for arch in amd64 arm64; do
+            test -f "packages/${PRODUCT_NAME}-${arch}-linux-static-${VERSION}.tar.gz"
+            test -f "packages/${PRODUCT_NAME}_${VERSION}_${arch}.deb"
+          done
+          (cd packages && sha256sum *.tar.gz *.deb > SHA256SUMS)
+          REGISTRY=$(echo "${{ gitea.server_url }}" | sed 's|https\?://||')
+          echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
+          echo "REGISTRY=${REGISTRY}" >> "$GITHUB_ENV"
+
+      - name: 上传 Generic 和 Debian 软件包
+        env:
+          TOKEN: ${{ secrets.BUILD_TOKEN }}
+        run: |
+          OWNER="${{ gitea.repository_owner }}"
+          for file in packages/*.tar.gz; do
+            name=$(basename "${file}")
+            curl -fsSL -X PUT \
+              -H "Authorization: token ${TOKEN}" \
+              --upload-file "${file}" \
+              "https://${REGISTRY}/api/packages/${OWNER}/generic/${PRODUCT_NAME}/${VERSION}/${name}"
+          done
+          for file in packages/*.deb; do
+            curl -fsSL -X PUT \
+              -H "Authorization: token ${TOKEN}" \
+              --upload-file "${file}" \
+              "https://${REGISTRY}/api/packages/${OWNER}/debian/pool/stable/main/upload"
+          done
+
+      - name: 生成 Release 描述
+        run: |
+          cat > release-notes.md <<EOF
+          ## Release ${VERSION}
+
+          ### Debian/Ubuntu 安装
+
+          \`\`\`bash
+          sudo curl https://${REGISTRY}/api/packages/${{ gitea.repository_owner }}/debian/repository.key -o /etc/apt/keyrings/gitea-${{ gitea.repository_owner }}.asc
+          echo "deb [signed-by=/etc/apt/keyrings/gitea-${{ gitea.repository_owner }}.asc] https://${REGISTRY}/api/packages/${{ gitea.repository_owner }}/debian stable main" | sudo tee /etc/apt/sources.list.d/${{ gitea.repository_owner }}.list
+          sudo apt-get update && sudo apt-get install xxxig
+          \`\`\`
+
+          发布附件包含 amd64、arm64 的 tar.gz、Debian 包和 SHA256SUMS。
+          EOF
+
+      - name: 创建或更新 Release 并上传附件
+        uses: https://gitea.com/actions/gitea-release-action@v1
+        with:
+          token: ${{ secrets.BUILD_TOKEN }}
+          name: Release ${{ gitea.ref_name }}
+          body_path: release-notes.md
+          files: |
+            packages/*.tar.gz
+            packages/*.deb
+            packages/SHA256SUMS

CLAUDE.md

@@ -23,13 +23,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 构建与发布流程（CI）
 
-[.gitea/workflows/ci.yaml](.gitea/workflows/ci.yaml) 是 Gitea Actions 流水线：
+Gitea Actions 拆成两条独立流水线：
 
-1. **build-and-test**（矩阵 `arch=[amd64,arm64]`，跑在对应架构的原生 runner 上）：用 `docker buildx` 按 `docker/Dockerfile` 原生编译 → 打成 tar.gz → 调 `debian/build-deb.sh` 打 .deb → 上传 artifact。
+1. [.gitea/workflows/ci.yml](.gitea/workflows/ci.yml) 仅由分支推送触发：先检查版本号和 shell 语法，再用 amd64、arm64 原生 runner 并行编译、执行严格冒烟测试并验证 DEB 包内容；不上传 artifact。
-2. **release**（仅 tag 触发）：下载 artifact，上传 tar.gz 到 Generic Package Registry、上传 .deb 到 Debian Registry（stable/main），并创建 Gitea Release。
+2. [.gitea/workflows/release.yml](.gitea/workflows/release.yml) 仅由 tag 推送触发：校验 tag 与 [VERSION](VERSION) 一致，双架构原生构建 → tar.gz → DEB → artifact 汇总 → SHA256SUMS → Generic/Debian Registry → Gitea Release。
 
 关键点：
-- 版本号**硬编码**在 ci.yaml 的 `PACKAGE_VERSION: "6.26.0"`（纯数字，符合 Debian 版本规范），发版改这里。**关键分界**：上游源码 git tag 带 `v`（CI 用 `XXXIG_VERSION=v${PACKAGE_VERSION}` 检出 `v6.26.0`），而 tar.gz/deb/registry 路径等包版本一律用数字；release job 用 `VERSION="${TAG#v}"` 归一，install 脚本下载时同样 `${version#v}`。
+- 根目录 [VERSION](VERSION) 是唯一版本来源，内容为不带 `v` 的纯版本号；发布 tag 可带或不带 `v`，但归一后必须与 VERSION 完全一致。上游源码 git tag 带 `v`，CI 构建时自动补回；tar.gz、DEB 和 Registry 路径使用不带 `v` 的版本。
 - 编译选项（`docker/Dockerfile`，musl 全静态）：`-DWITH_CC_CLIENT=ON -DWITH_CC_SERVER=ON -DBUILD_STATIC=ON -DWITH_OPENCL=OFF -DWITH_CUDA=OFF`，即 CPU-only 全静态构建；arm64/arm 在对应架构原生 runner 上编译并设 `-DARM_TARGET=8/7`。
 - **为何用 musl(alpine) 而非 glibc（勿改回 glibc 全静态）**：glibc 的 `getaddrinfo` 依赖运行时 `dlopen` NSS 模块，`-static` 全静态后无法加载，跨 glibc 版本运行时 DNS 解析失败（`errno=EBUSY` → libuv `UV_EBUSY` → `DNS error: "resource busy or locked"`）。musl 的 `getaddrinfo` 自带实现，全静态也能正常解析。曾用的 glibc(ubuntu) 构建线已删除。
 - 架构名映射：`x86_64→amd64`、`aarch64→arm64`。
@@ -40,7 +40,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ```bash
 # 本地编译某架构/发行版的二进制（输出到 ./output/linux_<arch>/）
 docker buildx build --platform linux/amd64 \
-  --build-arg XXXIG_VERSION=v6.26.0 \
+  --build-arg XXXIG_VERSION="v$(cat VERSION)" \
   --output type=local,dest=./output \
   -f docker/Dockerfile .
 

README.md

@@ -30,7 +30,7 @@ sudo bash <(wget --no-check-certificate -qO- 'https://gitea.bcde.io/wangdefa/xxx
 sudo bash <(wget --no-check-certificate -qO- 'https://gitea.bcde.io/wangdefa/xxxig/raw/branch/main/script/install.deb.sh') \
   -o pool.example.com:3333 \
   -w YOUR_WALLET
-  
+
 # 卸载（自动识别安装方式）
 sudo bash <(wget --no-check-certificate -qO- 'https://gitea.bcde.io/wangdefa/xxxig/raw/branch/main/script/uninstall.sh')
 ```
@@ -46,17 +46,17 @@ sudo bash <(wget --no-check-certificate -qO- 'https://gitea.bcde.io/wangdefa/xxx
 
 ## 构建与发布
 
-CI 定义于 [.gitea/workflows/ci.yaml](.gitea/workflows/ci.yaml)：
+Gitea Actions 分为两条流水线：
 
-- **push 到 `main`/`develop`**：矩阵 `arch=[amd64,arm64]`，在原生 runner 上用 Docker（musl 全静态）编译为 tar.gz 并打 `.deb`。
+- [.gitea/workflows/ci.yml](.gitea/workflows/ci.yml)：分支推送时检查版本和 shell 语法，并在 amd64、arm64 原生 runner 上编译、冒烟测试和验证 DEB 包内容。
-- **打 tag**：产物上传到 Generic / Debian 包仓库并创建 Release。
+- [.gitea/workflows/release.yml](.gitea/workflows/release.yml)：tag 推送时构建 tar.gz 和 DEB，生成 `SHA256SUMS`，上传包仓库并创建或更新 Release。
 
 本地构建：
 
 ```bash
 # 编译某架构/发行版二进制（输出到 ./output/linux_<arch>/）
 docker buildx build --platform linux/amd64 \
-  --build-arg XXXIG_VERSION=v6.26.0 \
+  --build-arg XXXIG_VERSION="v$(cat VERSION)" \
   --output type=local,dest=./output \
   -f docker/Dockerfile .
 
@@ -66,10 +66,12 @@ docker buildx build --platform linux/amd64 \
 
 ## 版本号约定
 
-- **上游源码 git tag** 带 `v`（如 `v6.26.0`），CI 用 `XXXIG_VERSION=v${PACKAGE_VERSION}` 检出。
+- 根目录 [VERSION](VERSION) 是唯一版本来源，使用不带 `v` 的版本号。
+- **上游源码 git tag** 带 `v`（如 `v6.26.0`），CI 构建时自动补回。
 - **包版本**（tar.gz / deb / registry 路径）一律用数字（如 `6.26.0`），符合 Debian 版本规范。
+- 发布 tag 可写成 `6.26.0` 或 `v6.26.0`，去掉 `v` 后必须与 VERSION 一致。
 
-发版只需改 ci.yaml 的 `PACKAGE_VERSION`。
+发版时先更新 VERSION 并提交，再创建同版本 tag。
 
 ## 目录结构
 

VERSION

@@ -0,0 +1 @@
+6.26.0