egovpdx/drupal-ci

Portland Oregon Drupal 8 站点镜像文档

镜像概述和主要用途

本镜像为Portland Oregon Drupal 8站点提供CI/CD流程支持，基于Lando容器化开发环境，集成Pantheon多环境（Dev/Test/Live）与CircleCI自动化构建测试。主要用于开发团队进行本地开发、代码版本控制、配置同步及持续集成部署，确保开发环境一致性与部署流程自动化。

核心功能和特性

• 容器化开发环境：通过Lando配置（.lando.yml）快速搭建与Pantheon Dev环境一致的本地容器，包含Drupal运行所需依赖
• 多环境集成：支持Pantheon Dev/Test/Live及Multidev环境同步，自动处理数据库与文件备份导入
• 自动化CI/CD：集成CircleCI实现代码提交触发自动构建、部署至Pantheon环境及冒烟测试
• 开发工具链：内置Composer包管理、Drush命令行工具、XDebug调试支持及主题构建工具（Webpack/Pattern Lab）
• 版本控制适配：针对Windows系统优化Git配置，支持符号链接与行尾符处理，确保跨平台代码一致性

使用场景和适用范围

• 本地开发：开发人员快速搭建一致的Drupal开发环境，避免"在我机器上能运行"问题
• 团队协作：通过标准化分支流程（GitHub Flow变体）实现代码提交、审查与合并管理
• 持续集成：功能分支提交自动触发CircleCI构建，部署至Pantheon Multidev环境并运行测试
• 生产部署：支持从release分支打包版本，依次部署至Pantheon Dev/Test/Live环境，包含配置同步与数据库更新

详细使用方法和配置说明

获取代码

标准克隆

bash
git clone git@github.com:eGovPDX/portlandor.git

该命令会在当前目录创建portlandor文件夹并拉取代码。

Windows开发者Git设置

Windows与类Unix系统（Unix/Linux/macOS）行尾符处理不同，需配置Git以确保代码兼容性：

1. 启用符号链接克隆：

bash
git clone -c core.symlinks=true git@github.com:eGovPDX/portlandor.git

注意：git clone和git checkout需以管理员身份运行（命令提示符或PowerShell）以创建符号链接

2. 禁用行尾符转换：

bash
git config core.autocrlf false

Lando安装与卸载

安装Lando

遵循Lando官方安装指南

卸载Lando

遵循Lando官方卸载指南，如需完全清理，执行"移除残留配置"步骤。

Lando使用指南

项目根目录的.lando.yml文件已配置Pantheon Dev环境连接，首次初始化本地站点步骤如下：

1. 启动容器：在项目根目录执行

bash
lando start

2. Pantheon认证：

   • 登录Pantheon控制台，在"我的仪表板 > 账户 > 机器令牌"生成令牌
   • 执行以下命令登录Pantheon账户：

   bash
   lando terminus auth:login --machine-token=[你的机器令牌]
   

3. Composer GitHub认证：

   • 登录GitHub生成个人访问令牌
   • 配置Composer认证：

   bash
   lando composer config --global --auth github-oauth.github.com "[你的GitHub令牌]"
   

4. 安装依赖（新克隆仓库时）：

bash
lando composer install  # 安装PHP依赖
lando yarn install      # 安装前端依赖

5. 数据库与文件设置（三选一）：

   • 自动导入最新数据：

     bash
     lando latest  # 自动下载并导入Pantheon Dev环境最新数据库
     

   • 手动导入数据库：
     1. 从Pantheon Dev环境备份页面下载最新数据库备份
     2. 创建artifacts目录并放入备份文件：mkdir artifacts && mv [备份文件] artifacts/
     3. 导入数据库：

        bash
        lando db-import artifacts/[备份文件名].sql.gz
        

   • 手动导入文件：
     1. 从Pantheon Dev环境下载最新文件备份
     2. 解压至web/sites/default/files目录

6. 构建本地环境：

bash
git checkout release      # 切换到release分支
lando refresh             # 执行composer install、数据库更新、配置导入及缓存重建

7. 访问站点：浏览器打开 [***]

8. XDebug控制：

bash
lando xdebug-on   # 启用XDebug
lando xdebug-off  # 禁用XDebug（提升性能）

9. 停止容器：

bash
lando stop        # 停止当前项目容器
lando poweroff    # 停止所有Lando容器

更多Lando与Pantheon命令参考Lando Pantheon文档

本地开发模式

默认本地站点运行于"开发模式"，禁用缓存并启用Twig调试，配置文件为web/sites/default/local.services.yml。开发者可修改该文件调整设置（如启用缓存），但禁止提交此文件，确保默认开发环境一致性。

仓库工作流

采用修改版GitHub Flow，通过feature分支提交PR至release分支，再合并至master部署。

启动本地开发

bash
git checkout release          # 切换到release分支
git pull origin release       # 拉取最新远程release分支代码
lando latest                  # 同步Pantheon Dev环境最新数据库
lando refresh                 # 刷新环境依赖与配置
git checkout -b powr-[ID]     # 创建feature分支（ID为Jira任务ID）

