gao/ljwx-health
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ljwx-health/deploy
T
History

README.md

部署文档 (Deployment Guide)

目录结构

deploy/
├── compose/                          # Docker Compose 配置（开发环境）
│   ├── docker-compose.dev.yml       # 基础设施（MySQL + Redis）
│   └── docker-compose.full.yml      # 完整服务（含应用）
├── helm/                             # Helm Charts（生产环境）
│   └── ljwx-health/
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
├── environments/                     # 环境差异化配置
│   ├── dev-eu.yaml                  # 欧洲开发环境
│   └── dev-mac.yaml                 # Mac Studio 开发环境
└── README.md                         # 本文件

部署演进路线图

阶段 1: Docker Compose（当前阶段）✅

适用场景: 本地开发、快速验证

优势:

  • 一键启动基础设施（MySQL + Redis）
  • 无需 K8s 环境
  • 适合单机开发调试

限制:

  • 无自动扩缩容
  • 无服务发现
  • 无滚动更新

使用方式:

# 启动基础设施
./scripts/dev_up.sh

# 执行数据库迁移
./scripts/db_migrate.sh

# 本地启动应用
cd ljwx-boot && ./run-local.sh
cd ljwx-bigscreen/bigscreen && python run.py

阶段 2: Helm + K3s（规划中）⏳

适用场景: 多环境部署（开发/测试/预发布）

优势:

  • 标准化配置管理
  • 环境差异化（values-dev.yaml, values-prod.yaml）
  • 支持滚动更新
  • 资源限制与健康检查

目标环境:

  • 欧洲节点 K3s 集群
  • Mac Studio K3s 集群

使用方式（待实现）:

# 部署到开发环境
helm upgrade --install ljwx-health ./deploy/helm/ljwx-health \
  -f deploy/environments/dev-eu.yaml \
  -n ljwx-health-dev --create-namespace

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

阶段 3: Argo CD + GitOps（最终目标）🎯

适用场景: 生产环境持续交付

优势:

  • Git 作为单一事实源
  • 自动同步部署
  • 声明式配置
  • 审计与回滚

架构:

Git Repo (main branch)
  └── deploy/helm/ljwx-health/
        ↓
    Argo CD Application
        ↓
    K3s Cluster (EU / Mac Studio)
        ↓
    ljwx-boot + ljwx-bigscreen + MySQL + Redis

使用方式（待实现）:

# argocd-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ljwx-health
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/ljwx-health.git
    targetRevision: main
    path: deploy/helm/ljwx-health
    helm:
      valueFiles:
        - ../../environments/dev-eu.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: ljwx-health-dev
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

环境变量约定

通用环境变量

变量名 说明 示例值 来源
ENV 环境标识 dev, staging, production ConfigMap
SERVICE_NAME 服务名称 ljwx-boot, ljwx-bigscreen ConfigMap
LOG_LEVEL 日志级别 INFO, DEBUG ConfigMap

数据库环境变量

变量名 说明 示例值 来源
DB_HOST 数据库地址 mysql.infra.svc.cluster.local ConfigMap
DB_PORT 数据库端口 3306 ConfigMap
DB_NAME 数据库名称 ljwx_health ConfigMap
DB_USER 数据库用户 ljwx_app Secret
DB_PASSWORD 数据库密码 <encrypted> Secret

Redis 环境变量

变量名 说明 示例值 来源
REDIS_HOST Redis 地址 redis.infra.svc.cluster.local ConfigMap
REDIS_PORT Redis 端口 6379 ConfigMap
REDIS_PASSWORD Redis 密码 <encrypted> Secret
REDIS_DB Redis 数据库索引 1 ConfigMap

可观测性环境变量

变量名 说明 示例值 来源
OTEL_EXPORTER_OTLP_ENDPOINT Tempo 地址 http://tempo.infra.svc:4317 ConfigMap
OTEL_SERVICE_NAME 服务名称 ljwx-boot ConfigMap
OTEL_TRACES_SAMPLER 采样策略 parentbased_traceidratio ConfigMap
OTEL_TRACES_SAMPLER_ARG 采样率 0.1 (10%) ConfigMap

数据库迁移策略

