公开摘要
架构说明
| 角色 | 说明 |
|---|---|
| GitLab | 代码仓库，提供 SSH 地址给 Jenkins 拉取代码。 |
| Jenkins | CI/CD 调度服务器，执行拉取、同步和远程命令。 |
| 目标测试机 | Nginx / PHP / Laradock 运行环境，承载 Laravel/Lumen 项目。 |
核心流程：Jenkins 拉取指定分支代码 → rsync 增量同步到目标服务器 → SSH 到目标服务器 → 进入 Laradock → 在 workspace 容器内执行依赖安装。
免密与权限通道
- Jenkins 到 GitLab：使用 GitLab Deploy Key 拉取代码。
- Jenkins 到目标测试机：使用 SSH 免密同步代码和执行命令。
- 部署密钥不要设置密码，否则 Jenkins 自动拉取会被阻塞。
- GitLab Deploy Key 如只用于拉取代码，不应授予写权限。
项目目录权限边界
- 不要给整个 Web 根目录设置
777。 - 不要把整个 Web 根目录过户给
jenkins。 - 每个项目使用独立目录，只授权该项目目录。
.env不从 Jenkins 工作区覆盖到目标服务器，应该由目标环境独立维护。vendor不通过 rsync 同步，统一在目标服务器 Laradock 容器内安装。
Jenkins 任务配置
- 源码管理选择 Git，使用 SSH 仓库地址。
- 凭据选择 Jenkins 中配置的 GitLab SSH 私钥。
- 构建分支可配置为测试分支，例如
*/beta。 - 内网环境可用 Poll SCM 轮询，不依赖公网回调或内网穿透。
- rsync 同步时应排除
.git/、.env、node_modules/、vendor/和storage/logs/。
部署脚本应该使用 composer install，而不是 composer update。
Laravel DevOps 准则
composer update会重新解析依赖版本，可能拉取未验证的新版本。composer install会严格按照composer.lock安装，保证开发、测试、生产依赖一致。composer.lock必须提交到 Git 仓库。- 不要依赖
git diff HEAD~1判断是否执行 Composer；Jenkins 可能使用 shallow clone，多分支合并也会让判断复杂化。 - 推荐每次部署都执行
composer install，利用 Composer 自身缓存和锁文件比对。
验收清单
- GitLab 项目已配置 Jenkins Deploy Key。
- Jenkins 已配置 SSH 私钥凭据，并可拉取 GitLab 仓库。
- Jenkins 可免密 SSH 到目标测试机。
- 目标测试机项目目录已创建并归属 Jenkins 用户。
- 目标测试机 Laradock 目录存在，workspace 容器可执行 Composer。
- Jenkins Console Output 中 rsync 同步成功。
.env、vendor、storage/logs未被覆盖。- 站点访问、接口健康检查或 Laravel/Lumen 启动检查正常。
常见问题
- Jenkins 拉取 GitLab 失败：检查 SSH 仓库地址、凭据、Deploy Key 和 Jenkins 用户 SSH 连通性。
- rsync 权限不足：检查目标项目目录归属。
- docker compose exec 失败：检查 Laradock 目录、workspace 容器和 Jenkins 用户 Docker 权限。
- Composer 安装失败：检查
composer.lock、PHP 版本、扩展和 Composer 源。