deploy-config

name	deploy-config
description	部署配置 — CI/CD流水线、容器化、环境配置、基础设施即代码。当需要配置 CI/CD 流水线、编写 Dockerfile/compose、管理多环境配置或基础设施即代码时使用此 skill。库/SDK 项目可标 deployment N/A 跳过。
argument-hint	<操作: pipeline|container|env|iac> <平台或环境类型>
suggested-tools	file_read, file_write, file_edit, shell_exec
depends	["context"]
disable-model-invocation	false
user-invocable	true

部署配置 (deploy-config)

能力边界

• 能做: CI/CD流水线配置、构建脚本编写、自动化测试集成、部署配置、容器化配置(Dockerfile/docker-compose)、环境配置管理、基础设施即代码(IaC)
• 不做: 源代码修改、测试编写、架构变更、CataForge 框架自身 CI/release 流水线（由仓库 .github/workflows 与 maintainer 维护）

输入规范

• arch#§1.4技术栈
• arch#§6目录结构
• test-report测试配置(流水线阶段)
• deploy-spec环境配置(容器/IaC阶段)

输出规范

• CI/CD配置文件(如 .github/workflows/)
• 构建脚本
• 容器化文件(Dockerfile, docker-compose.yml)
• 环境配置文件(.env.dev/.env.staging/.env.prod)
• IaC配置(Terraform/K8s manifests, 如适用)

操作指令

语言细则: 根据 framework.json project.languages，按需载入本 skill references/lang-<lang>.md（仅 active 语言，逐个 Read），获取对应语言的构建部署细则（构建/打包工具、依赖锁定、CI 缓存策略、容器基镜像、产物发布）。

指令1: CI/CD流水线 (pipeline)

Step 1: 平台选型

根据arch#§1.4技术栈决定CI/CD平台:

• GitHub Actions(默认): 项目托管在GitHub时
• GitLab CI: 项目托管在GitLab时
• Jenkins: 企业内部部署、复杂流水线需求时
• 不确定时通过context查阅arch#§1.4技术栈决策，信息不足则标注[ASSUMPTION]

Step 2: 配置标准流水线阶段

按以下顺序配置流水线:

lint → unit-test → integration-test → build → deploy-staging → e2e-test → deploy-prod

• 每个阶段定义明确的成功/失败条件
• 阶段间设置依赖(前序失败则阻断后续)
• PR触发: lint + unit-test + integration-test
• 主分支合并: 完整流水线

Step 3: 集成自动化测试

• 单元测试: 每次push触发
• 集成测试: PR和主分支触发
• E2E测试: 部署到staging后触发
• 覆盖率报告: 集成到PR检查中

Step 4: 环境变量与密钥管理

• secrets 注入见 §密钥管理规范
• 环境差异通过环境变量控制(dev/staging/prod)

Step 5: 缓存策略

• 依赖缓存: 包管理器的依赖目录 / 下载缓存（按技术栈）
• 构建缓存: Docker layer cache / 编译产物缓存
• 缓存key包含lock文件hash，确保依赖变更时刷新

Step 6: 发布检查清单

• 版本号: 项目版本元数据与 Git tag 一致
• changelog: 已更新且包含当前版本条目
• 构建产物: 存档到artifact存储
• 通知: 部署结果通知(Slack/邮件/webhook)

指令2: 容器化配置 (container)

Step 1: Dockerfile编写

遵循最佳实践:

• 多阶段构建: 分离构建环境和运行环境，减小镜像体积
• 最小基础镜像: 优先使用alpine/slim/distroless变体
• 非root用户: 创建专用用户运行应用
• .dockerignore: 排除node_modules、.git、测试文件等
• 层缓存优化: 依赖安装层在代码复制层之前
• 健康检查: 定义HEALTHCHECK指令

Step 2: docker-compose编排

• 服务定义: 每个服务指定image/build、ports、volumes、depends_on
• 网络: 定义服务间通信网络(前端/后端/数据库分离)
• 卷: 数据持久化卷(数据库) + 开发时代码热重载卷
• 健康检查: 依赖服务设置healthcheck，使用depends_on.condition: service_healthy
• compose profiles: 通过profiles区分dev/test/prod服务组合

