Shopware 6 保姆级部署教程与运维避坑指南（宝塔面板 Linux）

适用版本：Shopware 6.6 / 6.7 社区版操作系统：Ubuntu 22.04（推荐）或 Debian 11+服务器配置：2核4G 起步，生产环境建议 4核8G

一、部署前必须知道的硬性要求

在动手之前，先对照以下清单确认服务器是否达标，不满足的字段会导致安装失败或运行时频繁报错。

PHP 要求：版本 8.2 / 8.3 / 8.4，推荐 PHP 8.2。内存限制必须 ≥512M，建议设为 1024M 甚至 2048M。max_execution_time 至少 300 秒，否则 Composer 下载依赖和主题编译会超时中断。

数据库要求：MySQL 8.0.17 以上，或 MariaDB 10.11 以上-1-15。特别注意：MySQL 8.0.20 和 8.0.21 存在兼容性问题，务必避开这两个版本。

必须安装的 PHP 扩展：curl、gd、fileinfo、zip、mbstring、openssl、bcmath、intl、json、dom、iconv、libxml、pcre、pdo、pdo_mysql、phar、simplexml、sodium、zlib。

必须解除的 PHP 禁用函数（宝塔默认会禁用，Shopware CLI 命令和安装程序依赖这些函数）：proc_open、putenv、pcntl_alarm、pcntl_signal、exec、shell_exec。

二、宝塔面板环境搭建（逐步操作）

2.1 安装宝塔面板

SSH 登录服务器后执行对应命令。

Ubuntu / Debian：

bash

wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed8484bec

安装完成后记下面板地址、用户名、密码，浏览器登录。

2.2 安装运行环境

进入 软件商店 → 运行环境，安装以下组件：

MySQL 避坑：如果服务器已有 MySQL 5.7，需先彻底清理再安装 8.0。执行 sudo dpkg --purge bt-mysql57，然后删除 /www/server/mysql 和 /www/server/data 目录（删除前先备份数据），再在软件商店选择 MySQL 8.0 编译安装-4。

2.3 PHP 深度配置

安装完 PHP 8.2 后，点击 设置，依次完成以下调整：

第一步：解除禁用函数
进入 禁用函数 标签，从列表中找到并删除：proc_open、putenv、pcntl_alarm、pcntl_signal、exec、shell_exec。

如果 putenv 在禁用函数列表中找不到，进入 配置文件 标签，搜索 putenv 将其删除。

第二步：安装扩展
进入 安装扩展 标签，确认或安装：fileinfo、intl、opcache、redis（可选，用于缓存加速）。

第三步：修改配置参数
进入 配置修改 标签：

• memory_limit：改为 1024M
• max_execution_time：改为 300
• upload_max_filesize：改为 50M
• post_max_size：改为 50M

保存后重启 PHP 和 Nginx。

三、创建站点与数据库

3.1 添加站点

宝塔面板 → 网站 → 添加站点：

• 域名：填写你的域名
• 根目录：保持默认（如 /www/wwwroot/你的域名）
• 数据库：选择 MySQL 8.0，创建数据库并记录数据库名、用户名、密码
• PHP 版本：选择 PHP-82

3.2 SSL 与强制 HTTPS

站点创建后，点击 SSL → Let‘s Encrypt，申请免费证书，勾选 强制 HTTPS。Shopware 6 强制要求 HTTPS。

3.3 设置运行目录（暂不操作）

此时先不修改运行目录，等源码部署完成后再回到站点设置中将运行目录改为 /public。

四、部署 Shopware 6 源码

4.1 清空站点根目录

SSH 进入站点目录：

bash

cd /www/wwwroot/你的域名
rm -rf *

4.2 通过 Composer 安装

bash

composer create-project shopware/production . --no-dev

. 表示安装到当前目录。如需指定版本，可改为 shopware/production:6.6.10.0。

等待依赖下载完成。如果中途报错，优先检查：PHP 版本是否为 8.2+、禁用函数是否已解除、Composer 是否完整。

4.3 设置运行目录

回到宝塔面板 → 站点设置 → 网站目录，将运行目录改为 /public。

4.4 设置文件权限

bash

chown -R www:www /www/wwwroot/你的域名
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 775 var public/thumbnail public/media

权限避坑：绝对不要使用 chmod -R 777，Shopware 官方明确禁止全局 777，存在代码执行风险。

五、配置环境变量与安装

5.1 创建 .env.local

在站点根目录创建 .env.local：

bash

nano .env.local

写入：

env

APP_URL=https://你的域名
DATABASE_URL=mysql://数据库用户名:数据库密码@127.0.0.1:3306/数据库名

保存退出（Ctrl+X → Y → 回车）。

5.2 命令行安装

bash

cd /www/wwwroot/你的域名
sudo -u www php bin/console system:install --basic-setup

--basic-setup 自动完成数据库表创建、管理员账号和默认销售渠道的初始化。

默认管理员：用户名 admin，密码 shopware。

立即改密码（必做）：

bash

sudo -u www php bin/console user:change-password admin

六、Nginx 伪静态配置（关键步骤）

宝塔面板 → 站点设置 → 伪静态，粘贴以下 Shopware 6 官方规则：

nginx

