@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

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

@@ -1,255 +0,0 @@
-# 后端部署基础指南（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

@@ -1,325 +0,0 @@
-# 健康检查 / 监控 / 日志（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)