指令3: 环境配置 (env)

Step 1: 基础设施需求分析

根据arch#§1.4技术栈确定:

• 运行时环境(Node.js / Python / Go / JVM等)
• 依赖服务(数据库、缓存、消息队列等)
• 部署目标: 单机(docker-compose) / 云(Terraform) / 集群(K8s manifests)

Step 2: 环境差异管理

• 通过env文件区分环境: .env.dev / .env.staging / .env.prod
• 敏感配置不入仓库(通过.gitignore排除)
• 环境变量分层:
  • 通用配置: docker-compose.yml中定义
  • 环境特定: env文件覆盖
  • 密钥: 通过平台secret机制注入

指令4: IaC配置 (iac)

根据部署目标选择:

• docker-compose: 单机部署，适合小型项目
• Terraform: 云资源编排(AWS/GCP/Azure)，state远程存储
• K8s manifests/Helm: 集群部署，支持水平扩展和自动恢复
• 配置版本化，纳入代码仓库

密钥管理规范

所有部署配置必须遵循以下密钥管理要求:

禁止事项

• 禁止将密钥、Token、密码硬编码到配置文件或代码中
• 禁止将 .env 文件（含敏感值）提交到版本控制
• 禁止在 CI/CD 日志中输出密钥值（注意 --verbose 模式可能泄露）

密钥注入策略（按优先级）

1. 平台原生 Secret 机制（推荐）:
   • GitHub Actions: ${{ secrets.MY_SECRET }}，通过 Repository/Environment Secrets 配置
   • GitLab CI: $MY_SECRET，通过 CI/CD Variables (masked + protected) 配置
   • Jenkins: Credentials Store（withCredentials 绑定注入环境变量）
2. 外部 Secret Manager（生产环境推荐）:
   • AWS Secrets Manager / Azure Key Vault / GCP Secret Manager / HashiCorp Vault
   • 应用启动时动态拉取，不持久化到文件系统
3. 环境变量文件（仅限本地开发）:
   • .env.dev 仅含开发用非敏感配置（如 API_URL=http://localhost:3000）
   • .env.example 作为模板提交到仓库（仅含键名，不含实际值）
   • .env*（含敏感值的）必须在 .gitignore 中排除

密钥清单模板

deploy-spec 文档中必须包含密钥清单节:

| 密钥名 | 用途 | 注入方式 | 环境 | 轮换策略 |
|--------|------|---------|------|---------|
| DB_PASSWORD | 数据库连接 | GitHub Secret | all | 90天 |
| API_KEY | 第三方API | Secret Manager | prod | 按需 |

Anti-Patterns

• 禁止: 在 Dockerfile / compose / k8s 配置中硬编码 secret 字面量 —— 任何敏感值必须走 env 变量或 secret manager 注入，硬编码进镜像即长期泄露
• 禁止: 单环境一份配置 —— deploy-spec 必须区分 dev / staging / prod 三档差异矩阵；不区分会让 staging 误用 prod 配置
• 禁止: 部署步骤缺 rollback 路径 —— 上线方案必须明示回滚机制（蓝绿 / 灰度 / 版本 pin 等），缺失则故障无快速止血
• 避免: 把 CI 配置与 deploy-spec 混写 —— CI 是构建产物契约，deploy-spec 是运行时契约，混写让审阅点错位；如把 staging 的 replica 数 / 资源 limit 写进 .github/workflows/ci.yml，应拆到 deploy-spec 的环境差异矩阵

效率策略

• 配置文件模板化，按项目技术栈适配
• Dockerfile层顺序优化，最大化构建缓存命中
• 环境差异最小化，通过变量控制

文档落稿

• deploy-spec / changelog 经 cataforge context write-doc / write-narrative / transact 落图后 cataforge context finalize 导出；本 skill 的 CI/容器/IaC 文件直写仓库，不经图后端
• 不把「Write docs/deploy-spec/ + ingest」当作 authoring 路径