@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-backend-deploy/references/guide.md

@@ -0,0 +1,255 @@
+# 后端部署基础指南（backend-deploy）
+
+> Docker 镜像 / Kubernetes 部署 / 配置注入。
+
+---
+
+## 1. Docker 镜像
+
+### 1.1 多阶段构建
+
+```dockerfile
+# 第一阶段：构建
+FROM maven:3.9-eclipse-temurin-17 AS builder
+WORKDIR /build
+COPY pom.xml .
+RUN mvn dependency:go-offline -B
+COPY src ./src
+RUN mvn package -DskipTests -B
+
+# 第二阶段：运行
+FROM eclipse-temurin:17-jre-alpine
+WORKDIR /app
+
+# 时区
+RUN apk add --no-cache tzdata && \
+    cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
+    echo "Asia/Shanghai" > /etc/timezone
+
+# 复制 jar
+COPY --from=builder /build/target/your-service.jar /app/app.jar
+
+# JVM 参数
+ENV JAVA_OPTS="-XX:+UseG1GC -XX:MaxRAMPercentage=75.0 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/heapdump.hprof"
+
+EXPOSE 8080
+
+ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]
+```
+
+### 1.2 镜像优化
+
+| 优化点 | 效果 |
+|--------|------|
+| 多阶段构建 | 镜像小（无 Maven）|
+| JRE 而非 JDK | 镜像小 |
+| Alpine 基础镜像 | 镜像小 |
+| 合并 RUN | 层数少 |
+| 时区 | 日志时间正确 |
+
+## 2. Kubernetes 部署
+
+### 2.1 Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: your-service
+  namespace: meritdata
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: your-service
+  template:
+    metadata:
+      labels:
+        app: your-service
+    spec:
+      containers:
+        - name: your-service
+          image: registry.example.com/your-service:v1.2.3
+          ports:
+            - containerPort: 8080
+          env:
+            - name: SPRING_PROFILES_ACTIVE
+              value: prod
+            - name: NACOS_SERVER
+              valueFrom:
+                configMapKeyRef:
+                  name: your-service-config
+                  key: nacos.server
+            - name: DB_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: your-service-secret
+                  key: db-password
+          resources:
+            requests:
+              cpu: 500m
+              memory: 1Gi
+            limits:
+              cpu: 2000m
+              memory: 4Gi
+          readinessProbe:
+            httpGet:
+              path: /actuator/health/readiness
+              port: 8080
+            initialDelaySeconds: 30
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /actuator/health/liveness
+              port: 8080
+            initialDelaySeconds: 60
+            periodSeconds: 20
+```
+
+### 2.2 Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: your-service
+  namespace: meritdata
+spec:
+  selector:
+    app: your-service
+  ports:
+    - port: 80
+      targetPort: 8080
+  type: ClusterIP
+```
+
+### 2.3 Ingress
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: your-service
+  namespace: meritdata
+  annotations:
+    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
+spec:
+  rules:
+    - host: api.example.com
+      http:
+        paths:
+          - path: /api/your-service
+            pathType: Prefix
+            backend:
+              service:
+                name: your-service
+                port:
+                  number: 80
+```
+
+## 3. 配置管理
+
+### 3.1 ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: your-service-config
+  namespace: meritdata
+data:
+  nacos.server: nacos.example.com:8848
+  log.level: INFO
+  app.timeout: "30"
+```
+
+### 3.2 Secret
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: your-service-secret
+  namespace: meritdata
+type: Opaque
+stringData:
+  db-password: your-encrypted-password
+  api-key: your-api-key
+```
+
+⚠️ Secret 默认 base64 编码，**不是加密**。生产用 [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) 或 [External Secrets Operator](https://external-secrets.io/)。
+
+### 3.3 Nacos 集成（推荐）
+
+详见 [nacos-config encryption](../meritdata-platform-nacos-config/references/encryption.md)。
+
+```yaml
+env:
+  - name: SPRING_CLOUD_NACOS_CONFIG_SERVER_ADDR
+    value: nacos.example.com:8848
+  - name: SPRING_CLOUD_NACOS_CONFIG_NAMESPACE
+    value: prod
+```
+
+## 4. 资源限制
+
+```yaml
+resources:
+  requests:
+    cpu: 500m       # 0.5 核
+    memory: 1Gi
+  limits:
+    cpu: 2000m      # 2 核
+    memory: 4Gi
+```
+
+**必须**设置 requests（K8s 调度用）和 limits（防 OOM 影响其他容器）。
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 单阶段 Docker 构建
+
+```dockerfile
+# ❌ 错：JDK + Maven 都在镜像里
+FROM maven:3.9-jdk-17
+COPY . .
+RUN mvn package
+CMD java -jar target/app.jar
+```
+
+✅ 多阶段构建。
+
+### 5.2 ❌ 明文 Secret
+
+```yaml
+# ❌ 错
+data:
+  db-password: bXlwYXNz   # "mypass" 明文 base64
+```
+
+✅ 用 Sealed Secrets / External Secrets / Vault。
+
+### 5.3 ❌ 无健康检查
+
+```yaml
+# ❌ 错：没 readinessProbe
+# 启动慢的服务 → 流量打过来 → 502
+```
+
+✅ 必须配 readinessProbe + livenessProbe。
+
+### 5.4 ❌ 无资源限制
+
+```yaml
+# ❌ 错
+resources: {}   # 没限制
+# → 一个容器 OOM → 影响整个节点
+```
+
+✅ 显式设置 requests + limits。
+
+## 6. 关联阅读
+
+- [release-strategies.md](release-strategies.md) — 灰度 / 滚动 / 蓝绿
+- [health-monitor-log.md](health-monitor-log.md) — 健康检查 + 监控 + 日志
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-backend-deploy/references/health-monitor-log.md

@@ -0,0 +1,325 @@
+# 健康检查 / 监控 / 日志（backend-deploy）
+
+> Spring Boot Actuator / Prometheus / ELK。
+
+---
+
+## 1. Spring Boot Actuator
+
+### 1.1 引入
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-actuator</artifactId>
+</dependency>
+```
+
+### 1.2 配置
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health, info, metrics, prometheus
+  endpoint:
+    health:
+      show-details: when_authorized
+      probes:
+        enabled: true
+  health:
+    livenessState:
+      enabled: true
+    readinessState:
+      enabled: true
+    db:
+      enabled: true            # DB 健康检查
+    redis:
+      enabled: true            # Redis 健康检查
+    diskSpace:
+      enabled: true
+```
+
+### 1.3 健康检查端点
+
+```
+/actuator/health              综合健康
+/actuator/health/liveness     存活探针（K8s livenessProbe）
+/actuator/health/readiness    就绪探针（K8s readinessProbe）
+```
+
+### 1.4 自定义健康检查
+
+```java
+@Component
+public class CustomHealthIndicator implements HealthIndicator {
+    @Override
+    public Health health() {
+        if (checkExternalService()) {
+            return Health.up().build();
+        }
+        return Health.down().withDetail("reason", "外部服务不可用").build();
+    }
+}
+```
+
+## 2. Kubernetes 探针
+
+### 2.1 readinessProbe（就绪探针）
+
+**作用**：Pod 准备好才接流量。
+
+```yaml
+readinessProbe:
+  httpGet:
+    path: /actuator/health/readiness
+    port: 8080
+  initialDelaySeconds: 30       # 启动后等 30s 才探
+  periodSeconds: 10             # 每 10s 探一次
+  timeoutSeconds: 3
+  failureThreshold: 3           # 3 次失败才标记未就绪
+```
+
+### 2.2 livenessProbe（存活探针）
+
+**作用**：Pod 死了就重启。
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /actuator/health/liveness
+    port: 8080
+  initialDelaySeconds: 60
+  periodSeconds: 20
+  timeoutSeconds: 3
+  failureThreshold: 3
+```
+
+### 2.3 startupProbe（启动探针）
+
+慢启动服务（如 Java JVM）：
+
+```yaml
+startupProbe:
+  httpGet:
+    path: /actuator/health/liveness
+    port: 8080
+  initialDelaySeconds: 10
+  periodSeconds: 10
+  failureThreshold: 30    # 30 * 10s = 5 分钟启动时间
+```
+
+## 3. Prometheus 监控
+
+### 3.1 引入
+
+```xml
+<dependency>
+    <groupId>io.micrometer</groupId>
+    <artifactId>micrometer-registry-prometheus</artifactId>
+</dependency>
+```
+
+### 3.2 暴露端点
+
+```
+GET /actuator/prometheus
+```
+
+### 3.3 自定义指标
+
+```java
+@Component
+public class OrderMetrics {
+    private final Counter orderCreatedCounter;
+    private final Timer orderProcessTimer;
+
+    public OrderMetrics(MeterRegistry registry) {
+        this.orderCreatedCounter = Counter.builder("order_created_total")
+            .tag("type", "sales")
+            .description("订单创建总数")
+            .register(registry);
+
+        this.orderProcessTimer = Timer.builder("order_process_duration")
+            .description("订单处理耗时")
+            .register(registry);
+    }
+
+    public void onOrderCreated() {
+        orderCreatedCounter.increment();
+    }
+
+    public void recordProcess(Runnable r) {
+        orderProcessTimer.record(r);
+    }
+}
+```
+
+### 3.4 Grafana 看板
+
+```
+order_created_total                  订单创建速率
+order_process_duration_seconds       订单处理耗时
+http_requests_total{method,uri}      HTTP 请求数
+jvm_memory_used_bytes{area}            JVM 内存
+jvm_gc_pause_seconds                 GC 暂停
+```
+
+## 4. 日志收集
+
+### 4.1 ELK（Elasticsearch + Logstash + Kibana）
+
+#### 应用输出 JSON 日志
+
+```xml
+<dependency>
+    <groupId>net.logstash.logback</groupId>
+    <artifactId>logstash-logback-encoder</artifactId>
+    <version>7.4</version>
+</dependency>
+```
+
+```xml
+<!-- logback-spring.xml -->
+<configuration>
+    <appender name="LOGSTASH" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
+            <customFields>{"app":"your-service","env":"prod"}</customFields>
+        </encoder>
+    </appender>
+
+    <root level="INFO">
+        <appender-ref ref="LOGSTASH" />
+    </root>
+</configuration>
+```
+
+#### Filebeat 采集
+
+```yaml
+# filebeat.yml
+filebeat.inputs:
+  - type: container
+    paths:
+      - /var/log/containers/your-service-*.log
+    json.keys_under_root: true
+    json.add_error_key: true
+
+output.logstash:
+  hosts: ["logstash:5044"]
+```
+
+### 4.2 关键日志
+
+- 启动日志（启动成功/失败）
+- 错误日志（异常堆栈）
+- 业务关键事件（订单创建、审批）
+- 慢请求日志
+
+### 4.3 ❌ 反模式
+
+```java
+// ❌ 错：日志脱敏
+log.info("用户登录：username={}, password={}", user, password);  // 密码进日志
+log.info("请求参数：{}", JSON.toJSONString(req));  // 含身份证 / 手机号
+
+// ❌ 错：日志级别不当
+log.debug("订单创建成功：{}", order);  // 生产关闭 debug → 排查信息丢失
+
+// ❌ 错：异常吞掉
+try { ... } catch (Exception e) { log.warn("error"); }  // 无堆栈
+```
+
+## 5. APM（应用性能监控）
+
+### 5.1 SkyWalking
+
+```xml
+<dependency>
+    <groupId>org.apache.skywalking</groupId>
+    <artifactId>apm-toolkit-trace</artifactId>
+</dependency>
+```
+
+```yaml
+# agent/config/agent.config
+agent.service_name=your-service
+collector.backend_service=skywalking-oap:11800
+```
+
+自动采集：
+- HTTP 请求耗时
+- DB 查询耗时
+- 慢方法
+- 异常
+
+## 6. 告警规则
+
+```yaml
+# Prometheus AlertManager
+groups:
+  - name: your-service
+    rules:
+      - alert: HighErrorRate
+        expr: rate(http_requests_total{status="500"}[5m]) > 0.05
+        for: 2m
+        annotations:
+          summary: "错误率超过 5%"
+
+      - alert: HighMemoryUsage
+        expr: jvm_memory_used_bytes{area="heap"} / jvm_memory_max_bytes{area="heap"} > 0.9
+        for: 5m
+        annotations:
+          summary: "JVM 堆内存 > 90%"
+
+      - alert: HighGcPause
+        expr: rate(jvm_gc_pause_seconds_sum[5m]) > 0.1
+        for: 5m
+        annotations:
+          summary: "GC 暂停 > 100ms/s"
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 无健康检查
+
+```yaml
+# ❌ 错：K8s Deployment 没配探针
+# 启动慢服务 → 流量打过来 → 502
+```
+
+✅ 配 readinessProbe + livenessProbe。
+
+### 7.2 ❌ 探针路径错
+
+```yaml
+# ❌ 错：探针路径不存在 → 永远不健康
+livenessProbe:
+  httpGet:
+    path: /health  # 不存在
+```
+
+✅ 用 Actuator 端点（`/actuator/health/liveness`）。
+
+### 7.3 ❌ 日志无结构化
+
+```java
+// ❌ 错：纯文本日志
+log.info("user " + userId + " created order " + orderId);
+
+// ✅ 正确：结构化日志
+log.info("order_created", kv("userId", userId), kv("orderId", orderId));
+```
+
+### 7.4 ❌ 监控盲区
+
+只监控 CPU/Memory，不监控业务指标。
+
+✅ 业务指标（订单数、转化率）+ 技术指标（JVM、HTTP）结合。
+
+## 8. 关联阅读
+
+- [guide.md](guide.md) — 后端部署基础
+- [release-strategies.md](release-strategies.md) — 发布策略
+- [SKILL.md](../SKILL.md)