ljwx-health/deploy/QUICK_DEPLOY.md

LJWX Health - 快捷部署指南

本指南提供本地 AMD64 架构快速构建并部署到 K3s 的完整流程。

前置条件

• ✅ Docker 已安装并登录到 Harbor
• ✅ K3s 集群运行正常
• ✅ kubectl 和 Helm 已安装
• ✅ infra namespace 已部署 MySQL 和 Redis

环境架构

┌─────────────────────────────────────────────────────────┐
│                  K3s Cluster (ljwx-health ns)          │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────┐   ┌──────────────┐                   │
│  │ ljwx-boot    │   │ ljwx-admin   │                   │
│  │ (Spring Boot)│   │ (Vue3/Nginx) │                   │
│  └──────┬───────┘   └──────────────┘                   │
│         │                                                │
│         └──────┐                                        │
├────────────────┼────────────────────────────────────────┤
│                ▼                                         │
│  ┌─────────────────────────────────────┐                │
│  │    infra namespace (复用)           │                │
│  │  ┌────────┐       ┌──────────┐     │                │
│  │  │ MySQL  │       │  Redis   │     │                │
│  │  └────────┘       └──────────┘     │                │
│  └─────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

一键部署（推荐）

首次部署

# 1. 创建数据库 Secrets（仅首次需要）
./scripts/create-k3s-secrets.sh

# 2. 完整部署（构建 + 推送 + 部署）
./scripts/quick-deploy.sh

后续部署（已有 Secrets）

# 完整部署
./scripts/quick-deploy.sh

常用场景

场景 1：仅构建镜像（不部署）

./scripts/quick-deploy.sh --build-only

场景 2：仅部署已有镜像（跳过构建）

VERSION=dev-20251221-120000 ./scripts/quick-deploy.sh --skip-build

场景 3：指定版本号部署

VERSION=v1.0.7 ./scripts/quick-deploy.sh

场景 4：仅更新数据库迁移

# 整理迁移脚本
./scripts/organize-migrations.sh

# 部署（会自动更新 ConfigMap）
VERSION=current ./scripts/quick-deploy.sh --skip-build

脚本参数说明

参数	说明	示例
--skip-build	跳过镜像构建，仅部署	./scripts/quick-deploy.sh --skip-build
--build-only	仅构建镜像，不部署	./scripts/quick-deploy.sh --build-only
--version <版本>	指定镜像版本	./scripts/quick-deploy.sh --version v1.0.7
--help	显示帮助信息	./scripts/quick-deploy.sh --help

环境变量

变量	默认值	说明
VERSION	dev-<时间戳>	镜像版本号
HARBOR_HOST	harbor.eu.lingjingwanxiang.cn	Harbor 地址
KUBECONFIG	/etc/rancher/k3s/k3s.yaml	K8s 配置文件路径

部署流程

┌─────────────────────────────────────────────────────────┐
│ 1. 检查前置条件 (Docker, kubectl, Helm, K3s)           │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 2. 登录 Harbor                                          │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 3. 构建镜像 (ljwx-boot + ljwx-admin)                   │
│    - Multi-stage build                                  │
│    - Platform: linux/amd64                              │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 4. 推送镜像到 Harbor                                     │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 5. 创建 Flyway Migration ConfigMap                     │
│    - 来源: ljwx-boot/src/main/resources/db/migration   │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 6. Helm 部署到 K3s (ljwx-health namespace)             │
│    - PreSync: Flyway Migration Job                     │
│    - Deployment: ljwx-boot, ljwx-admin                  │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 7. 验证部署状态                                          │
└─────────────────────────────────────────────────────────┘

Flyway 数据库迁移

迁移脚本位置

ljwx-boot/src/main/resources/db/migration/
├── V1.0.3__create_weight_cache_table.sql
├── V1.0.4__optimize_health_baseline_for_userid.sql
├── V1.0.5__create_message_v2_tables.sql
├── ...
└── V20251218_002__create_message_config_table.sql

迁移脚本命名规范

• 格式：V<版本号>__<描述>.sql
• 版本号：使用语义化版本（如 1.0.3）或日期版本（如 20251218_001）
• 描述：简短的英文描述，使用下划线分隔

整理迁移脚本

如果你在 ljwx-boot/database/migrations/ 添加了新的迁移文件，运行：

./scripts/organize-migrations.sh

该脚本会：

1. 自动选择最终版本（跳过重复的 _fixed、_v2 等）
2. 重命名为 Flyway 标准格式
3. 复制到 ljwx-boot/src/main/resources/db/migration/

访问应用

端口转发