当前方案（Compose）

执行方式: 通过 scripts/db_migrate.sh 手动触发

#!/bin/bash
# scripts/db_migrate.sh

cd ljwx-boot
mvn flyway:migrate \
  -Dflyway.url=jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME} \
  -Dflyway.user=${DB_USER} \
  -Dflyway.password=${DB_PASSWORD}

未来方案（Helm + Argo CD）

执行方式: K8s Job + Argo CD PreSync Hook

# deploy/helm/ljwx-health/templates/migration-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      containers:
        - name: flyway
          image: flyway/flyway:latest
          command: ['flyway', 'migrate']
          env:
            - name: FLYWAY_URL
              value: jdbc:mysql://$(DB_HOST):$(DB_PORT)/$(DB_NAME)
            - name: FLYWAY_USER
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: username
            - name: FLYWAY_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: password
          volumeMounts:
            - name: migrations
              mountPath: /flyway/sql
      volumes:
        - name: migrations
          configMap:
            name: db-migrations
      restartPolicy: Never

优势:

  • 应用部署前自动执行迁移
  • 迁移失败自动阻止应用更新
  • 完整的执行日志与审计

基础设施复用策略

当前状态（独立部署）

ljwx-health-dev namespace
├── ljwx-boot (Pod)
├── ljwx-bigscreen (Pod)
├── mysql (StatefulSet) ← 独立部署
└── redis (StatefulSet) ← 独立部署

未来状态（infra 复用）

infra namespace
├── postgres (StatefulSet) ← 统一数据库
└── redis (StatefulSet)    ← 统一缓存

ljwx-health-dev namespace
├── ljwx-boot (Pod) ────→ postgres.infra.svc (独立 DB + 用户)
└── ljwx-bigscreen (Pod) ─→ redis.infra.svc (独立前缀/库)

迁移步骤:

  1. 在 infra namespace 创建 Postgres 数据库
  2. 创建独立用户 ljwx_app 与 Schema ljwx_health
  3. 执行数据迁移（MySQL → Postgres）
  4. 更新 ljwx-health 应用配置指向 infra Postgres
  5. 验证后下线独立 MySQL

健康检查配置

Spring Boot

# K8s Deployment
livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 9998
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 9998
  initialDelaySeconds: 10
  periodSeconds: 5

FastAPI

livenessProbe:
  httpGet:
    path: /health
    port: 5225
  initialDelaySeconds: 10
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5225
  initialDelaySeconds: 5
  periodSeconds: 5

资源配置建议

ljwx-boot (Spring Boot)

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 2000m
    memory: 2Gi

ljwx-bigscreen (FastAPI)

resources:
  requests:
    cpu: 250m
    memory: 512Mi
  limits:
    cpu: 1000m
    memory: 1Gi

网络与访问

开发环境（Compose）

服务 地址 说明
ljwx-boot http://localhost:9998 Spring Boot API
ljwx-bigscreen http://localhost:5225 FastAPI 大屏
MySQL localhost:3306 数据库
Redis localhost:6379 缓存

K8s 环境（Helm）

服务 内部地址 外部访问（Ingress）
ljwx-boot ljwx-boot.ljwx-health-dev.svc:9998 https://api.ljwx-health.example.com
ljwx-bigscreen ljwx-bigscreen.ljwx-health-dev.svc:5225 https://bigscreen.ljwx-health.example.com

验收标准

PR-4（Compose 阶段）

  • ./scripts/dev_up.sh 可一键启动 MySQL + Redis
  • ./scripts/db_migrate.sh 可执行 Flyway 迁移
  • 新人可在 10 分钟内完成环境搭建

PR-6（Helm 阶段）

  • Helm Chart 模板语法正确（helm lint 通过）
  • values.yaml 结构清晰，支持环境差异化
  • migration-job.yaml PreSync Hook 配置正确

未来（Argo CD 阶段）

  • Argo CD Application 可自动同步
  • Git commit 自动触发部署
  • 回滚操作 < 1 分钟

更新时间: 2025-12-18 当前阶段: Compose 开发环境 下一步: Helm Chart 结构搭建（PR-6）

Reference in New Issue View Git Blame Copy Permalink