fix(ci): 限制仅 main 部署并加固 IMAGE_TAG 传递

- lpt-ai 仅 main/master 可部署；dev/prod 靠 environment 区分 namespace
- IMAGE_TAG 写 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: '部署环境（本仓库仅 main 分支；dev/prod 均从 main 部署）'
         required: true
         type: choice
         options:
@@ -20,25 +20,70 @@ jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
     steps:
+      - name: Validate branch ↔ environment
+        run: |
+          set -euo pipefail
+          REF="${{ gitea.ref }}"
+          BRANCH="${REF#refs/heads/}"
+          if [[ "$REF" == refs/tags/* ]]; then
+            echo "ERROR: 请从分支触发部署，不要用 tag。当前 ref=$REF"
+            exit 1
+          fi
+          ENV="${{ inputs.environment }}"
+          echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
+          # lpt-ai 仅维护 main：dev/prod 都从 main 出包，靠 environment 区分 namespace/镜像 tag
+          case "$BRANCH" in
+            main|master)
+              echo "OK: lpt-ai 从 $BRANCH 部署到 $ENV"
+              ;;
+            *)
+              echo "ERROR: lpt-ai 只能从 main/master 部署，当前分支是 '$BRANCH'"
+              exit 1
+              ;;
+          esac
+          case "$ENV" in
+            dev|prod) ;;
+            *)
+              echo "ERROR: 未知 environment=$ENV"
+              exit 1
+              ;;
+          esac
+
       - name: Checkout code
         run: |
-          git clone $REPO_URL .
+          set -euo pipefail
-          git checkout ${{ gitea.sha }}
+          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
-          docker build -t $REGISTRY/$APP:$TAG -t $REGISTRY/$APP:${{ inputs.environment }} .
+          ENV="${{ inputs.environment }}"
-          docker push $REGISTRY/$APP:$TAG
+          TAG="${{ gitea.sha }}-$(date +%s)"
-          docker push $REGISTRY/$APP:${{ inputs.environment }}
+          echo "Building $REGISTRY/$APP:$TAG (env tag=$ENV)"
-          echo "IMAGE_TAG=$TAG" >> $GITHUB_ENV
+          docker build -t "$REGISTRY/$APP:$TAG" -t "$REGISTRY/$APP:$ENV" .
+          docker push "$REGISTRY/$APP:$TAG"
+          docker push "$REGISTRY/$APP:$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/
@@ -47,39 +92,62 @@ jobs:
 
       - name: Create/Update imagePullSecret
         run: |
+          set -euo pipefail
           kubectl 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 apply -f -
 
       - name: Deploy to K8s
         run: |
-          kubectl set image deployment/$APP $APP=$REGISTRY/$APP:$IMAGE_TAG -n lpt-${{ inputs.environment }} --record
+          set -euo pipefail
-          kubectl rollout status deployment/$APP -n lpt-${{ inputs.environment }} --timeout=5m
+          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 set image "deployment/$APP" \
+            "$APP=$REGISTRY/$APP:$IMAGE_TAG" \
+            -n "lpt-$ENV" --record
+          kubectl rollout status "deployment/$APP" \
+            -n "lpt-$ENV" --timeout=5m
 
       - name: Debug on failure
         if: failure()
         run: |
+          ENV="${{ inputs.environment }}"
           echo "=== Deployment Status ==="
-          kubectl get deployment $APP -n lpt-${{ inputs.environment }}
+          kubectl get deployment "$APP" -n "lpt-$ENV" || true
           echo ""
           echo "=== Pod Status ==="
-          kubectl get pods -n lpt-${{ inputs.environment }} -l app=$APP
+          kubectl get pods -n "lpt-$ENV" -l "app=$APP" || true
           echo ""
           echo "=== Recent Events ==="
-          kubectl get events -n lpt-${{ inputs.environment }} --sort-by='.lastTimestamp' | tail -20
+          kubectl get events -n "lpt-$ENV" --sort-by='.lastTimestamp' | tail -20 || true
           echo ""
           echo "=== Pod Describe (latest) ==="
-          POD=$(kubectl get pods -n lpt-${{ inputs.environment }} -l app=$APP --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')
+          POD=$(kubectl get pods -n "lpt-$ENV" -l "app=$APP" --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}' 2>/dev/null || true)
-          kubectl describe pod $POD -n lpt-${{ inputs.environment }} || true
+          if [ -n "${POD:-}" ]; then
-          echo ""
+            kubectl describe pod "$POD" -n "lpt-$ENV" || true
-          echo "=== Pod Logs (latest) ==="
+            echo ""
-          kubectl logs $POD -n lpt-${{ inputs.environment }} --tail=50 || true
+            echo "=== Pod Logs (latest) ==="
+            kubectl logs "$POD" -n "lpt-$ENV" --tail=50 || true
+          fi
 
       - name: Rollback on failure
         if: failure()
         run: |
-          kubectl rollout undo deployment/$APP -n lpt-${{ inputs.environment }}
+          set -euo pipefail
-          kubectl rollout status deployment/$APP -n lpt-${{ inputs.environment }}
+          ENV="${{ inputs.environment }}"
+          kubectl rollout undo "deployment/$APP" -n "lpt-$ENV" || true
+          kubectl rollout status "deployment/$APP" -n "lpt-$ENV" || true

k8s/README.md

@@ -0,0 +1,131 @@
+# Kubernetes Configuration for LPT Project
+
+This directory contains the shared Kubernetes configuration files for the LPT (Learning Progress Tracker) project.
+
+## Files
+
+### ConfigMap
+- **`configmap.yaml`** - Shared environment variables for all services
+  - LLM API configuration (URL, model, timeout)
+  - Database connection string
+  - Service URLs
+
+### Secrets (Templates)
+- **`lpt-secrets.yaml`** - Application secrets template
+  - LLM API key
+  - MySQL root password
+  - **⚠️ DO NOT commit real secrets!** Use the template to create secrets manually.
+
+- **`regcred-secret.yaml`** - Docker registry authentication template
+  - Used for pulling images from private registry (192.168.123.199:5000)
+  - **⚠️ Managed by Gitea Actions workflow** - DO NOT commit real credentials!
+
+### Service-Specific Configurations
+Each service has its own `k8s/` directory with deployment and service configs:
+- **`lpt-fe/k8s/`** - Frontend deployment (Nginx + Vue 3)
+- **`lpt-be/k8s/`** - Backend deployment (Spring Boot)
+- **`lpt-ai/k8s/`** - AI service deployment (Python FastAPI)
+
+## Deployment
+
+### Initial Setup
+
+1. **Create namespace**:
+   ```bash
+   kubectl create namespace lpt-dev
+   ```
+
+2. **Apply shared ConfigMap**:
+   ```bash
+   kubectl apply -f k8s/configmap.yaml
+   ```
+
+3. **Create secrets** (replace with actual values):
+   ```bash
+   # Application secrets
+   kubectl create secret generic lpt-secrets \
+     --from-literal=llm-api-key=<YOUR_LLM_API_KEY> \
+     --from-literal=mysql-root-password=<YOUR_MYSQL_ROOT_PASSWORD> \
+     --namespace=lpt-dev
+
+   # Registry credentials (for manual creation, or use Gitea workflow)
+   kubectl create secret docker-registry regcred \
+     --docker-server=192.168.123.199:5000 \
+     --docker-username=admin \
+     --docker-password=<REGISTRY_PASSWORD> \
+     --namespace=lpt-dev
+   ```
+
+4. **Deploy services**:
+   ```bash
+   # Frontend
+   kubectl apply -f lpt-fe/k8s/
+
+   # Backend
+   kubectl apply -f lpt-be/k8s/
+
+   # AI Service
+   kubectl apply -f lpt-ai/k8s/
+   ```
+
+### CI/CD Workflow
+
+The Gitea Actions workflows (`.gitea/workflows/deploy.yml` in each service) automatically:
+1. Build Docker images
+2. Push to private registry (192.168.123.199:5000)
+3. Create/update `regcred` secret with credentials from Gitea secrets
+4. Update deployment image tags
+
+**Required Gitea Secrets** (per repository):
+- `REGISTRY_USERNAME`: Docker registry username (admin)
+- `REGISTRY_PASSWORD`: Docker registry password
+
+## Verification
+
+Check deployment status:
+```bash
+kubectl get all -n lpt-dev
+kubectl get configmap -n lpt-dev
+kubectl get secret -n lpt-dev
+```
+
+View logs:
+```bash
+kubectl logs -f deployment/lpt-fe -n lpt-dev
+kubectl logs -f deployment/lpt-be -n lpt-dev
+kubectl logs -f deployment/lpt-ai -n lpt-dev
+```
+
+## Architecture
+
+```
+┌─────────────────┐
+│   lpt-fe:3000   │ (NodePort 30080)
+│   Vue 3 + Nginx │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   lpt-be:8080   │ (NodePort 30088)
+│   Spring Boot   │
+└────────┬────────┘
+         │
+         ├─────────► MySQL (external)
+         │
+         ▼
+┌─────────────────┐
+│  lpt-ai:5199    │ (ClusterIP)
+│  FastAPI        │
+└─────────────────┘
+         │
+         ▼
+   LLM API (external)
+```
+
+## Notes
+
+- **Namespace**: All resources use `lpt-dev` namespace
+- **Registry**: Private Docker registry at `192.168.123.199:5000`
+- **Image Pull**: All deployments use `imagePullSecrets: [name: regcred]`
+- **ConfigMap**: Shared config is mounted as environment variables
+- **Secrets**: Sensitive data (API keys, passwords) stored in `lpt-secrets`

k8s/configmap.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: lpt-config
+  namespace: lpt-dev
+data:
+  # LPT AI Service
+  LLM_API_URL: https://api.siliconflow.cn/v1/chat/completions
+  LLM_MODEL: Qwen/Qwen2.5-32B-Instruct
+  LLM_TIMEOUT_MS: "60000"
+  LPT_AI-SERVICE_URL: http://lpt-ai:5199
+  PORT: "5199"
+
+  # Spring Boot Database
+  SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/learning_progress_tracker?allowPublicKeyRetrieval=true&characterEncoding=utf-8&useSSL=false&serverTimezone=GMT%2B8

k8s/lpt-secrets.yaml

@@ -0,0 +1,33 @@
+# LPT Application Secrets
+#
+# This file is a TEMPLATE - DO NOT commit real secrets to git!
+#
+# To create this secret:
+# kubectl create secret generic lpt-secrets \
+#   --from-literal=llm-api-key=<YOUR_LLM_API_KEY> \
+#   --from-literal=mysql-root-password=<YOUR_MYSQL_ROOT_PASSWORD> \
+#   --namespace=lpt-dev
+#
+# Or use kubectl apply with stringData:
+# kubectl apply -f - <<EOF
+# apiVersion: v1
+# kind: Secret
+# metadata:
+#   name: lpt-secrets
+#   namespace: lpt-dev
+# type: Opaque
+# stringData:
+#   llm-api-key: "your-actual-api-key"
+#   mysql-root-password: "your-actual-mysql-password"
+# EOF
+
+apiVersion: v1
+kind: Secret
+metadata:
+  name: lpt-secrets
+  namespace: lpt-dev
+type: Opaque
+data:
+  # Base64 encoded values - use stringData for plain text when applying
+  # llm-api-key: <base64-encoded-api-key>
+  # mysql-root-password: <base64-encoded-password>

k8s/regcred-secret.yaml

@@ -0,0 +1,26 @@
+# Docker Registry Secret for pulling images from private registry
+#
+# This file is a TEMPLATE - the actual secret is managed by Gitea Actions workflow
+# and should NOT be committed with real credentials.
+#
+# To create this secret manually:
+# kubectl create secret docker-registry regcred \
+#   --docker-server=192.168.123.199:5000 \
+#   --docker-username=admin \
+#   --docker-password=<REGISTRY_PASSWORD> \
+#   --namespace=lpt-dev
+#
+# Or use the workflow which reads from Gitea secrets:
+# - REGISTRY_USERNAME
+# - REGISTRY_PASSWORD
+
+apiVersion: v1
+kind: Secret
+metadata:
+  name: regcred
+  namespace: lpt-dev
+type: kubernetes.io/dockerconfigjson
+data:
+  # .dockerconfigjson: <base64-encoded-docker-config>
+  # This is generated by the workflow - DO NOT commit real values here
+  .dockerconfigjson: ""