universal-dev-standards 5.2.0 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,65 @@
1
+ # Release Option: GitHub Actions Publish Mode - AI Optimized
2
+ # Parent: release-standards
3
+ # Source: options/release/publish-mode-github-actions.md
4
+
5
+ id: publish-mode-github-actions
6
+ meta:
7
+ parent: release-standards
8
+ version: "1.0.0"
9
+ updated: "2026-04-24"
10
+ source: options/release/publish-mode-github-actions.md
11
+ description: CD publish pattern for npm packages — publish is triggered automatically by GitHub Release, not by manual `npm publish`
12
+
13
+ best_for:
14
+ - npm packages hosted in GitHub repositories
15
+ - Projects with GitHub Actions publish workflow (publish.yml or similar)
16
+ - Single-owner or small-team repos using GitHub Actions CD
17
+ - Projects where NPM_TOKEN is stored as a GitHub Actions secret
18
+
19
+ configuration:
20
+ publish_mode: github-actions
21
+ publish_trigger: gh_release_create
22
+ publish_command: none # npm publish is handled by GitHub Actions
23
+ tag_format: "v{semver}"
24
+
25
+ behaviors:
26
+ release_finish_sequence:
27
+ steps:
28
+ - bump_version # scripts/bump-version.sh or npm version
29
+ - update_changelog # add [X.Y.Z] section, remove from [Unreleased]
30
+ - commit_and_tag # git commit + git tag vX.Y.Z
31
+ - push_with_tag # git push origin main vX.Y.Z
32
+ - create_gh_release # gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
33
+ note: >
34
+ DO NOT run `npm publish` manually. The `gh release create` command triggers
35
+ the publish workflow via `release: published` event. GitHub Actions handles
36
+ the actual npm publish using NPM_TOKEN stored as a repository secret.
37
+
38
+ gh_release_create:
39
+ command: 'gh release create v{version} --title "v{version}" --notes "{changelog_entry}"'
40
+ triggers: publish_workflow
41
+ publishes_to_npm_tag:
42
+ stable: latest # versions without pre-release suffix (e.g. 5.2.0)
43
+ prerelease: next # versions with beta/alpha/rc suffix (e.g. 5.2.0-beta.1)
44
+
45
+ publish_workflow:
46
+ trigger_event: "release: published"
47
+ secret_required: NPM_TOKEN
48
+ runs_on: github_actions
49
+ note: >
50
+ Workflow file is typically `.github/workflows/publish.yml`.
51
+ It runs `npm publish` with `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
52
+
53
+ local_verification:
54
+ before_release:
55
+ - run_tests # npm test / vitest
56
+ - verify_build # npm run build (if applicable)
57
+ - check_version # confirm package.json version matches intended tag
58
+ note: All local gates must pass before `gh release create`
59
+
60
+ comparison_with_manual_mode:
61
+ publish_command: "not run locally" # manual: npm publish
62
+ publish_trigger: gh_release_create # manual: direct npm publish
63
+ npm_token_location: github_secret # manual: local .npmrc or env var
64
+ audit_trail: github_actions_log # manual: none (local terminal)
65
+ reproducibility: full_ci_isolation # manual: depends on local environment
@@ -0,0 +1,73 @@
1
+ # CD Deployment Strategies (AI-Optimized v1)
2
+ # Source: core/cd-deployment-strategies.md
3
+
4
+ standard:
5
+ id: cd-deployment-strategies
6
+ name: CD Deployment Strategies
7
+ description: Strategy selection matrix for blue-green, canary, rolling, and recreate deployments
8
+ guidelines:
9
+ - "Choose strategy based on: traffic volume × risk tolerance × infrastructure cost"
10
+ - "High traffic + low risk tolerance → blue-green (instant rollback)"
11
+ - "Medium traffic + medium risk → canary (progressive validation)"
12
+ - "Low traffic + low risk → rolling (resource efficient)"
13
+ - "Dev/internal only → recreate (simplest, acceptable downtime)"
14
+ - "Never deploy directly to production without staging validation"
15
+
16
+ meta:
17
+ version: "1.0.0"
18
+ updated: "2026-04-26"
19
+ source: core/cd-deployment-strategies.md
20
+ parent: deployment-standards.ai.yaml
21
+
22
+ strategy_matrix:
23
+ blue_green:
24
+ traffic: high
25
+ risk_tolerance: low
26
+ infrastructure_cost: high
27
+ downtime: zero
28
+ rollback_time: "<30s"
29
+ use_cases: ["stateful services", "database-compatible changes", "high-SLA APIs"]
30
+ prerequisites: ["dual environment", "load balancer", "health checks"]
31
+ canary:
32
+ traffic: medium_to_high
33
+ risk_tolerance: medium
34
+ infrastructure_cost: medium
35
+ downtime: zero
36
+ rollback_time: "<2min"
37
+ use_cases: ["feature validation", "A/B testing", "high-risk changes"]
38
+ traffic_stages: ["1%", "5%", "25%", "50%", "100%"]
39
+ prerequisites: ["traffic splitting", "observability", "auto-promotion rules"]
40
+ rolling:
41
+ traffic: any
42
+ risk_tolerance: medium
43
+ infrastructure_cost: low
44
+ downtime: minimal
45
+ rollback_time: "minutes"
46
+ use_cases: ["stateless services", "standard updates", "batch workers"]
47
+ prerequisites: ["multiple instances", "health checks"]
48
+ recreate:
49
+ traffic: low
50
+ risk_tolerance: high
51
+ infrastructure_cost: minimal
52
+ downtime: "seconds to minutes"
53
+ rollback_time: "minutes"
54
+ use_cases: ["dev/staging", "internal tools", "single-instance services"]
55
+ prerequisites: ["none"]
56
+
57
+ decision_tree:
58
+ step_1: "Is zero-downtime required? No → recreate; Yes → continue"
59
+ step_2: "Is traffic > 10k req/min? Yes → blue-green or canary; No → rolling"
60
+ step_3: "Is change high-risk? Yes → canary; No → blue-green or rolling"
61
+ step_4: "Is infrastructure budget constrained? Yes → rolling; No → blue-green"
62
+
63
+ no_cicd_compatibility:
64
+ blue_green: "See no-cicd-deployment.ai.yaml for script-based implementation"
65
+ canary: "Requires Nginx split_clients or HAProxy for script-based canary"
66
+ rolling: "Achievable with sequential rsync + health check loop"
67
+ recreate: "Simplest — stop, deploy, start"
68
+
69
+ physical_spec:
70
+ type: custom_script
71
+ validator:
72
+ command: "grep -r 'deployment_strategy\\|deploy.*strategy' . --include='*.yaml' --include='*.json' -l 2>/dev/null | head -1"
73
+ rule: "deployment_strategy_documented"
@@ -0,0 +1,134 @@
1
+ # No-CI/CD Deployment Strategy (AI-Optimized v1)
2
+ # Source: core/no-cicd-deployment.md
3
+
4
+ standard:
5
+ id: no-cicd-deployment
6
+ name: No-CI/CD Deployment Strategy
7
+ description: Reliable deployment without CI/CD platforms using shell scripts, smoke tests, Blue-Green switching, and deploy.lock protection
8
+ guidelines:
9
+ - "Use set -euo pipefail in all deploy scripts — fail fast, stop on first error"
10
+ - "Always verify deployment after completion — check version endpoint, never assume success"
11
+ - "Maintain Blue-Green slots for instant rollback — recovery time must be <30 seconds"
12
+ - "Enforce deploy.lock to prevent concurrent deployments"
13
+ - "Only deploy commits with semantic version tags — no untagged HEAD deployments"
14
+ - "Log every deployment with timestamp, version, operator, and result (JSON Lines)"
15
+
16
+ meta:
17
+ version: "1.0.0"
18
+ updated: "2026-04-26"
19
+ source: core/no-cicd-deployment.md
20
+ description: Reliable deployment strategy for environments without CI/CD platforms
21
+ complements: deployment-standards.ai.yaml
22
+
23
+ principles:
24
+ core:
25
+ - fail_fast: "set -euo pipefail stops execution at first failure — no silent partial deploys"
26
+ - verify_always: "Post-deploy smoke test is mandatory, not optional"
27
+ - instant_recovery: "Blue-Green rollback must complete in <30 seconds"
28
+ - concurrent_protection: "deploy.lock prevents race conditions from simultaneous deployments"
29
+ - version_discipline: "Only semver-tagged commits are deployable"
30
+ - audit_trail: "Every deploy produces a machine-readable log entry"
31
+
32
+ architecture:
33
+ three_layer:
34
+ layer_1_prevent:
35
+ name: "Prevent Wrong Deployments"
36
+ mechanisms:
37
+ - "set -euo pipefail in deploy.sh"
38
+ - "Mandatory test pass before deploy"
39
+ - "Semver tag enforcement"
40
+ - "deploy.lock concurrency guard"
41
+ layer_2_verify:
42
+ name: "Verify Deployment Correctness"
43
+ mechanisms:
44
+ - "HTTP /health endpoint check"
45
+ - "Version number comparison with VERSION file"
46
+ - "Auto-rollback on verification failure"
47
+ layer_3_recover:
48
+ name: "Fast Recovery Capability"
49
+ mechanisms:
50
+ - "Blue-Green slot switching"
51
+ - "Nginx upstream pointer swap"
52
+ - "Single-command rollback.sh"
53
+
54
+ deploy_script:
55
+ required_header: "#!/usr/bin/env bash\nset -euo pipefail"
56
+ mandatory_steps:
57
+ - step: test
58
+ order: 1
59
+ description: "Run full test suite before any deployment"
60
+ - step: build
61
+ order: 2
62
+ description: "Produce deployment artifact"
63
+ - step: deploy
64
+ order: 3
65
+ description: "Transfer artifact to target server"
66
+ - step: verify
67
+ order: 4
68
+ description: "Run smoke test; auto-rollback on failure"
69
+ lock_pattern:
70
+ file: "/tmp/deploy.lock"
71
+ create: "echo $$ > $LOCK_FILE"
72
+ cleanup: "trap 'rm -f $LOCK_FILE' EXIT"
73
+ check: "[ -f $LOCK_FILE ] && echo 'Deploy in progress' && exit 1"
74
+ version_enforcement:
75
+ command: "git describe --exact-match --tags HEAD"
76
+ format: "v[0-9]+\\.[0-9]+\\.[0-9]+"
77
+ failure_message: "No semver tag on HEAD — tag before deploying"
78
+
79
+ smoke_test:
80
+ endpoint: "/health"
81
+ required_fields:
82
+ - field: "version"
83
+ source: "VERSION file"
84
+ comparison: "exact match"
85
+ - field: "status"
86
+ expected: "ok"
87
+ failure_action: "auto_rollback"
88
+ timeout_seconds: 30
89
+
90
+ blue_green:
91
+ slots:
92
+ - name: blue
93
+ port: 3001
94
+ state: "active (stable)"
95
+ - name: green
96
+ port: 3002
97
+ state: "inactive (staging)"
98
+ switch_mechanism: "nginx upstream pointer"
99
+ rollback_time_sla: "30 seconds"
100
+ rollback_command: "./rollback.sh"
101
+
102
+ deployment_log:
103
+ format: "JSON Lines"
104
+ required_fields:
105
+ - "timestamp (ISO 8601)"
106
+ - "version"
107
+ - "git_commit"
108
+ - "operator (whoami)"
109
+ - "result (success|failure)"
110
+ - "duration_seconds"
111
+ location: "/var/log/deployments.jsonl"
112
+
113
+ checklist:
114
+ pre_deploy:
115
+ - "Tests pass"
116
+ - "Artifact built successfully"
117
+ - "No deploy.lock present"
118
+ - "HEAD has semver tag"
119
+ - "Previous deployment log reviewed"
120
+ post_deploy:
121
+ - "Health check HTTP 200"
122
+ - "Version matches expected"
123
+ - "Service responds to basic requests"
124
+ - "Deployment log entry written"
125
+ rollback_readiness:
126
+ - "Blue slot running previous stable version"
127
+ - "rollback.sh tested and functional"
128
+ - "Nginx upstream reload works"
129
+
130
+ physical_spec:
131
+ type: custom_script
132
+ validator:
133
+ command: "test -f deploy.sh && grep -q 'set -euo pipefail' deploy.sh && test -f rollback.sh && test -f verify.sh"
134
+ rule: "no_cicd_deployment_scripts_configured"
@@ -0,0 +1,71 @@
1
+ # Pipeline Security Gates (AI-Optimized v1)
2
+ # Source: core/pipeline-security-gates.md
3
+
4
+ standard:
5
+ id: pipeline-security-gates
6
+ name: Pipeline Security Gates
7
+ description: Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan with block/warn/log behavior
8
+ guidelines:
9
+ - "Secrets scan at pre-commit — block ALL commits containing secrets"
10
+ - "SAST after build — block Critical/High findings"
11
+ - "SCA + SBOM generation at package stage"
12
+ - "DAST after staging deploy — warn on findings, require approval for Critical"
13
+ - "Never skip security gates with --force or emergency bypass without audit trail"
14
+ - "Treat security gate failures as pipeline failures, not warnings"
15
+
16
+ meta:
17
+ version: "1.0.0"
18
+ updated: "2026-04-26"
19
+ source: core/pipeline-security-gates.md
20
+ complements: security-standards.ai.yaml
21
+
22
+ gate_positions:
23
+ pre_commit:
24
+ type: secrets_scan
25
+ tools: ["gitleaks", "trufflehog", "detect-secrets"]
26
+ scope: "staged files"
27
+ block_on: ["any secret pattern match"]
28
+ never_skip: true
29
+ post_build:
30
+ type: sast
31
+ tools: ["semgrep", "codeql", "sonarqube"]
32
+ scope: "source code + build output"
33
+ block_on: ["Critical", "High"]
34
+ warn_on: ["Medium"]
35
+ log_only: ["Low", "Info"]
36
+ post_staging_deploy:
37
+ type: dast
38
+ tools: ["zap", "nuclei", "burpsuite-enterprise"]
39
+ scope: "running staging application"
40
+ block_on: ["Critical"]
41
+ require_approval: ["High"]
42
+ warn_on: ["Medium"]
43
+ package_stage:
44
+ type: sca_and_sbom
45
+ tools: ["trivy", "syft", "grype", "dependabot"]
46
+ scope: "dependencies + container image"
47
+ block_on: ["Critical CVE with fix available"]
48
+ warn_on: ["High CVE", "outdated dependencies"]
49
+ sbom_format: ["spdx", "cyclonedx"]
50
+
51
+ bypass_policy:
52
+ allowed: false
53
+ exception_process: "written security approval + audit log entry"
54
+ emergency_bypass: "time-limited token + mandatory post-incident review"
55
+
56
+ failure_behavior:
57
+ Critical: {action: "block pipeline", notify: "security-team", sla: "immediate"}
58
+ High: {action: "block pipeline", notify: "team-lead", sla: "same-day"}
59
+ Medium: {action: "warn + require approval", notify: "developer", sla: "next-sprint"}
60
+ Low: {action: "log only", notify: "none", sla: "backlog"}
61
+
62
+ integration_points:
63
+ secrets_vault: "Integrate with HashiCorp Vault or AWS Secrets Manager for secrets injection"
64
+ sbom_registry: "Upload SBOM to dependency-track or grype-db for continuous monitoring"
65
+ incident_response: "Critical findings automatically create incident tickets"
66
+
67
+ physical_spec:
68
+ type: custom_script
69
+ validator:
70
+ command: "grep -r 'secrets\\|sast\\|sca\\|dast' .github/workflows/ .gitlab-ci.yml Jenkinsfile 2>/dev/null | head -1 || echo 'no-ci-pipeline'"
71
+ rule: "security_gates_in_pipeline"
@@ -0,0 +1,105 @@
1
+ id: push-standards
2
+ meta:
3
+ version: "1.0.0"
4
+ updated: "2026-04-23"
5
+ source: skills/push/SKILL.md
6
+ description: "Git push safety gates, protected branch detection, force-push guardrails, and push receipt audit trail"
7
+
8
+ config:
9
+ protected_branches:
10
+ default: ["main", "master", "release/*", "hotfix/*"]
11
+ description: "Branches requiring explicit confirmation before push"
12
+
13
+ push_gates:
14
+ default: ["lint", "test"]
15
+ optional: ["ac-coverage", "type-check", "security-scan"]
16
+ description: "Quality gates to run before pushing"
17
+
18
+ receipt:
19
+ output:
20
+ default: "console"
21
+ choices: ["console", "file", "both"]
22
+ file_path: "~/.uds/push-history.jsonl"
23
+
24
+ auto_pr:
25
+ default: true
26
+ description: "Prompt to create PR after pushing to non-protected branch"
27
+
28
+ repo_mode:
29
+ default: "team"
30
+ choices: ["team", "single-owner"]
31
+ description: "single-owner skips PR prompts and reduces collaboration guardrails"
32
+
33
+ rules:
34
+ - id: detect-protected-branch
35
+ trigger: "executing /push"
36
+ priority: required
37
+ instruction: |
38
+ Before pushing, detect the target branch name.
39
+ If the target matches any protected_branches pattern:
40
+ 1. Display a warning with the branch name
41
+ 2. Show what commits will be pushed
42
+ 3. Require explicit user confirmation before proceeding
43
+ 4. If user does not confirm, abort without pushing
44
+
45
+ - id: force-push-guardrail
46
+ trigger: "push with --force flag detected"
47
+ priority: required
48
+ instruction: |
49
+ When force push is detected:
50
+ 1. Calculate commits that will be overwritten on remote
51
+ 2. Show the count and authors of overwritten commits
52
+ 3. Require the user to type a confirmation string (e.g., "yes, force push")
53
+ 4. Record force_push: true in the push receipt
54
+
55
+ - id: pre-push-gates
56
+ trigger: "before executing git push"
57
+ priority: required
58
+ instruction: |
59
+ Run all configured push_gates in sequence:
60
+ - lint: run project lint command (from uds.project.yaml or detected)
61
+ - test: run project test command
62
+ If any gate fails: abort push, display which gate failed, suggest fix.
63
+ If --skip-gates flag: run push without gates, mark gates_skipped: true in receipt.
64
+
65
+ - id: push-receipt
66
+ trigger: "after successful push"
67
+ priority: required
68
+ instruction: |
69
+ Output a structured push receipt containing:
70
+ - branch: target branch name
71
+ - commit_sha: HEAD commit SHA (short)
72
+ - gates_passed: list of gates that ran and passed
73
+ - gates_skipped: boolean
74
+ - force_push: boolean
75
+ - timestamp: ISO 8601 format
76
+ If receipt.output includes "file": append to ~/.uds/push-history.jsonl as JSON line.
77
+
78
+ - id: pr-integration
79
+ trigger: "after successful push to non-protected branch"
80
+ priority: suggested
81
+ instruction: |
82
+ If auto_pr is true AND repo_mode is "team":
83
+ Check if an open PR exists for this branch on the remote.
84
+ If no open PR: prompt user whether to run pr-automation-assistant.
85
+ If user confirms: invoke pr-automation-assistant.
86
+ If auto_pr is false OR repo_mode is "single-owner": skip this step.
87
+
88
+ - id: single-owner-mode
89
+ trigger: "repo_mode: single-owner is configured"
90
+ priority: recommended
91
+ instruction: |
92
+ In single-owner mode, skip all collaboration-specific steps:
93
+ - No PR prompts
94
+ - Reduced force-push warnings (still warn, but no confirmation text required)
95
+ Protected branch detection remains active.
96
+
97
+ schema:
98
+ push_receipt:
99
+ branch: string
100
+ commit_sha: string
101
+ gates_passed: "string[]"
102
+ gates_skipped: boolean
103
+ force_push: boolean
104
+ timestamp: "ISO 8601 string"
105
+ target_remote: string
@@ -0,0 +1,68 @@
1
+ # Rollback Standards (AI-Optimized v1)
2
+ # Source: core/rollback-standards.md
3
+
4
+ standard:
5
+ id: rollback-standards
6
+ name: Rollback Standards
7
+ description: Rollback trigger conditions, auto vs manual decisions, and error budget integration
8
+ guidelines:
9
+ - "Define rollback triggers with measurable thresholds — never subjective 'it looks bad'"
10
+ - "Auto-rollback on error rate > 2× baseline sustained 5 minutes"
11
+ - "Assisted rollback when SLO violated but non-critical"
12
+ - "Manual rollback for latency degradation within SLO bounds"
13
+ - "Error budget < 10% automatically escalates assisted to auto-rollback"
14
+ - "Every rollback event must be logged and trigger incident response flow"
15
+
16
+ meta:
17
+ version: "1.0.0"
18
+ updated: "2026-04-26"
19
+ source: core/rollback-standards.md
20
+ parent: deployment-standards.ai.yaml
21
+
22
+ trigger_conditions:
23
+ auto_rollback:
24
+ error_rate: ">2× baseline sustained 5min"
25
+ health_check_failures: "3 consecutive"
26
+ p99_latency: ">5× baseline sustained 3min"
27
+ assisted_rollback:
28
+ slo_violated: "non-critical path"
29
+ error_budget_remaining: "<10%"
30
+ manual_rollback:
31
+ latency_degraded: "within SLO bounds"
32
+ cosmetic_issues: "user-visible but non-functional"
33
+
34
+ severity_matrix:
35
+ P0: {trigger: auto, timeline: "<2min", notify: "all-hands"}
36
+ P1: {trigger: auto, timeline: "<5min", notify: "on-call"}
37
+ P2: {trigger: assisted, timeline: "<15min", notify: "team-lead"}
38
+ P3: {trigger: manual, timeline: "<1hr", notify: "developer"}
39
+
40
+ error_budget_integration:
41
+ threshold: "10% remaining"
42
+ escalation: "assisted → auto"
43
+ incident_event: true
44
+ pause_deploys: "when budget exhausted"
45
+
46
+ rollback_methods:
47
+ blue_green: {time: "<30s", risk: low, prerequisite: "dual-slot infrastructure"}
48
+ feature_flag: {time: "<5s", risk: minimal, prerequisite: "flag system in place"}
49
+ dns_switch: {time: "60-120s", risk: medium, prerequisite: "multi-region setup"}
50
+ code_revert: {time: "minutes", risk: medium, prerequisite: "clean git history"}
51
+ database_restore: {time: "hours", risk: high, prerequisite: "backup verified"}
52
+
53
+ checklist:
54
+ pre_rollback:
55
+ - "Confirm rollback target version is healthy"
56
+ - "Verify database migration is backward compatible"
57
+ - "Notify stakeholders of rollback"
58
+ post_rollback:
59
+ - "Confirm health checks pass at target version"
60
+ - "Write rollback event to deployment log"
61
+ - "Open incident ticket for root cause analysis"
62
+ - "Update error budget tracking"
63
+
64
+ physical_spec:
65
+ type: custom_script
66
+ validator:
67
+ command: "test -f rollback.sh && grep -q 'set -euo pipefail' rollback.sh"
68
+ rule: "rollback_script_configured"
@@ -0,0 +1,121 @@
1
+ # CD Deployment Strategies(CD 部署策略)
2
+
3
+ ## 概述
4
+
5
+ 本標準定義四種主要部署策略的選用矩陣:Blue-Green、Canary、Rolling、Recreate。幫助團隊根據流量規模、風險容忍度和基礎設施成本,做出一致且有據可查的策略選擇。
6
+
7
+ ---
8
+
9
+ ## 核心原則
10
+
11
+ - **三維決策**:根據流量規模 × 風險容忍度 × 基礎設施成本選擇策略
12
+ - **禁止直接推產**:任何變更都必須先通過 staging 環境驗證
13
+ - **零停機目標**:除非為內部工具或開發環境,否則應追求零停機部署
14
+
15
+ ---
16
+
17
+ ## 策略選用矩陣
18
+
19
+ | 策略 | 流量規模 | 風險容忍度 | 基礎設施成本 | 停機時間 | 回滾時間 |
20
+ |------|---------|----------|------------|---------|---------|
21
+ | Blue-Green | 高 | 低 | 高 | 零 | < 30 秒 |
22
+ | Canary | 中至高 | 中 | 中 | 零 | < 2 分鐘 |
23
+ | Rolling | 任意 | 中 | 低 | 極少 | 數分鐘 |
24
+ | Recreate | 低 | 高 | 極低 | 數秒至數分鐘 | 數分鐘 |
25
+
26
+ ---
27
+
28
+ ## 各策略詳細說明
29
+
30
+ ### Blue-Green
31
+
32
+ **適用場景**:有狀態服務、資料庫相容性變更、高 SLA API
33
+
34
+ **運作方式**:
35
+ - 維護兩個完全相同的環境(Blue = 現有線上版,Green = 新版本)
36
+ - 完整部署並驗證 Green 環境後,切換 Load Balancer 流量
37
+ - 問題發生時立即切回 Blue
38
+
39
+ **前置條件**:雙環境基礎設施、Load Balancer、健康檢查
40
+
41
+ ---
42
+
43
+ ### Canary
44
+
45
+ **適用場景**:功能驗證、A/B 測試、高風險變更
46
+
47
+ **流量漸進比例**:1% → 5% → 25% → 50% → 100%
48
+
49
+ **運作方式**:
50
+ - 先將少量流量導向新版本
51
+ - 監控指標,符合自動晉升規則則繼續擴大
52
+ - 發現問題立即縮回 0%
53
+
54
+ **前置條件**:流量切分機制、可觀測性、自動晉升規則
55
+
56
+ ---
57
+
58
+ ### Rolling
59
+
60
+ **適用場景**:無狀態服務、標準更新、批次工作者
61
+
62
+ **運作方式**:
63
+ - 依序更新每個實例,更新前進行健康檢查
64
+ - 允許新舊版本短暫共存
65
+ - 資源效率最佳,但回滾需時較長
66
+
67
+ **前置條件**:多個服務實例、健康檢查
68
+
69
+ ---
70
+
71
+ ### Recreate
72
+
73
+ **適用場景**:開發/測試環境、內部工具、單一實例服務
74
+
75
+ **運作方式**:
76
+ - 停止所有現有實例,部署新版本,重新啟動
77
+ - 最簡單,但有停機時間
78
+
79
+ **前置條件**:無(最低門檻)
80
+
81
+ ---
82
+
83
+ ## 決策樹
84
+
85
+ ```
86
+ Q1: 需要零停機時間?
87
+ → 否 → Recreate
88
+ → 是 → Q2
89
+
90
+ Q2: 流量 > 10k req/min?
91
+ → 是 → Q3(Blue-Green 或 Canary)
92
+ → 否 → Rolling
93
+
94
+ Q3: 變更屬於高風險?
95
+ → 是 → Canary
96
+ → 否 → Q4
97
+
98
+ Q4: 基礎設施預算有限?
99
+ → 是 → Rolling
100
+ → 否 → Blue-Green
101
+ ```
102
+
103
+ ---
104
+
105
+ ## 無 CI/CD 環境的替代做法
106
+
107
+ | 策略 | 替代方案 |
108
+ |------|---------|
109
+ | Blue-Green | 參見 no-cicd-deployment.ai.yaml 的 Shell Script 實作 |
110
+ | Canary | 使用 Nginx `split_clients` 或 HAProxy 做流量切分 |
111
+ | Rolling | 使用順序式 rsync + 健康檢查迴圈 |
112
+ | Recreate | 最簡單 — 停止、部署、啟動 |
113
+
114
+ ---
115
+
116
+ ## 相關標準
117
+
118
+ - [deployment-standards.md](deployment-standards.md) — 部署基礎原則
119
+ - [rollback-standards.md](rollback-standards.md) — 回滾觸發條件矩陣
120
+ - [no-cicd-deployment.md](no-cicd-deployment.md) — 無 CI/CD 部署策略
121
+ - AI 格式:[../ai/standards/cd-deployment-strategies.ai.yaml](../ai/standards/cd-deployment-strategies.ai.yaml)