nex_design/VOLUME_MOUNT_SOLUTION.md

Docker 卷挂载方案 - 实施总结

✅ 方案优势

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

🚀 实时更新

• 修改 MD 文档后立即生效
• 无需重新构建 Docker 镜像
• 无需重启容器
• 开发体验极佳

💡 简化流程

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

🔄 灵活部署

• 可以独立管理文档版本
• 支持多环境使用不同文档
• 易于回滚和更新

📝 实施内容

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

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 - 保持部署文档链接

🎯 使用方法

本地开发

yarn dev                    # 开发服务器

构建和预览

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

Docker 部署

# 首次部署
docker-compose up -d --build

# 后续启动
docker-compose up -d

# 查看日志
docker-compose logs -f

更新文档

# 直接编辑即可，立即生效
vim docs/DESIGN_COOKBOOK.md

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

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

🔍 验证方法

1. 检查挂载

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

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

2. 验证实时同步

# 在宿主机添加测试文件
echo "# Test" > docs/test.md

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

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

3. 浏览器访问

# 启动服务
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. 权限管理

# 确保 docs 目录权限正确
chmod -R 755 docs/

3. 生产环境

可以将 docs 部署到专门的目录：

# docker-compose.prod.yml
volumes:
  - /var/www/nex-design-docs:/app/dist/docs:ro

📚 相关文档

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

🎉 总结

核心优势：

• 修改文档 → 立即生效
• 简化构建流程
• 提升开发体验

一行配置搞定：

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

这就是你想要的方案！🎯