vr-shopxo-plugin/docs/DEPLOYMENT.md

# ShopXO 本地开发环境部署

> 部署时间：2026-04-14
> 适用平台：macOS (Intel/Apple Silicon M1-M3)

---

## 一、快速启动

### 前提条件

- Docker Desktop（macOS）
- ShopXO 源码（本仓库已克隆）

### 一键启动

```bash
cd ~/WorkSpace/shopxo-env
./start.sh
```

启动后访问：**http://localhost:10000**

### 首次安装

1. 浏览器打开 http://localhost:10000
2. 按向导填写：

| 配置项 | 值 |
|---|---|
| 数据库地址 | `mysqldb` |
| 端口 | `3306` |
| 数据库名 | `vrticket` |
| 用户名 | `shopxo_user` |
| 密码 | `shopxo_pass_2024` |

3. 完成安装后，后台入口文件名会被随机化为 `admin{随机6位}.php`（如 `adminufgeyw.php`），记录下来备用。

### 停止环境

```bash
docker compose -f ~/WorkSpace/shopxo-env/docker-compose.yml down
```

---

## 二、目录结构

```
~/WorkSpace/shopxo-env/
├── docker-compose.yml   # 容器编排配置
├── .env                # 环境变量（数据库密码）
├── start.sh            # 启动脚本
├── etc/
│   ├── nginx/          # nginx 配置
│   ├── php/            # PHP 配置
│   └── db/             # MySQL 配置
└── logs/               # 日志目录（待创建）
```

**ShopXO 源码挂载位置**：
- 容器内：`/var/www/html`
- 本地： `${SHOPXO_SRC}` 环境变量指向的目录

---

## 三、容器说明

| 容器名 | 镜像 | 端口 | 说明 |
|---|---|---|---|
| `shopxo-web` | nginx:latest | 10000→80 | Web 服务器 |
| `shopxo-php` | nanoninja/php-fpm:8.1 | 9000 (内部) | PHP-FPM |
| `shopxo-mysql` | mysql:8.0 | 10001→3306 | 数据库 |

### PHP 扩展（已预装）

```
pdo_mysql ✅  curl ✅  gd ✅
mbstring ✅  openssl ✅  zip ✅
```

### 修改代码后

代码通过绑定挂载直接挂到容器内，**修改本地文件立即生效**，无需重启容器。

如需重启 PHP：
```bash
docker compose -f ~/WorkSpace/shopxo-env/docker-compose.yml restart php
```

---

## 四、日志查看

```bash
# 查看所有容器日志
docker compose -f ~/WorkSpace/shopxo-env/docker-compose.yml logs -f

# 仅看 PHP 日志
docker compose -f ~/WorkSpace/shopxo-env/docker-compose.yml logs -f php

# 仅看 MySQL 日志
docker compose -f ~/WorkSpace/shopxo-env/docker-compose.yml logs -f mysqldb
```

---

## 五、数据库连接

从容器内连接（PHP 连接 MySQL）：
```
主机: mysqldb（容器网络名）
端口: 3306
用户: shopxo_user
密码: shopxo_pass_2024
```

从宿主机连接（数据库工具）：
```
主机: localhost
端口: 10001
用户: root
密码: shopxo_root_2024
```

---

## 六、修改 ShopXO 源码路径

默认挂载到：
```
/Users/bigemon/WorkSpace/vr-shopxo-plugin/shopxo
```

如需切换到其他目录，修改 `~/workspace/shopxo-env/.env`：
```
SHOPXO_SRC=/你的/路径/shopxo-src
```

然后重启：
```bash
docker compose -f ~/WorkSpace/shopxo-env/docker-compose.yml restart
```

---

## 七、已知问题

### M1/M2/M3 Mac ARM64 兼容

`nanoninja/php-fpm:8.1` 镜像为 AMD64，通过 Rosetta2 模拟运行。功能正常，但性能略低于原生 ARM64 镜像。

**未来可选方案**：如有性能需求，可研究支持 ARM64 的 PHP-FPM 镜像（如 `php:8.1-fpm-alpine`）。

### MySQL 配置文件

`etc/db/my.cnf` 已针对 MySQL 8.0 优化，移除了 `NO_AUTO_CREATE_USER`（MySQL 8.0 已移除）。

---

## 八、环境完整性验证

```bash
# 1. 检查容器运行状态
docker ps --filter "name=shopxo"

# 2. 验证 PHP
docker exec shopxo-php php -v

# 3. 验证 MySQL 连接
docker exec shopxo-php php -r "new PDO('mysql:host=mysqldb', 'shopxo_user', 'shopxo_pass_2024');"

# 4. 验证 Web 访问
curl -s -o /dev/null -w "%{http_code}" http://localhost:10000/
# 期望输出: 302 (重定向到安装向导) 或 200
```