fix: 流水线kubeconfig改用临时目录

- dev 仅允许 dev 分支，prod 仅允许 master/main
- IMAGE_TAG 写 env 文件 + image_tag.txt 兜底
- checkout 时确保 maven 容器内安装 git

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

.gitea/workflows/deploy.yml

@@ -0,0 +1,152 @@
+name: lpt-be Build & Deploy
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: '部署环境（dev 仅允许 dev 分支；prod 仅允许 master/main）'
+        required: true
+        type: choice
+        options:
+          - dev
+          - prod
+
+env:
+  REGISTRY: 192.168.123.199:5000
+  APP: lpt-be
+  REPO_URL: http://git.cat-shark.xyz/cat-shark/lpt-be.git
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    env:
+      KUBECONFIG: /tmp/kubeconfig
+    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 }}"
+          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: |
+          set -euo pipefail
+          git clone "$REPO_URL" .
+          git checkout "${{ gitea.sha }}"
+
+      - name: Login to Docker Registry
+        run: |
+          set -euo pipefail
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "$REGISTRY" -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+
+      - name: Build & Push Docker image
+        run: |
+          set -euo pipefail
+          ENV="${{ inputs.environment }}"
+          TAG="${{ gitea.sha }}-$(date +%s)"
+          echo "Building $REGISTRY/$APP:$TAG (env tag=$ENV)"
+          docker build -t "$REGISTRY/$APP:$TAG" -t "$REGISTRY/$APP:$ENV" .
+          docker push "$REGISTRY/$APP:$TAG"
+          docker push "$REGISTRY/$APP:$ENV"
+          echo "IMAGE_TAG=$TAG"
+          echo "$TAG" > image_tag.txt
+          mkdir -p /tmp/lpt-ci
+          echo "$TAG" > /tmp/lpt-ci/image_tag.txt
+
+      - 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/
+          echo "${{ secrets.KUBECONFIG_B64 }}" | base64 -d > /tmp/kubeconfig
+          chmod 600 /tmp/kubeconfig
+
+      - name: Create/Update imagePullSecret
+        run: |
+          set -euo pipefail
+          kubectl create secret docker-registry regcred \
+            --docker-server="$REGISTRY" \
+            --docker-username="${{ secrets.REGISTRY_USERNAME }}" \
+            --docker-password="${{ secrets.REGISTRY_PASSWORD }}" \
+            -n "lpt-${{ inputs.environment }}" \
+            --dry-run=client -o yaml | kubectl apply -f -
+
+      - name: Deploy to K8s
+        run: |
+          set -euo pipefail
+          ENV="${{ inputs.environment }}"
+          IMAGE_TAG="$(cat image_tag.txt 2>/dev/null || cat /tmp/lpt-ci/image_tag.txt 2>/dev/null || echo '')"
+          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-$ENV" || true
+          echo ""
+          echo "=== Pod Status ==="
+          kubectl get pods -n "lpt-$ENV" -l "app=$APP" || true
+          echo ""
+          echo "=== Recent Events ==="
+          kubectl get events -n "lpt-$ENV" --sort-by='.lastTimestamp' | tail -20 || true
+          echo ""
+          echo "=== Pod Describe (latest) ==="
+          POD=$(kubectl 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 describe pod "$POD" -n "lpt-$ENV" || true
+            echo ""
+            echo "=== Pod Logs (latest) ==="
+            kubectl logs "$POD" -n "lpt-$ENV" --tail=50 || true
+          fi
+
+      - name: Rollback on failure
+        if: failure()
+        run: |
+          set -euo pipefail
+          ENV="${{ inputs.environment }}"
+          kubectl rollout undo "deployment/$APP" -n "lpt-$ENV" || true
+          kubectl rollout status "deployment/$APP" -n "lpt-$ENV" || true

AGENTS.md

@@ -1,4 +1,132 @@
-# 项目规范
+# LPT 后端服务（lpt-be）
+
+> Java Spring Boot 后端，提供 REST API、数据库访问、认证鉴权。
+
+## Git 提交规范
+
+- 提交信息必须简短且使用中文，不要使用英文长句。
+- 格式：`类型: 简述`，例如 `feat: 新增用户登录接口`、`fix: 修复多租户拦截器空指针`、`docs: 补充API文档`。
+
+## 技术栈
+
+- Java 17
+- 框架：Spring Boot 3.2.5
+- ORM：MyBatis-Plus 3.5.5
+- 数据库：MySQL 8.0
+- 认证：Sa-Token 1.38.0，Cookie 名 `satoken`
+- 数据库迁移：Flyway
+- 对象映射：MapStruct 1.5.5
+- 连接池：Druid 1.2.8
+- 密码加密：jBCrypt 0.4
+- API 文档：Knife4j (OpenAPI 3)
+- Lombok（@Data, @Slf4j）
+
+## 项目结构
+
+```text
+lpt-be/src/main/java/com/guo/learningprogresstracker/
+├── controller/   → REST 接口层
+├── service/      → 业务逻辑层（接口 + impl）
+├── mapper/       → MyBatis-Plus BaseMapper
+├── entity/       → 数据库实体
+├── dto/          → 请求/响应 DTO
+├── config/       → Spring 配置
+├── common/       → 全局异常处理、Ops
+├── mapStruct/    → MapStruct Converter
+├── enums/        → 枚举类
+├── exception/    → 自定义异常
+└── utils/        → 工具类
+```
+
+- controller 只做参数校验和路由。
+- service/impl 承载业务逻辑。
+- mapper 使用 MyBatis-Plus BaseMapper。
+- entity 使用 `@TableName`、`@TableField` 映射数据库字段。
+- mapStruct 承载 DTO 转换。
+
+## API 端点总览（32 个）
+
+| 模块 | 端点数 | 端点 |
+|------|--------|------|
+| 学习会话 | 9 | `POST /study-sessions/{taskNum}/start`, `PUT .../pause`, `PUT .../resume`, `PUT .../end`, `POST .../fragments`, `GET .../history`, `PUT .../expectation`, `GET .../expectation`, `GET .../report-draft` |
+| 标准思维导图 | 6 | `GET /review/standard-mind-map/{taskNum}`, `POST .../regenerate`, `PUT ...`, `POST .../recall`, `POST .../find-node`, `GET .../recall-records` |
+| 复习模块 | 6 | `GET /review/feed`, `GET /review/task/{taskNum}`, `GET /review/report/{id}`, `GET /review/fragment/{id}`, `GET /review/standard-mind-map/recall-records/{recordId}`, `GET /review/tasks` |
+| 任务管理 | 6 | `GET /tasks`, `POST /tasks`, `PUT /tasks/{taskNum}`, `DELETE /tasks/{taskNum}`, `GET /tasks/priority-weights`, `PUT /tasks/priority-weights` |
+| 应用场景 | 4 | `GET/POST/PUT/DELETE /tasks/{taskNum}/applications[/{id}]` |
+| 工具 | 1 | `GET /utils/fetch-title?url=...` |
+
+## 数据库（10 个核心表）
+
+`users`, `tasks`, `study_sessions`, `study_reports`, `study_report_fragments`, `study_expectations`, `task_applications`, `review_standard_mind_maps`, `review_recall_records`, `user_priority_weights`
+
+## 关键机制
+
+- 多租户隔离：`TenantLineInnerInterceptor` 自动注入 `WHERE created_by = #{当前用户}`，排除 `user`/`flyway_schema_history` 表。
+- 自动填充：`MetaObjectHandler` 自动填充 `created_by`/`updated_by`/`created_time`/`updated_time`。
+- 认证鉴权：Sa-Token 拦截 `/**` 排除 `/login`，Cookie `satoken`，支持 `@SaCheckPermission` 注解式权限。
+- 响应格式：`CommonResult<T>` 统一包装 `{ code, message, data }`。
+- CORS：可配置，local profile 允许所有来源。
+
+## 响应规范
+
+- 成功：`CommonResult.success(data)`，code=200。
+- 业务错误：`CommonResult.error(msg)`，code=400，HTTP 200。
+- 未登录：`GlobalExceptionHandler.handleNotLogin()`，HTTP 401 + code=401。
+- 参数校验失败：`MethodArgumentNotValidException`，code=400。
+
+## DTO 转换
+
+- MapStruct 编译期生成 `*ConvertImpl.java`，同名属性自动映射。
+- 默认 `unmappedTargetPolicy = IGNORE`。
+- 自定义映射使用 `@Mapping(source, target)`。
+- 增删 DTO 字段后必须重新编译，否则生成代码不含新字段。
+
+## CORS
+
+- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins`。
+- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`，兼容 `allowCredentials`。
+
+## 标题抓取
+
+- `TitleFetcher`：静态工具类，支持 HTTP→HTTPS 重定向和宽松 SSL。
+- `UtilsController`：`GET /utils/fetch-title?url=...` 代理端点。
+
+## 运行环境
+
+- 默认 profile：local（`application.yml` 中 `spring.profiles.active: local`）。
+- 编译命令：`mvn clean compile -DskipTests`，需要 JDK 17。
+
+## 配置文件
+
+| Profile | 文件 |
+|---------|------|
+| local | `application-local.yml` |
+| dev | `application-dev.yml` |
+| uat | `application-uat.yml` |
+| prod | `application-prod.yml` |
+| 公共 | `application.yml` |
+
+## AI 服务依赖
+
+- 配置：`lpt.ai-service.url=http://localhost:5199`
+- 超时：600s
+- AI 服务不可用时自动降级到内置规则引擎（`BuiltinMindMapGenerator`）
+
+## 启动命令
+
+```bash
+mvn clean compile -DskipTests   # 编译（需要 JDK 17）
+mvn spring-boot:run              # 启动（默认 profile: local）
+```
+
+## 关联项目
+
+| 项目 | 路径 | 端口 | 说明 |
+|------|------|------|------|
+| lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端，通过 `/api` 代理调用本服务 |
+| lpt-ai | `../lpt-ai/` | 5199 | AI 服务，本服务通过 HTTP 调用其异步任务接口 |
+
+## 项目规范
 
 ## 数据库迁移（Flyway Migration）
 

CLAUDE.md

@@ -1,63 +0,0 @@
-# LPT 后端规范
-
-## 技术栈
-- Java 17, Spring Boot 3.2.5
-- MyBatis-Plus 3.5.5 + MySQL
-- MapStruct 1.5.5（编译期生成代码，DTO 增删字段后需重新编译）
-- Sa-Token 1.38.0（认证/鉴权）
-- Flyway（数据库迁移）
-- Lombok（@Data, @Slf4j）
-
-## 项目结构
-```
-controller/   → REST 接口，只做参数校验和路由
-service/      → 业务逻辑
-  impl/
-mapper/       → MyBatis-Plus BaseMapper
-entity/       → 数据库实体（@TableName, @TableField）
-dto/          → 请求/响应 DTO
-  request/
-  response/
-config/       → Spring 配置（WebMvcConfig, JacksonConfig 等）
-utils/        → 工具类
-common/       → GlobalExceptionHandler, Ops 等
-mapStruct/    → MapStruct Converter 接口
-```
-
-## 响应规范
-- 统一使用 `CommonResult<T>` 包装：`{ code, message, data }`
-- 成功：`CommonResult.success(data)` → code=200
-- 业务错误：`CommonResult.error(msg)` → code=400, HTTP 200
-- 未登录：`GlobalExceptionHandler.handleNotLogin()` → HTTP 401 + code=401
-- 参数校验失败走 `MethodArgumentNotValidException` → code=400
-
-## 认证
-- SaInterceptor 注册在 `WebMvcConfig`（无 @Profile 限制，所有环境生效）
-- 拦截 `/**`，排除 `/login`
-- `StpUtil.checkLogin()` 失败 → NotLoginException → GlobalExceptionHandler → 401
-- Cookie 名 `satoken`，前端 axios 需 `withCredentials: true`
-
-## 数据库变更
-- Flyway 迁移文件：`src/main/resources/db/migration/V{日期}_{序号}__{描述}.sql`
-- 文件名日期格式：`yyyyMMdd`
-
-## DTO 转换
-- MapStruct 编译期生成 `*ConvertImpl.java`（target/generated-sources/）
-- 同名属性自动映射，`unmappedTargetPolicy = IGNORE`
-- 如需自定义映射用 `@Mapping(source, target)`
-- **增删 DTO 字段后必须重新编译**，否则 MapStruct 生成代码不含新字段
-
-## CORS
-- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins` 配置
-- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`（兼容 allowCredentials）
-- local profile：`allow-credentials: true`, `allowed-origins: '*'`
-
-## 标题抓取
-- `TitleFetcher`：静态工具类，支持手动跟随 HTTP→HTTPS 重定向、宽松 SSL
-- `UtilsController`：`GET /utils/fetch-title?url=...` 代理端点
-
-## 运行
-- 默认 profile：local（application.yml 中 `spring.profiles.active: local`）
-- IDEA JDK：`C:/Users/cat-win/.jdks/ms-17.0.19`
-- Maven：IDEA 内置 `C:/Program Files/JetBrains/IntelliJ IDEA 2026.1.3/plugins/maven/lib/maven3/bin/mvn`
-- 编译：`mvn clean compile -DskipTests`（须用 JDK 17）

Dockerfile

@@ -1,17 +1,24 @@
-# 使用官方 OpenJDK 作为基础镜像
+# Stage 1: Maven 构建（Docker 层缓存自动缓存依赖）
-FROM eclipse-temurin:17-jre
+FROM maven:3.9-eclipse-temurin-17 AS builder
-
-# 设置工作目录
 WORKDIR /app
 
-# 拷贝打包好的 JAR 文件到容器
+# 先复制 pom.xml，单独一层 —— 只要依赖不变，这层就被缓存
-COPY target/LPT.jar LPT.jar
+COPY pom.xml .
+RUN mvn dependency:go-offline -B -q
+
+# 再复制源码构建
+COPY src/ ./src/
+RUN mvn package -DskipTests -B -q
+
+# Stage 2: 运行时（精简 JRE）
+FROM eclipse-temurin:17-jre
+WORKDIR /app
+
+COPY --from=builder /app/target/LPT.jar LPT.jar
 
-# 暴露应用运行的端口
 EXPOSE 8888
 
-# 启动应用
 ENTRYPOINT ["java", "-jar", "LPT.jar"]
 
-# 健康检查
+HEALTHCHECK --interval=10s --timeout=5s \
-HEALTHCHECK --interval=10s --timeout=5s CMD curl --fail http://localhost:8888/actuator/health || exit 1
+  CMD curl --fail http://localhost:8888/actuator/health || exit 1

Jenkinsfile

@@ -1,78 +0,0 @@
-pipeline {
-    agent none  // 全局不指定，局部自己声明
-    environment {
-        IMAGE_NAME = 'lpt-prod:0.0'
-        CONTAINER_NAME = 'LPT-prod'
-        CONTAINER_PORT = '8888'
-    }
-    stages {
-        stage('Build') {
-            agent {
-                docker {
-                    image 'maven:3.9.6-eclipse-temurin-17'
-                    args '-v /root/.m2:/root/.m2'
-                }
-            }
-            steps {
-                sh 'mvn -B -DskipTests clean package'
-            }
-        }
-
-        stage('Build Docker Image') {
-            agent any  // 使用 Jenkins 默认节点（宿主机），前提是宿主有 docker 命令
-            steps {
-                sh 'docker build -t $IMAGE_NAME .'
-            }
-        }
-
-        stage('Run Docker Container') {
-            agent any
-            steps {
-                sh '''
-                  docker network create traefik-public || true
-                  docker rm -f $CONTAINER_NAME || true
-                  docker run -d --name $CONTAINER_NAME --network mysql-prod_mysql-prod \\
-                  --restart=always \\
-                   -e SPRING_PROFILES_ACTIVE=prod \\
-                      --label "traefik.enable=true" \\
-                      --label "traefik.docker.network=traefik-public" \\
-                      --label 'traefik.http.routers.lpt-api.rule=Host(`lpt.cat-shark.xyz`) && PathPrefix(`/api`)' \\
-                      --label "traefik.http.routers.lpt-api.entrypoints=websecure" \\
-                      --label "traefik.http.routers.lpt-api.tls.certresolver=le" \\
-                      --label "traefik.http.routers.lpt-api.priority=100" \\
-                      --label "traefik.http.routers.lpt-api.service=lpt-api" \\
-                      --label "traefik.http.routers.lpt-api.middlewares=lpt-api-strip" \\
-                      --label "traefik.http.middlewares.lpt-api-strip.stripprefix.prefixes=/api" \\
-                      --label "traefik.http.services.lpt-api.loadbalancer.server.port=$CONTAINER_PORT" \\
-                      --log-driver=loki \\
-                      --log-opt loki-url="http://192.168.123.199:3100/loki/api/v1/push" \\
-                   $IMAGE_NAME
-                  docker network connect traefik-public $CONTAINER_NAME || true
-                '''
-            }
-        }
-
-        stage('Check Docker Status') {
-            agent any
-            steps {
-                script {
-                    def lastStatus = ''
-                    timeout(time: 60, unit: 'SECONDS') {
-                        waitUntil {
-                            def status = sh(
-                                    script: "docker inspect -f '{{.State.Health.Status}}' $CONTAINER_NAME || echo 'unhealthy'",
-                                    returnStdout: true
-                            ).trim()
-
-                            if (status != lastStatus) {
-                                echo "Container health: ${status}"
-                                lastStatus = status
-                            }
-                            return (status == 'healthy')
-                        }
-                    }
-                }
-            }
-        }
-    }
-}

Jenkinsfile-dev

@@ -1,78 +0,0 @@
-pipeline {
-    agent none  // 全局不指定，局部自己声明
-    environment {
-        IMAGE_NAME = 'lpt-dev:0.0'
-        CONTAINER_NAME = 'LPT-dev'
-        CONTAINER_PORT = '8888'
-    }
-    stages {
-        stage('Build') {
-            agent {
-                docker {
-                    image 'maven:3.9.6-eclipse-temurin-17'
-                    args '-v /root/.m2:/root/.m2'
-                }
-            }
-            steps {
-                sh 'mvn -B -DskipTests clean package'
-            }
-        }
-
-        stage('Build Docker Image') {
-            agent any  // 使用 Jenkins 默认节点（宿主机），前提是宿主有 docker 命令
-            steps {
-                sh 'docker build -t $IMAGE_NAME .'
-            }
-        }
-
-        stage('Run Docker Container') {
-            agent any
-            steps {
-                sh '''
-                  docker network create traefik-public || true
-                  docker rm -f $CONTAINER_NAME || true
-                  docker run -d --name $CONTAINER_NAME --network mysql_default \\
-                  --restart=always \\
-                   -e SPRING_PROFILES_ACTIVE=dev \\
-                      --label "traefik.enable=true" \\
-                      --label "traefik.docker.network=traefik-public" \\
-                      --label 'traefik.http.routers.lpt-api-dev.rule=Host(`lpt-dev.cat-shark.xyz`) && PathPrefix(`/api`)' \\
-                      --label "traefik.http.routers.lpt-api-dev.entrypoints=websecure" \\
-                      --label "traefik.http.routers.lpt-api-dev.tls.certresolver=le" \\
-                      --label "traefik.http.routers.lpt-api-dev.priority=100" \\
-                      --label "traefik.http.routers.lpt-api-dev.service=lpt-api-dev" \\
-                      --label "traefik.http.routers.lpt-api-dev.middlewares=lpt-api-dev-strip" \\
-                      --label "traefik.http.middlewares.lpt-api-dev-strip.stripprefix.prefixes=/api" \\
-                      --label "traefik.http.services.lpt-api-dev.loadbalancer.server.port=$CONTAINER_PORT" \\
-                      --log-driver=loki \\
-                      --log-opt loki-url="http://192.168.123.199:3100/loki/api/v1/push" \\
-                   $IMAGE_NAME
-                  docker network connect traefik-public $CONTAINER_NAME || true
-                '''
-            }
-        }
-
-        stage('Check Docker Status') {
-            agent any
-            steps {
-                script {
-                    def lastStatus = ''
-                    timeout(time: 60, unit: 'SECONDS') {
-                        waitUntil {
-                            def status = sh(
-                                    script: "docker inspect -f '{{.State.Health.Status}}' $CONTAINER_NAME || echo 'unhealthy'",
-                                    returnStdout: true
-                            ).trim()
-
-                            if (status != lastStatus) {
-                                echo "Container health: ${status}"
-                                lastStatus = status
-                            }
-                            return (status == 'healthy')
-                        }
-                    }
-                }
-            }
-        }
-    }
-}