ECShopX_docker/php74

ECShopX Docker 开发环境

ECShopX 采用前后端分离的方式开发，代码结构由后端 API 和多个前端组成。

• 后端 API：基于 Lumen 开发，包含 Web、Scheduler、Worker
• 前端：管理端、小程序、PC端、H5端

📋 目录

• 准备工作
• 快速开始
• 详细步骤
• 脚本说明
• 常见问题
• 访问地址

🚀 快速开始

1. 克隆项目

git clone https://github.com/shopex/ecshopx-open-docker.git
cd ecshopx-open-docker/php74
cp .env.example .env

2. 初始化子项目代码

chmod +x setup.sh init-api.sh
./setup.sh

3. 配置 Docker Desktop 文件共享（重要！macOS 用户必须操作）

# 打开 Docker Desktop → Settings → Resources → File Sharing
# 添加项目所在目录（如 /Users/你的用户名/data/ecshopx-open-docker/php74）

4. 启动 Docker 容器

docker-compose up -d

5. 一键初始化 API（包含数据库迁移）

./init-api.sh

6. 访问应用

# 管理后台: http://127.0.0.1:8080
# 移动端: http://127.0.0.1:8081
# PC端: http://127.0.0.1:8082

📦 准备工作

1. 系统要求

• Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
• Docker Compose
• Git
• 至少 4GB 可用内存
• 至少 10GB 可用磁盘空间

Docker 会自动处理不同 CPU 架构的兼容性问题，无需手动配置。

2. 克隆项目

git clone https://github.com/shopex/ecshopx-open-docker.git
cd ecshopx-open-docker/php74

3. macOS 用户重要配置 ⚠️

Docker Desktop 文件共享配置（必须操作）：

1. 打开 Docker Desktop 应用
2. 点击右上角 ⚙️ Settings
3. 进入 Resources → File Sharing
4. 添加项目所在目录（例如：/Users/你的用户名/data/ecshopx-open-docker/php74）
5. 点击 Apply & Restart

为什么需要这一步？ macOS 的 Docker Desktop 默认只允许访问某些目录。如果不配置文件共享，容器内将看不到挂载的文件，导致应用无法正常运行。

📖 详细步骤

第一步：初始化代码

方式一：使用 setup.sh 自动拉取（推荐）

chmod +x setup.sh
./setup.sh

运行脚本后会交互式询问是否拉取子项目代码：

• 按 Y/y 或 回车 → 自动从 GitHub 拉取所有子项目
• 按 N/n → 跳过拉取，使用本地已有的代码

方式二：手动放置代码

如果你已经下载了代码包，可以手动复制到对应目录：

• 管理端代码 → ECShopX_admin-frontend/ 目录
• API端代码 → ECShopX/ 目录
• PC端代码 → ECShopX_desktop-frontend/ 目录
• H5端代码 → ECShopX_mobile-frontend/ 目录

完成后的目录结构

php74/
├── .env                          # Docker Compose 环境变量（需创建）
├── docker-compose.yml            # Docker 编排配置
├── setup.sh                      # 子项目代码初始化脚本
├── init-api.sh                   # API 服务一键初始化脚本
├── config/                       # 配置文件目录
│   ├── nginx/
│   └── php/
├── ECShopX/                      # 后端 API 代码
│   ├── app/
│   ├── bootstrap/
│   ├── config/
│   ├── .env                      # API 配置（自动生成）
│   └── ...
├── ECShopX_admin-frontend/       # 管理端前端代码
├── ECShopX_desktop-frontend/     # PC端前端代码
└── ECShopX_mobile-frontend/      # H5端前端代码

第二步：创建 Docker Compose 环境变量

在 php74 目录创建 .env 文件：

cp .env.example .env

说明：这个 .env 文件用于 docker-compose.yml 中的卷映射配置。使用相对路径使项目更便于移动。

第三步：启动 Docker 容器

# 后台启动所有服务
docker-compose up -d

# 查看容器状态
docker-compose ps

# 查看日志（可选）
docker-compose logs -f

首次启动说明：

• 第一次启动需要拉取 Docker 镜像，可能需要等待几分钟
• 镜像地址：shopexhub/php:ecx-7.4.32-fpm-alpine3.16
• 如果拉取失败，可能需要配置 Docker 镜像加速或使用代理

第四步：一键初始化 API（推荐）

