@umacloud/knowledge 1.0.1

package/cicd/01-standards/deployment-and-delivery-standard.md

@@ -0,0 +1,96 @@
+---
+id: deployment-and-delivery-standard
+title: 部署与交付规范（商业级必读）
+domain: cicd
+category: 01-standards
+difficulty: intermediate
+tags: [部署, 交付, deployment, ci, cd, dockerfile, 多阶段, 蓝绿, 金丝雀, 回滚, rollback, 零停机, 迁移, 环境, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 部署与交付规范（商业级必读）
+
+> 能跑通 ≠ 能交付。商业级项目要可重复构建、自动化流水线、零停机部署、一键回滚、环境隔离。这是从"demo"到"上线产品"的关键一段。
+
+## 1. 容器化（Dockerfile）
+
+- **多阶段构建**：build 阶段装依赖/编译，运行阶段只拷产物 → 镜像小、攻击面小。
+- 基础镜像用**小而固定版本**（`node:20-slim`、`python:3.12-slim`、distroless），不用 `latest`。
+- **非 root 运行**：建专用用户，`USER app`，不用 root。
+- 善用层缓存：先拷依赖清单装依赖，再拷源码（改代码不重装依赖）。
+- `.dockerignore` 排除 node_modules/.git/test 等；不把密钥/`.env` 打进镜像。
+- 声明 `HEALTHCHECK`、`EXPOSE`、合理的启动命令（前台进程、正确处理信号）。
+
+## 2. CI 流水线（每次 PR/push 自动）
+
+标准顺序，任一步失败即**阻断合并**：
+```
+checkout → 装依赖(带缓存) → lint/format 检查 → 类型检查 → 单元+集成测试 →
+构建 → 安全扫描(依赖审计/SAST/镜像扫描) → 质量门 → 产出制品
+```
+- 测试与质量门失败必须红、阻断；不允许"重跑就过"的 flaky 长期存在。
+- 依赖漏洞扫描（npm audit / pip-audit / cargo audit / trivy）纳入流水线。
+- 制品/镜像打**不可变版本标签**（git sha / 语义版本），不用 `latest` 部署。
+
+## 3. CD 部署策略（零停机）
+
+- **滚动更新 Rolling**：逐批替换，配合就绪探针，默认零停机。
+- **蓝绿 Blue-Green**：新版整套起好、切流量、有问题秒切回——回滚最快。
+- **金丝雀 Canary**：先放小比例流量验证指标，再逐步放量。
+- 部署期间新旧版本可能并存 → 接口与数据库必须**向后兼容**（见 §4）。
+- 所有部署经流水线，**禁止手动 ssh 改生产**。
+
+## 4. 数据库迁移与零停机
+
+- 迁移作为部署的一步，**自动执行**且幂等、可回滚。
+- 破坏性 schema 变更走 **expand-contract**（加列→双写→回填→切读→删旧），分多次发布，避免与并存的旧版本不兼容。
+- 大表 DDL 用在线方式、回填分批，别锁表停服。
+
+## 5. 环境与配置/密钥
+
+- 至少 dev / staging / prod 三套环境，**同一份代码 + 不同配置**（12-Factor）。
+- 配置/密钥按环境注入（env / 密钥管理 / CI secrets），**绝不进仓库、不进镜像、不进日志**。
+- staging 尽量贴近 prod；上 prod 前在 staging 验证。
+
+## 6. 回滚与发布安全
+
+- **一键回滚**：保留上一个可用版本，出问题能快速切回（蓝绿/旧镜像重部署）。
+- 发布后盯关键指标（错误率、p99、支付成功率）；异常自动/手动回滚。
+- 高风险变更用 feature flag 灰度，可不发版即关闭。
+- 重要发布避开高峰；有发布记录与可观测。
+
+## 7. 健康检查与运行时
+
+- liveness / readiness 探针；readiness 未就绪不接流量。
+- 优雅停机：SIGTERM 后停接新请求、处理完在途、释放资源再退出。
+- 资源 requests/limits 合理；崩溃自动重启；日志到 stdout 由平台收集。
+
+## 8. 交付物完备（商业项目应随附）
+
+- `Dockerfile`(多阶段、非root) + `docker-compose`(本地一键起 app+db) 或 k8s 清单。
+- CI 配置（lint+test+scan+构建+质量门）。
+- 数据库迁移脚本。
+- `.env.example`（列全变量、占位值）。
+- README：本地启动、环境变量、部署步骤、回滚方式。
+
+## 9. 反模式（出现即不合格）
+
+- 单阶段大镜像、root 运行、用 `latest` 部署。
+- 手动 ssh 改生产、无流水线、无版本制品。
+- 部署停服（无滚动/蓝绿）；破坏性迁移直接上导致旧版本崩。
+- 密钥进镜像/仓库/日志；prod 与 dev 同配置。
+- 无回滚方案；发布后不看指标。
+
+## 10. 最低交付 checklist
+
+- [ ] 多阶段、固定版本、非 root 的 Dockerfile + .dockerignore + HEALTHCHECK。
+- [ ] CI：lint+类型+单元+集成+安全扫描+质量门，失败阻断合并；制品打不可变版本。
+- [ ] CD：滚动/蓝绿/金丝雀之一，零停机；禁止手改生产。
+- [ ] 迁移自动化、幂等、expand-contract、向后兼容、不锁表停服。
+- [ ] dev/staging/prod 环境隔离，配置/密钥按环境注入不入仓库。
+- [ ] 一键回滚 + 发布后指标监控；健康探针 + 优雅停机。
+- [ ] 随附 Dockerfile/compose、CI、迁移、.env.example、部署 README。
+
+---
+**参考**：12-Factor App、Docker 多阶段构建最佳实践、蓝绿/金丝雀部署、Expand-Contract 迁移、Google SRE 发布工程。

package/cicd/01-standards/github-actions-complete.md

@@ -0,0 +1,473 @@
+---
+id: github-actions-complete
+title: GitHub Actions 完整指南
+domain: cicd
+category: 01-standards
+difficulty: intermediate
+tags: [actions, agent, changes, checklist, cicd, complete, github, 安全最佳实践]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# GitHub Actions 完整指南
+
+## 概述
+
+GitHub Actions 是 GitHub 原生的 CI/CD 平台，允许直接在仓库中定义自动化工作流。通过 YAML 文件配置，支持构建、测试、部署、发布等全生命周期自动化。
+
+### 核心优势
+
+- **原生集成**: 与 GitHub 深度集成，无需额外工具
+- **丰富市场**: 16000+ 社区 Actions 可复用
+- **矩阵构建**: 并行测试多个环境/版本
+- **自托管 Runner**: 支持自定义执行环境
+- **免费额度**: 公开仓库免费，私有仓库 2000 分钟/月
+
+---
+
+## 核心概念
+
+### Workflow 结构
+
+```yaml
+# .github/workflows/ci.yml
+name: CI Pipeline          # 工作流名称
+
+on:                         # 触发条件
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 2 * * 1'    # 每周一凌晨2点
+  workflow_dispatch:         # 手动触发
+    inputs:
+      environment:
+        description: 'Deploy environment'
+        required: true
+        default: 'staging'
+        type: choice
+        options: [staging, production]
+
+env:                         # 全局环境变量
+  NODE_VERSION: '20'
+  PYTHON_VERSION: '3.11'
+
+jobs:                        # 作业定义
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run linter
+        run: npm run lint
+
+  test:
+    needs: lint              # 依赖 lint 完成
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [18, 20, 22]   # 矩阵测试
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm test
+```
+
+### 触发事件详解
+
+```yaml
+on:
+  # Push 事件
+  push:
+    branches: [main, 'release/**']
+    tags: ['v*']
+    paths:
+      - 'src/**'
+      - '!src/**/*.test.ts'  # 排除测试文件
+
+  # PR 事件
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+
+  # 定时任务
+  schedule:
+    - cron: '30 5 * * 1-5'   # 工作日 5:30 UTC
+
+  # 其他仓库事件
+  issues:
+    types: [opened, labeled]
+  release:
+    types: [published]
+  workflow_run:
+    workflows: ["Build"]
+    types: [completed]
+```
+
+---
+
+## 实战模板
+
+### 1. Python CI/CD
+
+```yaml
+name: Python CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7
+        ports: ['6379:6379']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+          black --check .
+          mypy src/
+
+      - name: Test
+        env:
+          DATABASE_URL: postgresql://postgres:test@localhost:5432/testdb
+          REDIS_URL: redis://localhost:6379
+        run: |
+          pytest --cov=src --cov-report=xml -v
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+
+  deploy:
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: production
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy
+        env:
+          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+        run: |
+          echo "Deploying to production..."
+```
+
+### 2. Node.js + Docker 构建
+
+```yaml
+name: Build & Push Docker
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+### 3. 矩阵构建 + 跨平台
+
+```yaml
+name: Cross-Platform Build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: [18, 20]
+        include:
+          - os: ubuntu-latest
+            node: 20
+            coverage: true
+        exclude:
+          - os: windows-latest
+            node: 18
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm test
+      - name: Coverage
+        if: matrix.coverage
+        run: npm run test:coverage
+```
+
+### 4. 自动化发布
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -n "$PREV_TAG" ]; then
+            CHANGELOG=$(git log ${PREV_TAG}..HEAD --pretty=format:"- %s (%h)" --no-merges)
+          else
+            CHANGELOG=$(git log --pretty=format:"- %s (%h)" --no-merges -20)
+          fi
+          echo "changelog<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: |
+            ## Changes
+            ${{ steps.changelog.outputs.changelog }}
+          draft: false
+          prerelease: ${{ contains(github.ref, '-rc') }}
+```
+
+---
+
+## 高级技巧
+
+### Secrets 管理
+
+```yaml
+# 在 Settings → Secrets and variables → Actions 中设置
+env:
+  API_KEY: ${{ secrets.API_KEY }}
+  DATABASE_URL: ${{ secrets.DATABASE_URL }}
+
+# 环境级 Secrets (需要审批)
+jobs:
+  deploy:
+    environment:
+      name: production
+      url: https://myapp.com
+    steps:
+      - run: echo "Using ${{ secrets.PROD_API_KEY }}"
+```
+
+### 缓存优化
+
+```yaml
+# pip 缓存
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.11'
+    cache: 'pip'
+
+# npm 缓存
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    cache: 'npm'
+
+# 自定义缓存
+- uses: actions/cache@v4
+  with:
+    path: |
+      ~/.cargo/registry
+      ~/.cargo/git
+      target/
+    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+    restore-keys: |
+      ${{ runner.os }}-cargo-
+```
+
+### 可复用工作流
+
+```yaml
+# .github/workflows/reusable-test.yml
+name: Reusable Test
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: true
+        type: string
+    secrets:
+      codecov-token:
+        required: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+      - run: pytest
+
+# 调用方
+# .github/workflows/ci.yml
+jobs:
+  test:
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      python-version: '3.11'
+    secrets:
+      codecov-token: ${{ secrets.CODECOV_TOKEN }}
+```
+
+### 条件执行
+
+```yaml
+steps:
+  # 只在 main 分支执行
+  - if: github.ref == 'refs/heads/main'
+    run: echo "On main branch"
+
+  # 只在 PR 中执行
+  - if: github.event_name == 'pull_request'
+    run: echo "In PR"
+
+  # 前一步成功才执行
+  - if: success()
+    run: echo "Previous step succeeded"
+
+  # 前一步失败时执行
+  - if: failure()
+    run: echo "Previous step failed"
+
+  # 总是执行 (清理)
+  - if: always()
+    run: echo "Always runs"
+
+  # 包含特定标签
+  - if: contains(github.event.pull_request.labels.*.name, 'deploy')
+    run: echo "Has deploy label"
+```
+
+---
+
+## 安全最佳实践
+
+1. **✅ 最小权限**: 使用 `permissions` 限制 GITHUB_TOKEN 权限
+2. **✅ 固定版本**: 使用 `actions/checkout@v4` 而非 `@main`
+3. **✅ 审查第三方 Actions**: 检查源码，使用 SHA 固定版本
+4. **✅ 保护 Secrets**: 不在日志中打印，使用环境级 Secrets
+5. **✅ 保护分支**: 要求 PR 审查和状态检查通过
+6. **❌ 不要**: 在 PR 中运行不受信任的代码（`pull_request_target`风险）
+7. **❌ 不要**: 硬编码密钥在工作流文件中
+
+---
+
+## Agent Checklist
+
+Agent 在配置 CI/CD 时必须检查:
+
+- [ ] 工作流是否覆盖 lint/test/build/deploy 全流程？
+- [ ] 是否使用矩阵测试覆盖多版本？
+- [ ] Secrets 是否通过 GitHub Secrets 管理（非硬编码）？
+- [ ] 是否配置缓存优化构建速度？
+- [ ] Docker 构建是否使用多阶段构建和缓存？
+- [ ] 生产部署是否需要环境审批？
+- [ ] 是否有自动化发布流程（tag触发）？
+- [ ] Actions 版本是否固定（SHA或major版本）？
+- [ ] 工作流权限是否遵循最小权限原则？
+- [ ] 是否有失败通知机制？
+
+---
+
+**文档版本**: v1.0
+**最后更新**: 2026-03-28
+**质量评分**: 90/100

package/cicd/01-standards/release-and-store-submission.md

@@ -0,0 +1,75 @@
+---
+id: release-and-store-submission
+title: 发布与上架审核标准（多端 · 商业级）
+domain: cicd
+category: 01-standards
+difficulty: intermediate
+tags: [发布, 上架, 审核, app-store, google-play, 华为, 微信小程序, 公证, 隐私, 合规, 提审, 发布, 商业级]
+quality_score: 92
+last_updated: 2026-06-19
+---
+
+# 发布与上架审核标准（多端 · 商业级）
+
+> "做完"不等于"能上架"。各平台审核严格，缺隐私声明、权限说明、资质就被拒。本标准给出各端上架前的硬性 checklist，避免反复被拒。
+
+## 1. 通用（所有端）
+
+- **隐私政策 + 用户协议** 可访问；明确收集了什么数据、用途、第三方 SDK。
+- 权限**按需 + 说明用途**；删除未使用的权限/SDK（多余权限是被拒常见原因）。
+- 内容合规（无违规/侵权/敏感内容）；版本号/构建号规范；崩溃率达标。
+- 各环境配置正确（生产 API、密钥、关闭调试日志）。
+
+## 2. iOS / App Store
+
+- **App Privacy（隐私营养标签）** 如实填写数据收集；如有跟踪需 **ATT (App Tracking Transparency)** 弹窗。
+- 权限在 `Info.plist` 配 **用途说明文案(Usage Description)**，缺了直接崩/拒。
+- 不下发可执行代码/不绕过审核；用 IAP 卖数字内容（不能用三方支付绕苹果分成）。
+- 截图/预览/描述合规；测试账号给审核；支持最新系统与机型；适配深色/动态字体。
+- 证书/描述文件/签名正确；构建用正式证书。
+
+## 3. Android / Google Play & 华为应用市场
+
+- **数据安全表单(Data Safety)** 如实填；目标 API level 满足最新要求；64 位支持。
+- 权限敏感(定位/短信/通讯录等)需说明与合理性；前台服务/精确闹钟等受限权限需符合政策。
+- 用 **App Bundle (.aab)** 上传；签名(Play App Signing)；混淆/资源压缩。
+- 华为应用市场：额外资质(类目)、隐私、HMS(如用推送)适配；鸿蒙单独提审。
+
+## 4. 微信小程序 / 各小程序
+
+- 类目**资质**齐全（如电商/医疗/金融需对应资质）；服务器域名 **HTTPS + 白名单**配置。
+- 隐私协议 + 用户授权弹窗合规；遵守诱导分享/虚拟支付等运营规范。
+- 体验评分(性能/可用性)达标；提审填写完整、测试账号、功能页路径。
+- 包大小符合限制(主包/分包)。
+
+## 5. 桌面应用
+
+- **代码签名**：Windows 代码签名证书；**macOS 签名 + 公证(notarization)** + Gatekeeper 通过（不签名用户装不上/报毒）。
+- Linux 多发行版打包(AppImage/Flatpak/deb/rpm)。
+- 自动更新签名校验；安装包来源可信(HTTPS)。
+
+## 6. Web
+
+- 生产构建(压缩/Tree-shaking/source map 处理)；环境变量/密钥正确不泄漏。
+- HTTPS + 安全头(CSP/HSTS)；SEO 基础(sitemap/robots/meta)；监控与告警接好。
+- 回滚预案；灰度/蓝绿；健康检查。
+
+## 7. 反模式（出现即不合格）
+
+- 缺隐私政策/权限说明/数据安全表单 → 必被拒。
+- iOS 缺 Usage Description（崩溃）/用三方支付卖数字内容/有跟踪不弹 ATT。
+- Android 不用 aab/目标 API 过低/敏感权限无理由。
+- 小程序无资质/域名未配白名单/诱导分享。
+- 桌面不签名不公证；生产泄漏密钥/开调试。
+
+## 8. 最低交付 checklist（提审前）
+
+- [ ] 通用：隐私政策+协议、权限按需+说明、删多余权限/SDK、内容合规、生产配置正确。
+- [ ] iOS：App Privacy + ATT(如需) + Info.plist 用途说明 + IAP + 截图/测试账号 + 正式签名。
+- [ ] Android：Data Safety + 目标 API + aab 签名 + 敏感权限说明；华为/鸿蒙单独资质提审。
+- [ ] 小程序：类目资质 + 域名白名单 + 隐私授权合规 + 体验达标 + 包大小。
+- [ ] 桌面：Win 签名 + macOS 签名公证 + 多发行版打包 + 更新签名校验。
+- [ ] Web：生产构建 + 安全头 + SEO + 监控告警 + 回滚/灰度 + 健康检查。
+
+---
+**参考（官方）**：App Store Review Guidelines、Google Play 政策、华为应用市场审核、微信小程序审核规范、macOS 公证、Google Search Central。