location / {
    try_files $uri /index.php$is_args$args;
}

location /recovery/install {
    index index.php;
    try_files $uri /recovery/install/index.php$is_args$args;
}

location /recovery/update/ {
    if (!-e $request_filename){
        rewrite . /recovery/update/index.php last;
    }
}

location ~ ^/(theme|media|thumbnail|bundles|css|fonts|js|recovery|sitemap)/ {
    expires 1y;
    add_header Cache-Control "public, must-revalidate, proxy-revalidate";
    log_not_found off;
    tcp_nodelay off;
    open_file_cache max=3000 inactive=120s;
    open_file_cache_valid 45s;
    open_file_cache_min_uses 2;
    open_file_cache_errors off;
    try_files $uri /index.php$is_args$args;
}

location ~ \.php$ {
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_pass unix:/tmp/php-cgi-82.sock;
    fastcgi_index index.php;
    include fastcgi.conf;
    fastcgi_param HTTP_PROXY "";
    fastcgi_buffers 8 16k;
    fastcgi_buffer_size 32k;
    fastcgi_read_timeout 300s;
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    send_timeout 300s;
}

6.7 版本注意：Shopware 6.7 对 Nginx 配置有调整，上述规则适用于 6.6 及以下。若使用 6.7，建议参考官方文档中针对 6.7 的新配置。

保存后重载 Nginx。

七、安全加固（上线前必做）

7.1 删除安装残留

bash

rm -f public/shopware-installer.phar.php

7.2 修改后台路径

bash

sudo -u www php bin/console system:config:set core.admin_path custom-admin-path

将 custom-admin-path 替换为你自定义的路径，避免被扫描器探测。

7.3 站点目录保护

宝塔面板 → 站点设置 → 目录保护，禁止访问 .env、var、config 等敏感目录。

7.4 端口与面板安全

• 宝塔安全组：只开放 80、443、22 端口
• 关闭宝塔面板的“未授权访问”和“默认端口”，修改面板别名

八、后台初始化与定时任务

8.1 后台基础配置

登录 https://你的域名/custom-admin-path（或自定义路径），完成：

1. Settings → Shop：设置时区、货币、语言、店铺名称
2. Settings → Shipping/Payment：配置配送区域和支付方式
3. Settings → Tax：按地区配置税率
4. 确认 Storefront 销售渠道的域名配置正确

8.2 配置定时任务（核心运维步骤）

Shopware 6 的消息队列和定时任务必须通过 CLI 运行，Admin Worker 在生产环境中性能不足，官方建议禁用。

第一步：禁用 Admin Worker

编辑 config/packages/z-shopware.yaml（如不存在则创建）：

yaml

shopware:
    admin_worker:
        enable_admin_worker: false

第二步：配置宝塔计划任务

宝塔面板 → 计划任务 → 添加任务，类型选 Shell 脚本，执行周期设为 每 1 分钟：

bash

cd /www/wwwroot/你的域名 && sudo -u www php bin/console scheduled-task:run --time-limit=60

再添加一个任务，同样每 1 分钟执行：

bash

cd /www/wwwroot/你的域名 && sudo -u www php bin/console messenger:consume default --time-limit=60

--time-limit=60 表示每次最多执行 60 秒，配合 1 分钟的计划任务可实现持续运行。

九、常见报错与解决方案

安装时 Composer 报错或中断
检查 PHP 版本是否为 8.2+、禁用函数是否已解除、max_execution_time 是否 ≥300。

前台 404
伪静态未生效。回到宝塔“伪静态”页面重新保存，然后重载 Nginx。

页面 500 错误
查看 var/log/ 下的日志文件。最常见原因是内存不足或权限错误。先提升 PHP memory_limit，再检查 var/ 和 public/ 目录权限。

商品不显示、索引异常
执行索引重建命令：

bash

sudo -u www php bin/console dal:refresh:index

定时任务不生效
检查宝塔计划任务的 Shell 脚本是否以 www 用户执行，以及 PHP 的 exec、proc_open 等函数是否已解除禁用。

后台打开缓慢
Shopware 后台首次加载需要编译前端资源，属于正常现象。后续可通过安装 Redis 缓存加速

十、日常运维规范

备份策略：每日自动备份数据库（宝塔计划任务），每周备份全站源码与 public/media 目录。任何版本更新或插件安装前，必须手动全量备份。

更新原则：Shopware 版本迭代较快，第三方插件可能跟进不及时。大版本升级前务必在测试环境验证，确认所有已装插件兼容后再操作

插件管理：只安装官方商店或可信来源的插件，未知来源插件可能包含后门或导致系统不稳定。

缓存维护：定期清理 var/cache 目录，但生产环境不要频繁手动清缓存，定时任务的缓存机制会自动处理。

日志监控：定期查看 var/log/ 下的 prod.log，及时排查异常访问和接口报错。

验证清单

部署完成后，逐项确认：

• 前台可正常访问，无 404/500
• 后台可登录，路径为自定义地址
• 加购 → 下单 → 支付 → 库存扣减全流程正常
• 两个定时任务（scheduled-task 和 messenger:consume）正常运行
• .env 文件无法通过浏览器直接访问
• SSL 证书有效，HTTP 自动跳转 HTTPS