使用 init-api.sh 脚本一键完成所有配置：

chmod +x init-api.sh
./init-api.sh

脚本会自动完成以下操作：

1. ✅ 检查容器运行状态
2. ✅ 复制 .env.full 到 .env（如果不存在）
3. ✅ 验证文件挂载是否正常
4. ✅ 安装 Composer 依赖（使用阿里云镜像加速）
5. ✅ 安装 Supervisor、Curl、Vim
6. ✅ 配置并启动 Supervisor
7. ✅ 设置存储目录权限
8. ✅ 自动配置数据库和 Redis 连接
9. ✅ 创建数据库
10. ✅ 生成应用密钥
11. ✅ 运行数据库迁移

整个过程约需 3-5 分钟，完成后即可直接使用。

第五步：手动配置（可选，如果不使用 init-api.sh）

如果你想手动配置，可以按照以下步骤操作：

1. 进入容器

docker exec -it ecshopx-api sh
cd /data/httpd

2. 配置 .env 文件

# 复制配置文件
cp .env.full .env

# 编辑配置
vi .env

修改以下配置项：

# 数据库配置
DB_CONNECTION=default
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=ecshopx
DB_USERNAME=root
DB_PASSWORD=root

# Redis 配置
REDIS_CLIENT=predis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=123456

3. 安装依赖

# 配置 Composer 镜像
php composer.phar config repo.packagist composer https://mirrors.aliyun.com/composer/

# 安装依赖（需要较大内存）
php -d memory_limit=-1 composer.phar install --optimize-autoloader

4. 创建数据库

# 退出容器
exit

# 进入 MySQL 容器创建数据库
docker exec ecshopx-open-docker_mysql_1 mysql -uroot -proot -e \
  "CREATE DATABASE IF NOT EXISTS ecshopx CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

5. 初始化数据库

# 重新进入 API 容器
docker exec -it ecshopx-api sh
cd /data/httpd

# 生成应用密钥
php artisan key:generate

# 运行数据库迁移
php artisan doctrine:migrations:migrate

第六步：编译前端代码（可选）

如果需要开发前端，需要在宿主机安装 Node.js 并编译：

# 进入前端项目目录
cd ECShopX_admin-frontend

# 安装依赖
npm install

# 开发模式
npm run dev

# 生产构建
npm run build

详细步骤请参考各前端项目的 README.md。

🌐 访问地址

服务启动后，可以通过以下地址访问：

服务	地址	说明
管理后台	http://127.0.0.1:8080	商城管理端
移动端	http://127.0.0.1:8081	H5 移动端
PC端	http://127.0.0.1:8082	PC 桌面端
后端 API	http://127.0.0.1:8080/api	RESTful API
phpMyAdmin	http://127.0.0.1:8083	数据库管理工具

数据库连接信息

配置项	值
主机	mysql (容器内) / 127.0.0.1:3306 (宿主机)
用户名	root
密码	root
数据库	ecshopx

Redis 连接信息

配置项	值
主机	redis (容器内) / 127.0.0.1:6379 (宿主机)
密码	123456
数据库	0

🛠 脚本说明

setup.sh - 子项目代码初始化

功能：自动从 GitHub 克隆所有子项目代码

使用方法：

chmod +x setup.sh
./setup.sh

工作流程：

1. 交互式询问是否拉取代码
2. 检查各子项目目录是否已存在
3. 如果不存在，则从 GitHub 克隆
4. 如果已存在，则跳过

克隆的子项目：

• ECShopX - 后端 API
• ECShopX_admin-frontend - 管理端前端
• ECShopX_desktop-frontend - PC端前端
• ECShopX_mobile-frontend - H5端前端

init-api.sh - API 服务一键初始化

功能：自动完成 API 服务的所有初始化配置

使用方法：

chmod +x init-api.sh
./init-api.sh

详细功能：

步骤	说明	技术细节
检查环境	验证 docker-compose.yml 和容器状态	确保在正确目录运行
配置文件	自动复制 .env.full → .env	仅在 .env 不存在时复制
验证挂载	检查容器内文件是否可见	解决 macOS 文件共享问题
Composer	安装 PHP 依赖包（148个）	使用 -d memory_limit=-1 避免内存不足
系统工具	安装 supervisor、curl、vim	Alpine Linux 包管理
Supervisor	配置进程管理器	管理队列和 WebSocket 服务
权限设置	设置 storage 目录权限	确保日志和缓存可写
数据库配置	自动替换 DB/Redis 配置	使用 sed 批量替换
创建数据库	创建 ecshopx 数据库	UTF-8MB4 字符集
应用密钥	生成 Laravel 应用密钥	用于加密 session 等
数据库迁移	执行 64 个数据库迁移	创建所有表结构