# Backend API (Spring Boot)
kubectl port-forward -n ljwx-health svc/ljwx-health-boot 9998:9998

# Frontend Admin (Vue3)
kubectl port-forward -n ljwx-health svc/ljwx-health-admin 8080:80

健康检查

# 方式 1: 通过 curl
kubectl port-forward -n ljwx-health svc/ljwx-health-boot 9998:9998
curl http://localhost:9998/actuator/health

# 方式 2: 在 Pod 内执行
kubectl exec -n ljwx-health -it deploy/ljwx-health-boot -- \
  curl http://localhost:9998/actuator/health

查看日志

# Flyway Migration 日志
kubectl logs -n ljwx-health -l app=ljwx-migration --tail=100

# Spring Boot 日志
kubectl logs -n ljwx-health -l app=ljwx-boot -f

# Vue3 Admin 日志
kubectl logs -n ljwx-health -l app=ljwx-admin -f

# 查看 Pod 状态
kubectl get pods -n ljwx-health

故障排查

镜像拉取失败

# 检查 Harbor 登录状态
docker login harbor.eu.lingjingwanxiang.cn

# 检查镜像是否存在
docker images | grep ljwx-health

# 手动拉取测试
docker pull harbor.eu.lingjingwanxiang.cn/ljwx-health/ljwx-boot:dev-latest

Flyway Migration 失败

# 查看 Migration Job 日志
kubectl logs -n ljwx-health -l app=ljwx-migration

# 手动执行 Migration
kubectl delete job -n ljwx-health -l app=ljwx-migration
helm upgrade --install ljwx-health ./deploy/helm/ljwx-health \
  --namespace ljwx-health \
  --values ./deploy/environments/k3s-eu.yaml

Pod 无法启动

# 查看 Pod 事件
kubectl describe pod -n ljwx-health -l app=ljwx-boot

# 查看 Pod 日志
kubectl logs -n ljwx-health -l app=ljwx-boot --previous

# 检查 Secret 是否存在
kubectl get secret ljwx-boot-secrets -n ljwx-health

# 检查数据库连接
kubectl exec -n ljwx-health -it deploy/ljwx-health-boot -- \
  nc -zv mysql.infra.svc.cluster.local 3306

KUBECONFIG 问题

# 检查 KUBECONFIG
echo $KUBECONFIG

# 手动设置
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# 验证连接
kubectl cluster-info
kubectl get nodes

配置说明

MySQL 连接（复用 infra namespace）

env:
  - name: DB_HOST
    value: "mysql.infra.svc.cluster.local"
  - name: DB_PORT
    value: "3306"
  - name: DB_NAME
    value: "ljwx_health"
envFrom:
  - secretRef:
      name: ljwx-boot-secrets  # DB_USER, DB_PASSWORD

Redis 连接（复用 infra namespace）

env:
  - name: REDIS_HOST
    value: "redis.infra.svc.cluster.local"
  - name: REDIS_PORT
    value: "6379"
  - name: REDIS_DB
    value: "1"
envFrom:
  - secretRef:
      name: ljwx-boot-secrets  # REDIS_PASSWORD

Flyway 配置

env:
  - name: FLYWAY_URL
    value: "jdbc:mysql://mysql.infra.svc.cluster.local:3306/ljwx_health?useSSL=false&serverTimezone=Asia/Shanghai"
  - name: FLYWAY_BASELINE_ON_MIGRATE
    value: "true"
  - name: FLYWAY_BASELINE_VERSION
    value: "0"

相关文件

• 快捷部署脚本: scripts/quick-deploy.sh - 一键构建+部署
• 构建脚本: scripts/local-build-amd64.sh - 仅构建镜像
• 迁移整理脚本: scripts/organize-migrations.sh - 整理 Flyway 脚本
• Secret 创建脚本: scripts/create-k3s-secrets.sh - 创建 K8s Secrets
• Helm Chart: deploy/helm/ljwx-health/ - K8s 部署配置
• 环境配置: deploy/environments/k3s-eu.yaml - K3s EU 环境变量

最佳实践

1. 首次部署前：确保运行 ./scripts/create-k3s-secrets.sh 创建 Secret
2. 频繁迭代：使用 --skip-build 跳过构建，节省时间
3. 版本管理：生产部署使用明确的版本号（如 v1.0.7），避免使用 dev-latest
4. 迁移脚本：只追加新脚本，不修改已发布的迁移文件
5. 健康检查：部署后始终检查 Migration Job 和应用 Pod 的日志

参考资料

• PROMPT_BLUEPRINT.md - 工程规范蓝图
• CLAUDE.md - 项目整体说明
• Flyway Documentation
• Helm Documentation