nex_design/VOLUME_MOUNT_SOLUTION.md

# Docker 卷挂载方案 - 实施总结

## ✅ 方案优势

相比构建时复制方案，卷挂载方案具有以下优势：

### 🚀 实时更新
- 修改 MD 文档后**立即生效**
- **无需**重新构建 Docker 镜像
- **无需**重启容器
- 开发体验极佳

### 💡 简化流程
- 构建流程更简单，无需 prebuild 脚本
- 镜像更轻量，不包含文档内容
- 文档和代码分离，职责清晰

### 🔄 灵活部署
- 可以独立管理文档版本
- 支持多环境使用不同文档
- 易于回滚和更新

## 📝 实施内容

### 1. 核心配置（docker-compose.yml:16）

```yaml
volumes:
  - ./docs:/app/dist/docs:ro
```

**说明：**
- 将宿主机 `./docs` 挂载到容器 `/app/dist/docs`
- `:ro` 只读挂载，提高安全性

### 2. 清理之前的方案

**移除文件/配置：**
- ❌ `package.json` 中的 `prebuild` 脚本
- ❌ `Dockerfile` 中的 `cp -r docs public/` 命令
- ❌ `.gitignore` 中的 `public/docs/` 规则

**保留文件：**
- ✅ `ecosystem.config.js` - PM2 配置
- ✅ `Dockerfile` - Docker 镜像配置（已简化）
- ✅ `docker-compose.yml` - 添加了卷挂载
- ✅ `.dockerignore` - 优化构建
- ✅ `scripts/clean.sh` - 清理脚本（已更新）

### 3. 文档更新

- ✅ `DEPLOYMENT.md` - 更新为卷挂载方案说明
- ✅ `docs/DOCKER_DOCS_SETUP.md` - 详细的卷挂载方案文档
- ✅ `QUICKSTART.md` - 更新快速参考
- ✅ `README.md` - 保持部署文档链接

## 🎯 使用方法

### 本地开发
```bash
yarn dev                    # 开发服务器
```

### 构建和预览
```bash
yarn build                  # 构建（不包含 docs）
yarn preview                # 预览
```

### Docker 部署
```bash
# 首次部署
docker-compose up -d --build

# 后续启动
docker-compose up -d

# 查看日志
docker-compose logs -f
```

### 更新文档
```bash
# 直接编辑即可，立即生效
vim docs/DESIGN_COOKBOOK.md

# 或使用编辑器
code docs/components/PageTitleBar.md

# 浏览器刷新即可看到更新
```

## 🔍 验证方法

### 1. 检查挂载
```bash
# 查看容器挂载情况
docker inspect nex-design-app | grep -A 10 Mounts

# 检查容器内文件
docker exec nex-design-app ls -la /app/dist/docs/
```

### 2. 验证实时同步
```bash
# 在宿主机添加测试文件
echo "# Test" > docs/test.md

# 立即在容器内查看
docker exec nex-design-app cat /app/dist/docs/test.md

# 清理测试文件
rm docs/test.md
```

### 3. 浏览器访问
```bash
# 启动服务
docker-compose up -d

# 访问文档
curl http://localhost:3000/docs/DESIGN_COOKBOOK.md

# 或在浏览器打开
open http://localhost:3000
```

## 📊 方案对比

| 特性 | 卷挂载方案 ✅ | 构建时复制方案 |
|------|--------------|----------------|
| 文档实时更新 | ✅ 立即生效 | ❌ 需要重新构建 |
| 镜像体积 | ✅ 更小 | ❌ 更大 |
| 构建速度 | ✅ 更快 | ❌ 更慢 |
| 维护便利性 | ✅ 直接编辑 | ❌ 需要构建 |
| 部署灵活性 | ✅ 高 | ⚠️ 中 |
| 镜像自包含 | ⚠️ 需要 docs 目录 | ✅ 完全自包含 |

## 🚨 注意事项

### 1. 部署要求
- 部署时需要确保 `docs/` 目录存在
- 使用 `git clone` 或 `scp -r` 时包含 docs 目录

### 2. 权限管理
```bash
# 确保 docs 目录权限正确
chmod -R 755 docs/
```

### 3. 生产环境
可以将 docs 部署到专门的目录：
```yaml
# docker-compose.prod.yml
volumes:
  - /var/www/nex-design-docs:/app/dist/docs:ro
```

## 📚 相关文档

- **QUICKSTART.md** - 快速参考和常用命令
- **DEPLOYMENT.md** - 完整部署文档
- **docs/DOCKER_DOCS_SETUP.md** - 卷挂载方案详细说明

## 🎉 总结

**核心优势：**
- 修改文档 → 立即生效
- 简化构建流程
- 提升开发体验

**一行配置搞定：**
```yaml
volumes:
  - ./docs:/app/dist/docs:ro
```

这就是你想要的方案！🎯