diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..942a592
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,176 @@
+# 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` |
+| 数据库名 | `shopxo` |
+| 用户名 | `shopxo_user` |
+| 密码 | `shopxo_pass_2024` |
+
+3. 完成安装
+
+### 停止环境
+
+```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/.openclaw/workspace/council-research/shopxo-eval/.worktrees/shopxo-evaluator/shopxo-src/
+```
+
+如需切换到其他目录，修改 `~/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
+```