Files

hurole d22fdc9618 feat: 实现环境变量预设功能 & 移除稀疏检出

## 后端改动
- 添加 Project.envPresets 字段（JSON 格式）
- 移除 Deployment.env 字段，统一使用 envVars
- 更新部署 DTO，支持 envVars (Record<string, string>)
- pipeline-runner 支持解析并注入 envVars 到环境
- 移除稀疏检出模板和相关环境变量
- 优化代码格式（Biome lint & format）

## 前端改动
- 新增 EnvPresetsEditor 组件（支持单选/多选/输入框类型）
- 项目创建/编辑界面集成环境预设编辑器
- 部署界面基于预设动态生成环境变量表单
- 移除稀疏检出表单项
- 项目详情页添加环境变量预设配置 tab
- 优化部署界面布局（基本参数 & 环境变量分区）

## 文档
- 添加完整文档目录结构（docs/）
- 创建设计文档 design-0005（部署流程重构）
- 添加 API 文档、架构设计文档等

## 数据库
- 执行 prisma db push 同步 schema 变更

2026-01-03 22:59:20 +08:00

5.2 KiB

Raw Blame History

title: 设计文档 0005 - 部署流程重构（移除稀疏检出 & 环境预设） summary: 调整部署相关能力：移除稀疏检出；将部署环境从创建时输入改为在项目设置中预设。 owners: - team: backend reviewers: - team: frontend status: draft date: 2026-01-03 version: 0.1.0 related: - docs: docs/api/endpoints.md - schema: apps/server/prisma/schema.prisma

设计文档 0005：部署流程重构（移除稀疏检出 & 环境预设）

1. 背景（Context）

当前部署流程在“项目详情页发起部署”时包含“稀疏检出（sparse checkout）”表单项，并且流水线模板中也包含与稀疏检出相关的逻辑。

另外，部署时需要指定环境变量（例如 env），但目前是在“创建部署”时临时输入/选择。随着项目数量增加，这种方式容易造成不一致与误操作。

2. 目标（Goals）

移除项目详情页部署表单中的“稀疏检出”相关输入项
移除流水线模板中与稀疏检出相关的代码逻辑（后端模板/生成逻辑）
将“部署环境（env）”从创建部署时指定，调整为在“项目设置”中提前预设
创建部署时仍需要选择/指定环境，但选项来源于项目设置中的预设项

3. 非目标（Non-goals）

不新增多维度环境变量管理（仅覆盖本次提到的 env 单项预设）
不在本次引入复杂的环境权限、审批流

4. 需求与范围（Requirements & Scope）

4.1 移除稀疏检出

用户侧

项目详情页发起部署时：不再展示/提交稀疏检出字段

系统侧

流水线模板：移除任何基于稀疏检出路径的生成/执行逻辑

说明：当前 DB 中 Deployment 仍存在 sparseCheckoutPaths 字段（见 schema.prisma），本次需求仅明确“功能不再需要”。字段是否删除/迁移由本设计后续章节确定。

4.2 部署环境 env 改为项目设置预设

核心约束

环境变量预设需要支持多选、单选、输入框这几种类型
在项目设置中新增可配置项（预设项）：例如：指定env 环境变量
- 类型：单选（single select）
- key：env，value 及时部署是选中的候选项的值
- options：staging（测试环境）、production（生产环境）

行为

创建部署时仍需指定环境（env），但：
- 不再由用户自由输入
- 只允许从该项目预设的 options 中选择

5. 影响面（Impact）

5.1 前端

项目详情页部署表单：移除“稀疏检出”相关 UI 与字段提交
项目设置页：新增“环境预设（env）”配置入口（单选 + 选项 staging/production）
创建部署交互：环境选项从项目设置读取（不再硬编码/临时输入）

5.2 后端

部署创建接口：校验 env 必须来自项目预设（避免非法 env）
流水线模板：移除稀疏检出相关的模板字段/生成逻辑

5.3 数据库

需要新增“项目设置/项目配置”承载 env 预设（落库方案待定）
既有 Deployment 的 sparseCheckoutPaths 字段：后续决定是否保留（兼容历史）或迁移删除

6. 兼容性与迁移（Compatibility & Migration）

对历史部署记录：
- 若存在 sparseCheckoutPaths，不影响查询展示，但新建部署不再写入该字段
对创建部署：
- 若项目未配置 env 预设：创建部署应失败并提示先到项目设置配置（或提供默认值策略，待确认）

7. 测试要点（Test Plan）

前端：
- 项目详情页部署表单不再出现稀疏检出项
- 项目设置可保存 env 预设（单选）并在创建部署时正确展示
后端：
- 创建部署：env 不在项目预设 options 内时应拒绝
- 流水线模板：移除稀疏检出后仍能正常创建并执行

8. 实施状态（Implementation Status）

已完成（后端）

✅ Prisma Schema：在 Project 表添加 envPresets 字段（String? 类型，存储 JSON）
✅ 移除部署创建/重试接口中的 sparseCheckoutPaths 写入
✅ 在部署创建接口添加环境校验：验证 env 是否在项目 envPresets 的 options 中
✅ 更新 project DTO 和 controller 支持 envPresets 读写
✅ 移除 pipeline-runner 中的 SPARSE_CHECKOUT_PATHS 环境变量
✅ 生成 Prisma Client

已完成（前端）

✅ 创建 EnvPresetsEditor 组件（支持单选、多选、输入框类型）
✅ 在 CreateProjectModal 和 EditProjectModal 中集成环境预设编辑器
✅ 从 DeployModal 移除稀疏检出表单项
✅ 在 DeployModal 中从项目 envPresets 读取环境选项并展示
✅ 移除 DeployModal 中的动态环境变量列表（envVars Form.List）
✅ 从类型定义中移除 sparseCheckoutPaths 字段
✅ 在项目详情页项目设置 tab 中添加环境变量预设的查看和编辑功能

待定问题

Q1：项目设置存储方式 → 已决定：使用 Project.envPresets JSON 字段
Q2：未配置 env 预设的默认行为 → 已实现：若配置了预设则校验，否则允许任意值（向后兼容）
Q3：Deployment.sparseCheckoutPaths 字段 → 已决定：保留字段（兼容历史），但新建部署不再写入

5.2 KiB Raw Blame History Unescape Escape