@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

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)

package/skills/meritdata-platform-backend-deploy/references/release-strategies.md

@@ -1,256 +0,0 @@
-# 发布策略（backend-deploy）
-
-> 滚动发布 / 蓝绿部署 / 灰度（金丝雀）。
-
----
-
-## 1. 滚动发布（Rolling Update）
-
-### 1.1 默认策略
-
-K8s Deployment 默认滚动发布：
-
-```
-v1 (3 副本)
-   ↓
-v1 (2) + v2 (1)        启动新版本
-   ↓
-v1 (1) + v2 (2)        继续滚动
-   ↓
-v2 (3)                 完成
-```
-
-### 1.2 配置
-
-```yaml
-spec:
-  strategy:
-    type: RollingUpdate
-    rollingUpdate:
-      maxSurge: 1           # 最多多 1 个 pod
-      maxUnavailable: 0     # 不可用 ≤ 0
-```
-
-### 1.3 适用
-
-- 无状态服务
-- 启动快
-- 兼容性要求不高
-
-## 2. 蓝绿部署（Blue-Green）
-
-### 2.1 流程
-
-```
-蓝色（当前版本）  ← 100% 流量
-绿色（新版本）    ← 0% 流量
-   ↓ 验证
-绿色               ← 切流量（100%）
-蓝色               ← 0%（保留，回滚用）
-   ↓ 验证 OK
-蓝色               ← 销毁
-```
-
-### 2.2 实现
-
-```yaml
-# 蓝色（当前）
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: your-service-blue
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: your-service
-      version: blue
-  template:
-    metadata:
-      labels:
-        app: your-service
-        version: blue
-    spec:
-      containers:
-        - name: app
-          image: registry.example.com/your-service:v1.2.3
----
-# 绿色（新）
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: your-service-green
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: your-service
-      version: green
-  template:
-    metadata:
-      labels:
-        app: your-service
-        version: green
-    spec:
-      containers:
-        - name: app
-          image: registry.example.com/your-service:v1.3.0
----
-# Service 通过 version 标签路由
-apiVersion: v1
-kind: Service
-metadata:
-  name: your-service
-spec:
-  selector:
-    app: your-service
-    version: blue       # 切到 green → 全量切到新版本
-  ports:
-    - port: 80
-      targetPort: 8080
-```
-
-切流量：
-
-```bash
-# 一行命令完成切换
-kubectl patch service your-service -p '{"spec":{"selector":{"version":"green"}}}'
-```
-
-回滚：
-
-```bash
-kubectl patch service your-service -p '{"spec":{"selector":{"version":"blue"}}}'
-```
-
-### 2.3 适用
-
-- 关键业务（金融、订单）
-- 数据库 schema 变更需谨慎
-- 出了问题要立即回滚
-
-## 3. 灰度发布（金丝雀）
-
-### 3.1 流量比例
-
-```
-v1 (90%) + v2 (10%)   ← 灰度开始
-   ↓ 观察
-v1 (50%) + v2 (50%)   ← 监控正常
-   ↓
-v2 (100%)             ← 全量
-```
-
-### 3.2 Istio 灰度
-
-```yaml
-apiVersion: networking.istio.io/v1beta1
-kind: VirtualService
-metadata:
-  name: your-service
-spec:
-  hosts:
-    - your-service
-  http:
-    - match:
-        - headers:
-            user-agent:
-              regex: ".*beta.*"
-      route:
-        - destination:
-            host: your-service
-            subset: v2
-    - route:
-        - destination:
-            host: your-service
-            subset: v1
-          weight: 90
-        - destination:
-            host: your-service
-            subset: v2
-          weight: 10
-```
-
-按 Header / Cookie / 权重分流。
-
-### 3.3 适用
-
-- 大流量服务
-- 重要版本
-- 灰度验证
-
-## 4. 数据库迁移
-
-### 4.1 兼容性原则
-
-**新版本加列 → nullable**：
-
-```sql
--- 新版本加列
-ALTER TABLE t_order ADD COLUMN new_field VARCHAR(50) NULL;
-```
-
-旧版本代码忽略新字段；新版本代码读新字段。
-
-### 4.2 双写
-
-```
-旧版本：写 t_order_old
-新版本：写 t_order_new + t_order_old（双写）
-   ↓
-数据同步完成
-   ↓
-新版本：只写 t_order_new
-```
-
-### 4.3 灰度回滚
-
-如果新版本数据库变更需要回滚：
-- 保留旧版本 schema 兼容
-- 双写未关闭 → 数据安全
-
-## 5. 发布检查清单
-
-- [ ] 新版本镜像已构建 + 推送到 registry
-- [ ] 配置文件已更新（ConfigMap / Nacos）
-- [ ] 数据库变更已执行（兼容旧版本）
-- [ ] 健康检查 URL 可用
-- [ ] 监控指标已就绪
-- [ ] 回滚预案就绪
-- [ ] 灰度比例已规划
-- [ ] 团队已通知
-
-## 6. ❌ 反模式
-
-### 6.1 ❌ 全量直接推
-
-```bash
-# ❌ 错：直接全量推
-kubectl set image deployment/your-service app=registry/app:v2.0.0
-```
-
-✅ 先灰度 → 监控 → 推全。
-
-### 6.2 ❌ 数据库破坏性变更
-
-```sql
--- ❌ 错：直接删列
-ALTER TABLE t_order DROP COLUMN old_field;
-```
-
-✅ 先加 nullable → 新版本不用 → 数据迁移 → 删列（多版本发布）。
-
-### 6.3 ❌ 无回滚预案
-
-```bash
-# ❌ 错：上线后没保留旧版本
-kubectl delete deployment your-service-v1
-```
-
-✅ 保留历史版本 + Deployment 历史。
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — 后端部署基础
-- [health-monitor-log.md](health-monitor-log.md) — 健康检查 + 监控 + 日志
-- [SKILL.md](../SKILL.md)