Shopware 6 GitHub Actions CI搭建、部署后操作及API报错处理咨询

核心部署疑问解答 #

需配置写入权限的目录 #

• var/ 全量子目录（覆盖缓存、运行日志、搜索索引、临时生成的资源）
• config/jwt/（JWT鉴权证书的读写访问）
• public/media/、public/thumbnail/、public/bundles/（用户上传媒体、静态资源映射、插件资源输出目录）
• custom/plugins/（动态安装、更新插件的场景需要开放写入权限）
• 注意：所有目录的权限和属主必须与当前运行Web服务（PHP-FPM/Nginx/Apache）的用户完全匹配，避免使用sudo执行PHP命令生成root属主的缓存文件，这是生产环境API无规律报错的最常见诱因。

必选/可选的控制台命令 #

全场景必执行命令（缺失会直接导致功能异常）

• php bin/console asset:install：将插件、核心的静态资源映射到public/bundles目录，缺失会导致后台、前台静态资源404
• php bin/console system:update:finish：完成系统版本升级的全流程收尾，也是导致部署后API无法完成系统更新的核心遗漏命令
• php bin/console dal:refresh:index：更新商品、分类等实体的搜索索引，避免搜索结果异常
• php bin/console cache:clear：清理旧的容器、路由、配置缓存，避免部署后旧缓存逻辑不生效

按需执行的可选命令

• php bin/console theme:compile：仅当自定义主题、核心主题的前端资源发生变更时需要执行，纯服务端逻辑变更的场景不需要全量运行
• php bin/console plugin:refresh：仅当插件目录新增、删除后需要执行，无插件变动的场景可跳过
• 注意：不要直接执行rm -rf var/cache删除缓存目录，容易造成权限属主混乱，优先使用官方cache:clear命令按Web用户身份执行缓存清理。

必选的npm构建命令 #

• 主流Shopware 6版本不需要手动执行零散的vendor目录下npm命令，项目根目录内置的composer build:js命令已经覆盖了全量前端构建逻辑
• 仅当存在自定义主题、自定义插件的前端资源变更时，才需要执行构建流程；纯服务端逻辑、后台接口变更的场景完全可以跳过所有npm构建步骤，大幅缩短CI流程时长
• 不推荐在生产服务器上直接执行npm安装、构建操作，建议在CI Runner环境提前完成静态资源构建，再将产物同步到生产服务器，避免生产环境安装Node依赖带来的安全、性能损耗。

config/jwt目录的作用与所需证书 #

• 核心作用：该目录下的证书对是Shopware管理后台API、Storefront API的鉴权基础，用于签发、校验所有API请求的访问令牌，证书缺失或不匹配会直接导致所有API接口返回签名校验错误，是API无法完成系统更新的常见诱因
• 需要存放的证书：
  • config/jwt/private.pem：API请求签名私钥
  • config/jwt/public.pem：API请求验签公钥
• 注意：这套证书绝对不要跟随每次代码部署重新生成，需要在首次初始化项目时生成后存入CI加密凭据，每次部署复用同一份证书，避免证书变更导致所有已登录用户、第三方集成的API授权全部失效。

数据库迁移的配套执行命令 #

• 数据库迁移本身仅需执行php bin/console doctrine:migrations:migrate --no-interaction即可
• 迁移完成后必须配套执行的步骤：
  • 执行dal:refresh:index：迁移可能修改了实体索引结构，不刷新会导致索引与表结构不匹配报错
  • 执行system:update:finish：该命令会自动完成迁移后的状态校验、配置更新，单独执行迁移不运行该步骤，会导致系统更新流程卡在中断状态，触发API报错
• 非交互的CI流程下，所有控制台命令必须加--no-interaction参数，避免流程阻塞。

现有部署命令的常见问题 #

当前使用的部署命令存在几个容易引发API报错的问题：

sudo php bin/console cache:clear
sudo php bin/console dal:refresh:index
sudo php bin/console theme:compile

sudo rm -rf var/cache
sudo /usr/bin/npm clean-install --prefix vendor/shopware/administration/Resources
sudo /usr/bin/npm run --prefix vendor/shopware/administration/Resources lerna -- bootstrap
sudo /usr/bin/npm clean-install --prefix vendor/shopware/storefront/Resources/app/storefront
sudo /usr/bin/node vendor/shopware/storefront/Resources/app/storefront/copy-to-vendor.js
sudo php bin/console bundle:dump
sudo sh bin/build-js.sh
PROJECT_ROOT=/var/www/path-to-shopware/ sudo /usr/bin/npm --prefix vendor/shopware/storefront/Resources/app/storefront/ run production

• 全程使用sudo执行PHP命令，会导致生成的var/cache目录下的文件属主为root，Web服务器运行用户无读取权限，直接触发路由、配置加载类API错误
• 手动删除var/cache后未修正目录属主，进一步加剧权限不匹配问题
• 缺失system:update:finish、asset:install两个核心命令，系统更新流程走到收尾步骤会直接中断报错
• 在生产服务器上直接运行全量npm安装与构建，不仅耗时久，还容易因为Node版本不兼容导致构建产物缺失。

社区常用的Shopware 6部署方案与工具 #

• 工具选型：多数开发者会使用Ansible编写标准化部署剧本，固定权限配置、命令执行顺序、CI制品同步流程，避免手动执行命令的疏漏；也有团队使用Deployer这类专用PHP部署工具，工具内置Shopware 6的标准部署逻辑，不需要从零编写命令流程
• 通用标准部署流程顺序：
  1. CI环境拉取代码，执行composer依赖安装、前端资源构建，将所有代码、静态资源打包为部署制品
  2. 通过SSH连接生产服务器，拉取新的制品目录，通过软链接切换当前运行的版本路径
  3. 给Web服务器运行用户配置部署目录的读写权限
  4. 按Web用户身份依次执行必选控制台命令（不使用sudo）
  5. 重载PHP-FPM进程，完成版本切换
• API报错的常见排查方向：
  • 缓存目录、JWT证书的属主/权限与Web用户不匹配
  • 缺失system:update:finish命令导致系统更新状态卡在中断状态
  • JWT证书在部署过程中被重新生成，导致签名校验失败

内容的提问来源于stack exchange，提问作者Erik Pöhler