详细步骤：

1. 确认当前分支：git checkout release
2. 拉取远程更新：git pull origin release（可选git pull -p origin清理无效分支）
3. 命名规范：feature分支命名为powr-[ID]，子分支可加后缀（如powr-[ID]-a）
4. 分支切换：git checkout -b powr-[ID]
5. 数据库同步：每个 sprint 开始时执行lando latest
6. 环境刷新：lando refresh（执行composer install、drush updb、drush cim、drush cr）

代码提交与推送

1. 导出配置变更：

bash
lando drush cex  # 导出Drupal配置变更至代码仓库

2. 提交代码：

bash
git add [文件路径]  # 添加变更文件（或git add -A添加所有）
git commit -m "POWR-[ID] 变更描述"  # 提交并备注Jira任务ID

3. 变基同步release分支：

bash
git fetch origin release       # 获取远程release分支最新代码
git rebase -i origin/release   # 交互式变基，解决冲突后同步
git rebase --continue          # 冲突解决后继续变基（如需）
lando refresh                  # 刷新环境以应用release分支变更

4. 推送分支：

bash
git push -u origin powr-[ID]   # 推送至远程同名分支

创建Pull Request

• 在GitHub创建PR，base分支设为release（默认可能为master）
• PR标题格式：POWR-[ID] 功能简短描述，确保Jira自动关联任务

CircleCI持续集成

PR创建后触发自动流程：

1. 拉取代码并执行composer install
2. 部署至Pantheon Multidev环境
3. 执行配置导入（drush cim）、数据库更新（drush updb）、缓存重建（drush cr）
4. 运行冒烟测试验证构建成功
5. 失败时可在CircleCI日志查看错误（点击ci/circleci: visual_regression的Details链接）

构建与部署

合并至release分支

1. 代码审查通过后，点击"Squash and merge"合并至release分支，PR标题格式：POWR-[ID] 功能描述
2. 验证CircleCI在Release Multidev环境的构建结果
3. 测试通过后，在Jira标记任务完成并删除远程feature分支

部署至Pantheon Dev环境

1. 完成多个feature合并后，创建PR从release到master分支（使用普通"Merge"，非"Squash and merge"）
2. 合并触发CircleCI自动部署至Pantheon Dev环境，执行构建与测试
3. 验证Dev环境构建成功

部署至Test/Live环境

1. Test环境部署：

   • 登录Pantheon控制台，进入Test环境
   • 在"Deploys"页面勾选"克隆Live数据库至Test"，合并代码并部署，填写版本说明
   • 同步配置：访问/admin/config/development/configuration或执行lando terminus drush portlandor.test cim -y
   • 验证Test环境功能

2. Live环境部署：Test环境验证通过后，重复上述步骤部署至Live环境

主题构建

主题基于Webpack构建，Lando启动或lando refresh时自动触发，手动构建命令如下：

快速开始

bash
lando yarn start  # 启动开发模式，监视文件变更

访问Pattern Lab：[***]

常用命令

• 构建主题资产与Pattern Lab：lando yarn run build
• 监视文件变更并自动构建：lando yarn run watch
• 仅构建Pattern Lab：lando yarn run build:pl
• 监视Pattern Lab文件变更：lando yarn run watch:pl
• 清理Pattern Lab构建文件：lando yarn run clean:pl

Webpack构建输出说明

成功构建示例：

Hash: 83d85b18cfd6b88c5e7e
Version: webpack 4.29.0
Time: 7680ms
Built at: 02/05/2019 2:33:48 PM
                   Asset     Size  Chunks             Chunk Names
    css/style.bundle.css  196 KiB       0  [emitted]  main
css/style.bundle.css.map  542 KiB       0  [emitted]  main
       js/main.bundle.js   81 KiB       0  [emitted]  main
   js/main.bundle.js.map  320 KiB       0  [emitted]  main

• 输出包含版本信息、构建产物（CSS/JS文件及sourcemap）、模块依赖关系
• 错误排查：关注最后几行错误信息，如Sass导入失败（示例中因_fake.scss不存在导致构建失败）

使用Composer

Lando环境内置Composer，用于管理Drupal模块及依赖。

安装 contrib 模块

bash
lando composer require drupal/[模块名]  # 安装模块并更新composer.json
lando drush pm:enable [模块名]          # 启用模块

更新依赖

• 更新所有依赖：lando composer update
• 更新指定包（如Devel模块）：lando composer update --with-dependencies drupal/devel
• 更新锁文件哈希（composer.json变更后）：lando composer update --lock

Composer使用指南参考：Drupal 8 Composer最佳实践，Composer速查表

运行Jest测试

测试文件位于tests/percy/__tests__/，按用户角色组织。执行测试前确保依赖已安装，通过Lando环境运行测试命令（具体命令需参考项目package.json配置）。