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

package/skills/meritdata-platform-frontend-deploy/references/cdn-https-cache.md

@@ -1,222 +0,0 @@
-# CDN + HTTPS + 缓存策略（frontend-deploy）
-
-> CDN 加速 / HTTPS 配置 / 多级缓存。
-
----
-
-## 1. CDN 配置
-
-### 1.1 阿里云 / 腾讯云 CDN
-
-源站：你的服务器 / OSS bucket。
-
-加速域名：`cdn.example.com`（CNAME 到 CDN）。
-
-### 1.2 缓存规则
-
-```
-/assets/*           → 缓存 365 天（hash 文件名）
-/assets/index.html  → 不缓存
-/api/*              → 不缓存（动态）
-*.html              → 不缓存
-*.js, *.css, *.png  → 缓存 30 天
-```
-
-### 1.3 回源策略
-
-```
-用户请求 → CDN 节点
-   ↓ miss
-CDN 回源服务器
-   ↓
-缓存到 CDN
-   ↓
-返回用户
-```
-
-### 1.4 HTTPS on CDN
-
-- CDN 支持 HTTPS 回源
-- 客户端 → CDN：HTTPS（CDN 证书）
-- CDN → 源站：HTTP / HTTPS（可选）
-
-## 2. 缓存策略
-
-### 2.1 文件名 hash + 长缓存
-
-```
-dist/
-├── index.html              ← 不缓存
-└── assets/
-    ├── js/
-    │   ├── main.abc123.js  ← 缓存 1 年（hash 文件名）
-    │   └── vendor.def456.js
-    └── css/
-        └── main.abc123.css
-```
-
-文件 hash 变了 → 新 URL → 用户拉新文件。
-
-### 2.2 配置（Nginx）
-
-```nginx
-# HTML 不缓存
-location = /index.html {
-    add_header Cache-Control "no-cache, no-store, must-revalidate";
-    expires 0;
-}
-
-# 静态资源长缓存
-location ~* \.(js|css|png|jpg|svg|woff2)$ {
-    expires 1y;
-    add_header Cache-Control "public, immutable";
-}
-```
-
-### 2.3 配置（CDN）
-
-在 CDN 控制台配置缓存规则：
-
-```
-/index.html              0 秒（不缓存）
-/assets/*.js             365 天
-/assets/*.css            365 天
-/assets/*.png            365 天
-/api/*                   0 秒（不缓存）
-```
-
-## 3. HTTPS 全面启用
-
-### 3.1 证书获取
-
-- Let's Encrypt（免费，90 天续期）
-- 阿里云 / 腾讯云 SSL 证书（付费）
-- 自签名（仅内部使用）
-
-### 3.2 Nginx 配置
-
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name app.example.com;
-
-    ssl_certificate     /etc/nginx/ssl/app.crt;
-    ssl_certificate_key /etc/nginx/ssl/app.key;
-
-    ssl_protocols       TLSv1.2 TLSv1.3;
-    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
-    ssl_prefer_server_ciphers on;
-
-    ssl_session_cache   shared:SSL:10m;
-    ssl_session_timeout 1d;
-    ssl_session_tickets off;
-
-    # HSTS
-    add_header Strict-Transport-Security "max-age=63072000" always;
-}
-```
-
-### 3.3 强制 HTTPS
-
-```nginx
-server {
-    listen 80;
-    server_name app.example.com;
-    return 301 https://$server_name$request_uri;
-}
-```
-
-### 3.4 HSTS Preload
-
-将域名加入 HSTS Preload List → 浏览器硬编码强制 HTTPS。
-
-## 4. 多级缓存
-
-### 4.1 浏览器缓存
-
-```
-强缓存（Cache-Control / Expires）→ 不发请求
-   ↓ 失效
-协商缓存（ETag / Last-Modified）→ 304 Not Modified
-   ↓ 不匹配
-服务器返回新内容
-```
-
-### 4.2 CDN 缓存
-
-CDN 节点缓存静态资源。
-
-### 4.3 Nginx 缓存
-
-```nginx
-proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app_cache:10m;
-
-location /api/static/ {
-    proxy_cache app_cache;
-    proxy_cache_valid 200 5m;
-    proxy_pass http://backend;
-}
-```
-
-## 5. 缓存失效
-
-### 5.1 主动刷新（CDN）
-
-```bash
-# 阿里云
-aliyun cdn RefreshObjectCaches --ObjectPath https://app.example.com/index.html
-
-# 腾讯云
-tccli cdn PurgePathCache --Paths https://app.example.com/index.html
-```
-
-### 5.2 主动刷新（业务触发）
-
-```typescript
-// 部署完成 → 调用 CDN 刷新接口
-await fetch('https://cdn-api.example.com/refresh', {
-  method: 'POST',
-  body: JSON.stringify({ url: 'https://app.example.com/index.html' })
-});
-```
-
-## 6. ❌ 反模式
-
-### 6.1 ❌ HTML 缓存
-
-```nginx
-# ❌ 错：HTML 缓存 1 天
-location / {
-    expires 1d;
-}
-```
-
-✅ HTML 不缓存。
-
-### 6.2 ❌ 静态资源短期缓存
-
-```nginx
-# ❌ 错
-location ~* \.js$ {
-    expires 1h;  # 用户每小时重新下载
-}
-```
-
-✅ hash 文件名 + 1 年。
-
-### 6.3 ❌ 混合 HTTP / HTTPS
-
-```nginx
-# ❌ 错：HTTP 也开放
-server {
-    listen 80;  # 没强制跳转
-}
-```
-
-✅ 80 → 443 重定向。
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — 前端部署基础
-- [gray-and-rollback.md](gray-and-rollback.md) — 灰度 + 回滚
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-frontend-deploy/references/gray-and-rollback.md

@@ -1,236 +0,0 @@
-# 灰度发布与回滚（frontend-deploy）
-
-> 灰度策略 / 版本回滚 / 蓝绿部署。
-
----
-
-## 1. 灰度发布策略
-
-### 1.1 用户灰度
-
-按用户 ID / 租户 ID 取模：
-
-```
-userId % 100 < 10  → 新版本
-其他                → 旧版本
-```
-
-### 1.2 地域灰度
-
-按 IP 地域：
-
-```
-华北 → 旧版本
-华东 → 新版本
-```
-
-### 1.3 浏览器灰度
-
-按 User-Agent / Cookie：
-
-```
-Chrome + cookie=beta → 新版本
-其他                  → 旧版本
-```
-
-## 2. 实现方案
-
-### 2.1 方案 1：双版本目录
-
-```nginx
-server {
-    listen 80;
-    server_name app.example.com;
-
-    # 旧版本
-    location /v1/ {
-        alias /var/www/app/v1.0.0/;
-        try_files $uri $uri/ /v1/index.html;
-    }
-
-    # 新版本
-    location /v2/ {
-        alias /var/www/app/v2.0.0/;
-        try_files $uri $uri/ /v2/index.html;
-    }
-
-    # 灰度路由
-    location / {
-        set $version 'v1';
-        if ($http_cookie ~* "beta=true") {
-            set $version 'v2';
-        }
-        # 按 IP hash
-        if ($remote_addr ~ "^192\.168\.1\.") {
-            set $version 'v2';
-        }
-        return 302 /$version$request_uri;
-    }
-}
-```
-
-### 2.2 方案 2：路径分流（CDN）
-
-CDN 配置：
-
-```
-/v1/*  → 旧版本 bucket
-/v2/*  → 新版本 bucket
-```
-
-前端按用户分流到 /v1 或 /v2。
-
-### 2.3 方案 3：前端判断
-
-```typescript
-// 前端代码
-async function getVersion() {
-  const userId = getCurrentUserId();
-  if (userId % 100 < 10) {
-    return 'v2';
-  }
-  return 'v1';
-}
-
-// 根据版本加载不同资源
-const manifest = await import(`/manifest-${version}.json`);
-```
-
-## 3. 蓝绿部署
-
-### 3.1 流程
-
-```
-蓝色（当前版本）  ← 100% 流量
-绿色（新版本）    ← 0% 流量
-   ↓ 切换
-蓝色               ← 0% 流量
-绿色               ← 100% 流量
-   ↓ 出问题
-蓝色               ← 100% 流量（回滚）
-```
-
-### 3.2 Nginx 配置
-
-```nginx
-upstream blue {
-    server blue-1.example.com;
-    server blue-2.example.com;
-}
-
-upstream green {
-    server green-1.example.com;
-    server green-2.example.com;
-}
-
-server {
-    listen 80;
-    server_name app.example.com;
-
-    # 默认 blue
-    location / {
-        proxy_pass http://blue;
-    }
-
-    # 灰度切到 green
-    # proxy_pass http://green;
-}
-```
-
-切换 → 改一行配置 → nginx reload。
-
-## 4. 版本回滚
-
-### 4.1 保留历史版本
-
-```bash
-/var/www/app/
-├── v1.0.0/
-├── v1.1.0/
-├── v1.2.0/  ← 当前
-└── v1.3.0/  ← 新版本（出问题）
-```
-
-### 4.2 一键回滚脚本
-
-```bash
-#!/bin/bash
-# rollback.sh
-CURRENT=$(readlink /var/www/app/current)
-PREVIOUS=$(ls -t /var/www/app/ | grep -E '^v[0-9]+\.' | sed -n '2p')
-
-echo "Rollback from $CURRENT to $PREVIOUS"
-
-rm /var/www/app/current
-ln -s /var/www/app/$PREVIOUS /var/www/app/current
-
-nginx -s reload
-echo "Rollback complete"
-```
-
-### 4.3 数据库版本兼容
-
-⚠️ **前端回滚 ≠ 数据库回滚**
-
-数据库变更要兼容旧版本：
-
-```sql
--- 加列要 nullable
-ALTER TABLE t_order ADD COLUMN new_field VARCHAR(50) NULL;
-```
-
-新版本用新字段；旧版本忽略新字段（不报错）。
-
-## 5. 监控与告警
-
-### 5.1 灰度监控
-
-```yaml
-# Prometheus 指标
-http_requests_total{version="v1", status="200"}  1000
-http_requests_total{version="v2", status="200"}  50     # 灰度中
-http_requests_total{version="v2", status="500"}  10     # 错误率 20%
-```
-
-### 5.2 告警阈值
-
-```yaml
-# 灰度 v2 错误率 > 5% → 自动回滚
-- alert: GrayVersionHighErrorRate
-  condition: rate(http_requests_total{version="v2", status="500"}[5m]) > 0.05
-  action: rollback_to_v1
-```
-
-## 6. ❌ 反模式
-
-### 6.1 ❌ 全量上线
-
-```bash
-# ❌ 错：直接全量推 → 出问题全部用户受影响
-rsync dist/ user@app:/var/www/app/
-```
-
-✅ 先灰度 5% → 监控 → 推全。
-
-### 6.2 ❌ 无回滚预案
-
-```bash
-# ❌ 错：上线后没准备回滚方案
-```
-
-✅ 保留历史版本 + 回滚脚本 + 数据库兼容。
-
-### 6.3 ❌ 数据库变更与版本不兼容
-
-```sql
--- ❌ 错：新版本加非空列，旧版本报错
-ALTER TABLE t_order ADD COLUMN new_field INT NOT NULL;
-```
-
-✅ 加 nullable，或拆多次上线。
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — 前端部署基础
-- [cdn-https-cache.md](cdn-https-cache.md) — CDN + HTTPS + 缓存
-- [SKILL.md](../SKILL.md)

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

@@ -1,199 +0,0 @@
-# 前端部署基础指南（frontend-deploy）
-
-> 构建 / Nginx 反向代理 / 静态资源。
-
----
-
-## 1. 构建
-
-### 1.1 构建命令
-
-```bash
-# Vite
-npm run build
-
-# 产物输出到 dist/
-# - index.html（不缓存）
-# - assets/js/*.js（hash 文件名，长缓存）
-# - assets/css/*.css（hash 文件名，长缓存）
-# - assets/img/*（hash 文件名，长缓存）
-```
-
-### 1.2 环境变量
-
-```bash
-# .env.production
-VITE_API_BASE_URL=https://api.example.com
-VITE_APP_TITLE=MeritData
-VITE_USE_CDN=true
-```
-
-构建时注入到 bundle。
-
-### 1.3 构建优化
-
-```typescript
-// vite.config.ts
-export default defineConfig({
-  build: {
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          'react-vendor': ['react', 'react-dom'],
-          'antd-vendor': ['antd'],
-          'platform-vendor': ['@meritdata/platform-ui-components'],
-        },
-      },
-    },
-    chunkSizeWarningLimit: 1500,
-  },
-});
-```
-
-分包 → 首屏加载更快。
-
-## 2. Nginx 配置
-
-### 2.1 基础配置
-
-```nginx
-server {
-    listen 80;
-    server_name app.example.com;
-
-    root /var/www/app/dist;
-    index index.html;
-
-    # SPA fallback（所有路径回 index.html）
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # API 反向代理
-    location /api/ {
-        proxy_pass http://backend.example.com/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        proxy_connect_timeout 30s;
-        proxy_read_timeout 60s;
-        proxy_send_timeout 60s;
-    }
-
-    # 静态资源（长缓存）
-    location /assets/ {
-        expires 1y;
-        add_header Cache-Control "public, immutable";
-        access_log off;
-    }
-
-    # HTML 不缓存
-    location = /index.html {
-        add_header Cache-Control "no-cache, no-store, must-revalidate";
-        expires 0;
-    }
-}
-```
-
-### 2.2 Gzip / Brotli
-
-```nginx
-gzip on;
-gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
-gzip_min_length 1000;
-
-# Brotli（需编译 brotli 模块）
-brotli on;
-brotli_types text/plain text/css application/json application/javascript;
-```
-
-### 2.3 HTTPS
-
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name app.example.com;
-
-    ssl_certificate     /etc/nginx/ssl/app.crt;
-    ssl_certificate_key /etc/nginx/ssl/app.key;
-    ssl_protocols       TLSv1.2 TLSv1.3;
-    ssl_ciphers         HIGH:!aNULL:!MD5;
-
-    # 其他配置同 80 端口
-}
-
-# 80 → 443 重定向
-server {
-    listen 80;
-    server_name app.example.com;
-    return 301 https://$server_name$request_uri;
-}
-```
-
-## 3. 部署流程
-
-```bash
-# 1. 构建
-npm run build
-
-# 2. 上传到服务器
-rsync -avz dist/ user@app.example.com:/var/www/app/dist/
-
-# 3. Nginx 重新加载（无需重启）
-ssh user@app.example.com 'nginx -s reload'
-
-# 或用 docker
-docker build -t app:v1.2.3 .
-docker push registry.example.com/app:v1.2.3
-```
-
-## 4. ❌ 反模式
-
-### 4.1 ❌ HTML 缓存
-
-```nginx
-# ❌ 错
-location / {
-    expires 1d;  # HTML 也缓存 → 部署新版本用户看不到
-}
-```
-
-✅ HTML 不缓存，静态资源长缓存。
-
-### 4.2 ❌ 静态资源不缓存
-
-```nginx
-# ❌ 错
-location /assets/ {
-    expires off;  # 每次都重新下载
-}
-```
-
-✅ 长缓存 + immutable。
-
-### 4.3 ❌ 反向代理超时太短
-
-```nginx
-# ❌ 错
-proxy_read_timeout 5s;  # 慢请求直接断
-```
-
-✅ 60s + 业务超时控制。
-
-### 4.4 ❌ API 跨域硬编码
-
-```javascript
-// ❌ 错
-fetch('http://backend.example.com/api/orders')
-// → 跨域
-```
-
-✅ Nginx 反向代理，前端同源。
-
-## 5. 关联阅读
-
-- [cdn-https-cache.md](cdn-https-cache.md) — CDN + HTTPS + 缓存
-- [gray-and-rollback.md](gray-and-rollback.md) — 灰度 + 回滚
-- [SKILL.md](../SKILL.md)