fix(ci): 绑定分支与部署环境并加固 IMAGE_TAG 传递

- dev 仅允许 dev 分支，prod 仅允许 master/main，防止 master 代码进 lpt-dev
- IMAGE_TAG 同时写 GITHUB_ENV/GITEA_ENV 与工作区文件兜底
- 更新部署说明文档

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/deploy.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       environment:
-        description: '部署环境'
+        description: '部署环境（dev 仅允许 dev 分支；prod 仅允许 master/main）'
         required: true
         type: choice
         options:
@@ -20,28 +20,90 @@ jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
     steps:
+      - name: Validate branch ↔ environment
+        run: |
+          set -euo pipefail
+          REF="${{ gitea.ref }}"
+          BRANCH="${REF#refs/heads/}"
+          # tag 触发时拒绝
+          if [[ "$REF" == refs/tags/* ]]; then
+            echo "ERROR: 请从分支触发部署，不要用 tag。当前 ref=$REF"
+            exit 1
+          fi
+          ENV="${{ inputs.environment }}"
+          echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
+          case "$ENV" in
+            prod)
+              case "$BRANCH" in
+                master|main) echo "OK: prod 允许从 $BRANCH 部署" ;;
+                *)
+                  echo "ERROR: prod 只能从 master/main 部署，当前分支是 '$BRANCH'"
+                  echo "请切换到 master 后再 Run workflow，并选择 environment=prod"
+                  exit 1
+                  ;;
+              esac
+              ;;
+            dev)
+              case "$BRANCH" in
+                dev) echo "OK: dev 允许从 $BRANCH 部署" ;;
+                *)
+                  echo "ERROR: dev 只能从 dev 分支部署，当前分支是 '$BRANCH'"
+                  echo "请切换到 dev 后再 Run workflow，并选择 environment=dev"
+                  echo "（禁止用 master 代码部署到 lpt-dev，避免环境错配）"
+                  exit 1
+                  ;;
+              esac
+              ;;
+            *)
+              echo "ERROR: 未知 environment=$ENV"
+              exit 1
+              ;;
+          esac
+
       - name: Checkout code
         run: |
-          git clone $REPO_URL .
-          git checkout ${{ gitea.sha }}
+          set -euo pipefail
+          git clone "$REPO_URL" .
+          git checkout "${{ gitea.sha }}"
 
       - name: Login to Docker Registry
         run: |
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login $REGISTRY -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+          set -euo pipefail
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "$REGISTRY" -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
 
       - name: Build & Push Docker image
         run: |
-          TAG=${{ gitea.sha }}-$(date +%s)
+          set -euo pipefail
+          ENV="${{ inputs.environment }}"
+          if [ "$ENV" = "prod" ]; then
+            BUILD_MODE=production
+          else
+            BUILD_MODE=development
+          fi
+          TAG="${{ gitea.sha }}-$(date +%s)"
+          echo "Building $REGISTRY/$APP:$TAG (BUILD_MODE=$BUILD_MODE, env tag=$ENV)"
           docker build \
-            --build-arg BUILD_MODE=${{ inputs.environment == 'prod' && 'production' || 'development' }} \
-            -t $REGISTRY/$APP:$TAG \
-            -t $REGISTRY/$APP:${{ inputs.environment }} .
-          docker push $REGISTRY/$APP:$TAG
-          docker push $REGISTRY/$APP:${{ inputs.environment }}
-          echo "IMAGE_TAG=$TAG" >> $GITHUB_ENV
+            --build-arg "BUILD_MODE=$BUILD_MODE" \
+            -t "$REGISTRY/$APP:$TAG" \
+            -t "$REGISTRY/$APP:$ENV" .
+          docker push "$REGISTRY/$APP:$TAG"
+          docker push "$REGISTRY/$APP:$ENV"
+          # 持久化 TAG：兼容 Gitea / GitHub Actions；文件兜底避免 env 文件不支持
+          if [ -n "${GITHUB_ENV:-}" ]; then
+            echo "IMAGE_TAG=$TAG" >> "$GITHUB_ENV"
+          fi
+          if [ -n "${GITEA_ENV:-}" ]; then
+            echo "IMAGE_TAG=$TAG" >> "$GITEA_ENV"
+          fi
+          echo "$TAG" > image_tag.txt
+          if [ -n "${{ runner.temp }}" ]; then
+            echo "$TAG" > "${{ runner.temp }}/image_tag.txt" || true
+          fi
+          echo "IMAGE_TAG=$TAG"
 
       - name: Setup kubectl
         run: |
+          set -euo pipefail
           curl -sLO "https://dl.k8s.io/release/v1.30.0/bin/linux/amd64/kubectl"
           chmod +x kubectl
           mv kubectl /usr/local/bin/
@@ -49,39 +111,62 @@ jobs:
 
       - name: Create/Update imagePullSecret
         run: |
+          set -euo pipefail
           kubectl --kubeconfig=/tmp/kubeconfig create secret docker-registry regcred \
-            --docker-server=$REGISTRY \
+            --docker-server="$REGISTRY" \
             --docker-username="${{ secrets.REGISTRY_USERNAME }}" \
             --docker-password="${{ secrets.REGISTRY_PASSWORD }}" \
-            -n lpt-${{ inputs.environment }} \
+            -n "lpt-${{ inputs.environment }}" \
             --dry-run=client -o yaml | kubectl --kubeconfig=/tmp/kubeconfig apply -f -
 
       - name: Deploy to K8s
         run: |
-          kubectl --kubeconfig=/tmp/kubeconfig set image deployment/$APP $APP=$REGISTRY/$APP:$IMAGE_TAG -n lpt-${{ inputs.environment }} --record
-          kubectl --kubeconfig=/tmp/kubeconfig rollout status deployment/$APP -n lpt-${{ inputs.environment }} --timeout=5m
+          set -euo pipefail
+          ENV="${{ inputs.environment }}"
+          IMAGE_TAG="${IMAGE_TAG:-}"
+          if [ -z "$IMAGE_TAG" ] && [ -f image_tag.txt ]; then
+            IMAGE_TAG="$(cat image_tag.txt)"
+          fi
+          if [ -z "$IMAGE_TAG" ] && [ -f "${{ runner.temp }}/image_tag.txt" ]; then
+            IMAGE_TAG="$(cat "${{ runner.temp }}/image_tag.txt")"
+          fi
+          if [ -z "$IMAGE_TAG" ]; then
+            echo "ERROR: IMAGE_TAG 为空，无法部署"
+            exit 1
+          fi
+          echo "Deploying $REGISTRY/$APP:$IMAGE_TAG -> namespace lpt-$ENV"
+          kubectl --kubeconfig=/tmp/kubeconfig set image "deployment/$APP" \
+            "$APP=$REGISTRY/$APP:$IMAGE_TAG" \
+            -n "lpt-$ENV" --record
+          kubectl --kubeconfig=/tmp/kubeconfig rollout status "deployment/$APP" \
+            -n "lpt-$ENV" --timeout=5m
 
       - name: Debug on failure
         if: failure()
         run: |
+          ENV="${{ inputs.environment }}"
           echo "=== Deployment Status ==="
-          kubectl --kubeconfig=/tmp/kubeconfig get deployment $APP -n lpt-${{ inputs.environment }}
+          kubectl --kubeconfig=/tmp/kubeconfig get deployment "$APP" -n "lpt-$ENV" || true
           echo ""
           echo "=== Pod Status ==="
-          kubectl --kubeconfig=/tmp/kubeconfig get pods -n lpt-${{ inputs.environment }} -l app=$APP
+          kubectl --kubeconfig=/tmp/kubeconfig get pods -n "lpt-$ENV" -l "app=$APP" || true
           echo ""
           echo "=== Recent Events ==="
-          kubectl --kubeconfig=/tmp/kubeconfig get events -n lpt-${{ inputs.environment }} --sort-by='.lastTimestamp' | tail -20
+          kubectl --kubeconfig=/tmp/kubeconfig get events -n "lpt-$ENV" --sort-by='.lastTimestamp' | tail -20 || true
           echo ""
           echo "=== Pod Describe (latest) ==="
-          POD=$(kubectl --kubeconfig=/tmp/kubeconfig get pods -n lpt-${{ inputs.environment }} -l app=$APP --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')
-          kubectl --kubeconfig=/tmp/kubeconfig describe pod $POD -n lpt-${{ inputs.environment }} || true
-          echo ""
-          echo "=== Pod Logs (latest) ==="
-          kubectl --kubeconfig=/tmp/kubeconfig logs $POD -n lpt-${{ inputs.environment }} --tail=50 || true
+          POD=$(kubectl --kubeconfig=/tmp/kubeconfig get pods -n "lpt-$ENV" -l "app=$APP" --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}' 2>/dev/null || true)
+          if [ -n "${POD:-}" ]; then
+            kubectl --kubeconfig=/tmp/kubeconfig describe pod "$POD" -n "lpt-$ENV" || true
+            echo ""
+            echo "=== Pod Logs (latest) ==="
+            kubectl --kubeconfig=/tmp/kubeconfig logs "$POD" -n "lpt-$ENV" --tail=50 || true
+          fi
 
       - name: Rollback on failure
         if: failure()
         run: |
-          kubectl --kubeconfig=/tmp/kubeconfig rollout undo deployment/$APP -n lpt-${{ inputs.environment }}
-          kubectl --kubeconfig=/tmp/kubeconfig rollout status deployment/$APP -n lpt-${{ inputs.environment }}
+          set -euo pipefail
+          ENV="${{ inputs.environment }}"
+          kubectl --kubeconfig=/tmp/kubeconfig rollout undo "deployment/$APP" -n "lpt-$ENV" || true
+          kubectl --kubeconfig=/tmp/kubeconfig rollout status "deployment/$APP" -n "lpt-$ENV" || true