371 lines
7.2 KiB
Markdown
371 lines
7.2 KiB
Markdown
# 文档目录 Docker 部署方案
|
||
|
||
## 问题描述
|
||
|
||
应用中 `/design` 路由通过 `fetch('/docs/...')` 加载项目根目录下 `docs/` 文件夹中的 Markdown 文档。在 Docker 容器中运行时，需要确保这些文档能够被访问。
|
||
|
||
## 解决方案：Docker 卷挂载
|
||
|
||
采用 Docker 卷挂载方式，将宿主机的 `docs/` 目录直接映射到容器内，实现文档的实时更新和灵活管理。
|
||
|
||
### 配置方式
|
||
|
||
#### docker-compose.yml 配置
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
nex-design:
|
||
build:
|
||
context: .
|
||
dockerfile: Dockerfile
|
||
volumes:
|
||
- ./logs:/app/logs # 日志目录挂载
|
||
- ./docs:/app/dist/docs:ro # 文档目录挂载（只读）
|
||
```
|
||
|
||
**说明：**
|
||
- `./docs:/app/dist/docs` - 将宿主机当前目录的 `docs` 映射到容器的 `/app/dist/docs`
|
||
- `:ro` - 只读挂载，提高安全性，防止容器内进程修改文档
|
||
|
||
### 方案优势
|
||
|
||
✅ **实时更新**
|
||
- 修改 MD 文件后立即生效
|
||
- 无需重新构建 Docker 镜像
|
||
- 无需重启容器
|
||
|
||
✅ **方便维护**
|
||
- 在宿主机直接编辑文档
|
||
- 使用熟悉的编辑器和工具
|
||
- 支持版本控制
|
||
|
||
✅ **轻量镜像**
|
||
- Docker 镜像不包含文档内容
|
||
- 镜像体积更小
|
||
- 构建速度更快
|
||
|
||
✅ **灵活部署**
|
||
- 可以独立管理文档版本
|
||
- 支持多环境部署（开发、测试、生产使用不同文档）
|
||
- 易于更新和回滚
|
||
|
||
### 目录结构
|
||
|
||
**宿主机：**
|
||
```
|
||
nex-design/
|
||
├── docs/ # 文档源文件（Git 管理）
|
||
│ ├── DESIGN_COOKBOOK.md
|
||
│ ├── components/
|
||
│ │ ├── PageTitleBar.md
|
||
│ │ ├── ListTable.md
|
||
│ │ └── ...
|
||
│ └── pages/
|
||
├── dist/ # 构建产物（容器内）
|
||
│ ├── index.html
|
||
│ └── assets/
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
**容器内：**
|
||
```
|
||
/app/
|
||
├── dist/ # 应用构建产物
|
||
│ ├── index.html
|
||
│ ├── assets/
|
||
│ └── docs/ # 挂载点 → 宿主机 docs/
|
||
├── logs/ # 日志目录（挂载）
|
||
└── ecosystem.config.js # PM2 配置
|
||
```
|
||
|
||
### 使用流程
|
||
|
||
#### 1. 启动服务
|
||
|
||
```bash
|
||
# 第一次启动（构建镜像）
|
||
docker-compose up -d --build
|
||
|
||
# 后续启动（使用已有镜像）
|
||
docker-compose up -d
|
||
```
|
||
|
||
#### 2. 修改文档
|
||
|
||
```bash
|
||
# 在宿主机直接编辑文档
|
||
vim docs/DESIGN_COOKBOOK.md
|
||
|
||
# 或使用 VS Code 等编辑器
|
||
code docs/components/PageTitleBar.md
|
||
```
|
||
|
||
#### 3. 验证更新
|
||
|
||
```bash
|
||
# 文档修改后立即生效，无需任何操作
|
||
# 浏览器刷新即可看到最新内容
|
||
|
||
# 或使用 curl 验证
|
||
curl http://localhost:3000/docs/DESIGN_COOKBOOK.md
|
||
```
|
||
|
||
### 验证挂载
|
||
|
||
```bash
|
||
# 检查容器内的挂载情况
|
||
docker exec nex-design-app ls -la /app/dist/docs/
|
||
|
||
# 查看某个文档内容
|
||
docker exec nex-design-app cat /app/dist/docs/DESIGN_COOKBOOK.md
|
||
|
||
# 验证文件同步
|
||
# 在宿主机修改文件
|
||
echo "# Test" >> docs/test.md
|
||
|
||
# 立即在容器内查看
|
||
docker exec nex-design-app cat /app/dist/docs/test.md
|
||
```
|
||
|
||
### 部署注意事项
|
||
|
||
#### 1. 生产环境部署
|
||
|
||
**方式一：携带 docs 目录**
|
||
```bash
|
||
# 使用 git clone 或 scp 上传整个项目
|
||
git clone <repo> /path/to/deploy
|
||
cd /path/to/deploy
|
||
docker-compose up -d
|
||
```
|
||
|
||
**方式二：单独管理文档**
|
||
```bash
|
||
# 文档单独部署在某个目录
|
||
mkdir -p /var/www/nex-design-docs
|
||
# 上传文档到该目录
|
||
|
||
# 修改 docker-compose.yml
|
||
volumes:
|
||
- /var/www/nex-design-docs:/app/dist/docs:ro
|
||
```
|
||
|
||
#### 2. 权限管理
|
||
|
||
```bash
|
||
# 确保 docs 目录有正确的权限
|
||
chmod -R 755 docs/
|
||
|
||
# 只读挂载可防止容器内修改，但宿主机权限仍需控制
|
||
```
|
||
|
||
#### 3. 多环境配置
|
||
|
||
可以为不同环境创建不同的 docker-compose 文件：
|
||
|
||
```bash
|
||
# docker-compose.dev.yml - 开发环境
|
||
volumes:
|
||
- ./docs:/app/dist/docs:ro
|
||
|
||
# docker-compose.prod.yml - 生产环境
|
||
volumes:
|
||
- /var/www/docs:/app/dist/docs:ro
|
||
```
|
||
|
||
使用时指定配置文件：
|
||
```bash
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
### 故障排查
|
||
|
||
#### 问题 1：文档无法加载
|
||
|
||
```bash
|
||
# 检查挂载是否成功
|
||
docker inspect nex-design-app | grep -A 10 Mounts
|
||
|
||
# 检查容器内文件
|
||
docker exec nex-design-app ls -la /app/dist/docs/
|
||
|
||
# 检查文件权限
|
||
ls -la docs/
|
||
```
|
||
|
||
#### 问题 2：修改后未生效
|
||
|
||
```bash
|
||
# 确认使用的是卷挂载而不是 COPY
|
||
docker exec nex-design-app cat /app/dist/docs/DESIGN_COOKBOOK.md
|
||
|
||
# 检查浏览器缓存
|
||
# 使用 Ctrl+Shift+R 强制刷新
|
||
|
||
# 检查 serve 是否缓存了静态文件
|
||
docker-compose restart
|
||
```
|
||
|
||
#### 问题 3：Windows 路径问题
|
||
|
||
Windows 下需要注意路径格式：
|
||
```yaml
|
||
# 错误
|
||
volumes:
|
||
- .\docs:/app/dist/docs:ro
|
||
|
||
# 正确
|
||
volumes:
|
||
- ./docs:/app/dist/docs:ro
|
||
```
|
||
|
||
### 性能考虑
|
||
|
||
#### 1. 卷挂载性能
|
||
|
||
- **Linux/macOS**: 性能很好，几乎无损耗
|
||
- **Windows/macOS + Docker Desktop**: 可能有轻微性能损耗
|
||
- **生产环境**: 使用 Linux 主机，性能最佳
|
||
|
||
#### 2. 优化建议
|
||
|
||
如果文档很多且访问频繁，可考虑：
|
||
|
||
1. **使用命名卷**：
|
||
```yaml
|
||
volumes:
|
||
docs-data:
|
||
driver: local
|
||
driver_opts:
|
||
type: none
|
||
o: bind
|
||
device: /path/to/docs
|
||
|
||
services:
|
||
nex-design:
|
||
volumes:
|
||
- docs-data:/app/dist/docs:ro
|
||
```
|
||
|
||
2. **缓存策略**：
|
||
在 Nginx 反向代理中添加缓存：
|
||
```nginx
|
||
location /docs/ {
|
||
proxy_pass http://nex_design;
|
||
proxy_cache_valid 200 10m;
|
||
add_header X-Cache-Status $upstream_cache_status;
|
||
}
|
||
```
|
||
|
||
## 替代方案对比
|
||
|
||
### 方案 A: 构建时复制（未采用）
|
||
|
||
```dockerfile
|
||
# Dockerfile
|
||
COPY docs /app/dist/docs
|
||
```
|
||
|
||
❌ 缺点：
|
||
- 修改文档需要重新构建镜像
|
||
- 镜像体积更大
|
||
- 更新流程复杂
|
||
|
||
✅ 优点：
|
||
- 镜像自包含
|
||
- 适合不常修改的场景
|
||
|
||
### 方案 B: prebuild 脚本（未采用）
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"prebuild": "cp -r docs public/"
|
||
}
|
||
}
|
||
```
|
||
|
||
❌ 缺点：
|
||
- 需要重新构建才能更新
|
||
- 增加构建时间
|
||
- 文档和代码耦合
|
||
|
||
### 方案 C: 卷挂载（✅ 当前采用）
|
||
|
||
```yaml
|
||
volumes:
|
||
- ./docs:/app/dist/docs:ro
|
||
```
|
||
|
||
✅ 优点：
|
||
- 实时更新
|
||
- 灵活管理
|
||
- 镜像轻量
|
||
|
||
⚠️ 注意：
|
||
- 需要保持 docs 目录结构
|
||
- 部署时需要文档文件
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 文档版本管理
|
||
|
||
```bash
|
||
# 使用 Git 管理文档版本
|
||
cd docs
|
||
git log DESIGN_COOKBOOK.md
|
||
|
||
# 回滚到特定版本
|
||
git checkout <commit-hash> DESIGN_COOKBOOK.md
|
||
```
|
||
|
||
### 2. 文档自动化部署
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# scripts/update-docs.sh
|
||
|
||
echo "更新文档..."
|
||
cd /path/to/nex-design
|
||
|
||
# 拉取最新文档
|
||
git pull origin main -- docs/
|
||
|
||
# 无需重启容器，文档即时生效
|
||
echo "文档已更新！"
|
||
```
|
||
|
||
### 3. 监控文档访问
|
||
|
||
可以在 Nginx 中记录文档访问日志：
|
||
```nginx
|
||
location /docs/ {
|
||
access_log /var/log/nginx/docs-access.log;
|
||
proxy_pass http://nex_design;
|
||
}
|
||
```
|
||
|
||
## 总结
|
||
|
||
使用 Docker 卷挂载方案是最灵活、最适合本项目的解决方案：
|
||
|
||
✅ **实时更新** - 修改即生效
|
||
✅ **简单维护** - 直接编辑文件
|
||
✅ **轻量镜像** - 更快的构建和部署
|
||
✅ **灵活部署** - 支持多种场景
|
||
|
||
**核心配置只需一行：**
|
||
```yaml
|
||
volumes:
|
||
- ./docs:/app/dist/docs:ro
|
||
```
|
||
|
||
## 相关文件
|
||
|
||
- `docker-compose.yml:16` - 卷挂载配置
|
||
- `DEPLOYMENT.md:14-35` - 部署文档说明
|
||
- `QUICKSTART.md` - 快速参考
|
||
|