179 lines
3.8 KiB
Markdown
179 lines
3.8 KiB
Markdown
# 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
|
||
```
|
||
|
||
这就是你想要的方案！🎯
|