脚本亮点：

• ✅ 智能内存管理：使用 -d memory_limit=-1 解决 Composer 内存不足
• ✅ 镜像加速：配置阿里云 Composer 镜像，加快依赖下载
• ✅ 自动配置：无需手动编辑配置文件
• ✅ 错误检测：每步都有状态检查和错误提示
• ✅ 幂等性：可以重复执行，不会造成数据问题

❓ 常见问题

1. 容器内看不到挂载的文件

症状：运行 docker exec ecshopx-api ls /data/httpd 显示为空

原因：macOS Docker Desktop 文件共享权限未配置

解决方案：

# 1. 打开 Docker Desktop
# 2. Settings → Resources → File Sharing
# 3. 添加项目所在目录（如 /Users/你的用户名/data/ecshopx-open-docker/php74）
# 4. Apply & Restart

# 5. 重启容器
docker-compose down
docker-compose up -d

详见：VOLUME_ISSUE_SOLUTION.md

2. Composer 安装失败：内存不足

症状：

Fatal error: Allowed memory size of 1610612736 bytes exhausted

解决方案：使用 -d memory_limit=-1 参数

docker exec ecshopx-api sh -c "cd /data/httpd && php -d memory_limit=-1 composer.phar install"

init-api.sh 脚本已自动处理此问题。

3. 数据库连接失败

症状：

SQLSTATE[HY000] [2002] Connection refused

解决方案：

检查 .env 配置中数据库主机是否正确：

# 容器内必须使用服务名
DB_HOST=mysql  # ✅ 正确
DB_HOST=127.0.0.1  # ❌ 错误（容器内不可用）
DB_HOST=localhost  # ❌ 错误（容器内不可用）

4. Redis 连接失败

症状：

Connection refused [tcp://127.0.0.1:6379]

解决方案：

检查 .env 配置：

REDIS_HOST=redis           # ✅ 正确
REDIS_PASSWORD=123456      # 必须配置密码

5. 端口冲突

症状：

Bind for 0.0.0.0:8080 failed: port is already allocated

解决方案：

# 方式一：停止占用端口的程序
lsof -ti:8080 | xargs kill

# 方式二：修改 docker-compose.yml 中的端口映射
# 例如：将 8080:80 改为 8090:80

6. 查看容器日志

# 查看所有容器日志
docker-compose logs

# 查看特定容器日志
docker-compose logs ecshopx-api

# 实时跟踪日志
docker-compose logs -f ecshopx-api

# 查看最近 100 行日志
docker-compose logs --tail=100 ecshopx-api

7. 重启服务

# 重启所有服务
docker-compose restart

# 重启特定服务
docker-compose restart ecshopx-api

# 停止并删除容器（不会删除数据）
docker-compose down

# 完全清理（包括卷和网络）
docker-compose down -v

🔧 开发命令

进入容器

# 进入 API 容器
docker exec -it ecshopx-api sh

# 进入 MySQL 容器
docker exec -it ecshopx-open-docker_mysql_1 mysql -u root -p

# 进入 Redis 容器
docker exec -it ecshopx-redis redis-cli -a 123456

常用 Artisan 命令

# 进入 API 容器
docker exec -it ecshopx-api sh
cd /data/httpd

# 查看路由
php artisan route:list

# 清除缓存
php artisan cache:clear

# 清除配置缓存
php artisan config:clear

# 生成 API 文档
php artisan swagger:generate

# 运行队列
php artisan queue:work

# 查看所有命令
php artisan list

数据库操作

# 运行迁移
docker exec -w /data/httpd ecshopx-api php artisan doctrine:migrations:migrate

# 回滚迁移
docker exec -w /data/httpd ecshopx-api php artisan doctrine:migrations:rollback

# 查看迁移状态
docker exec -w /data/httpd ecshopx-api php artisan doctrine:migrations:status

📚 更多资源

• ECShopX 官方文档
• Docker 官方文档
• Docker Compose 文档
• Lumen 框架文档

---

如有问题，请提交 Issue。