7.2 KiB

Raw Permalink Blame History

文档目录 Docker 部署方案

问题描述

应用中 /design 路由通过 fetch('/docs/...') 加载项目根目录下 docs/ 文件夹中的 Markdown 文档。在 Docker 容器中运行时，需要确保这些文档能够被访问。

解决方案：Docker 卷挂载

采用 Docker 卷挂载方式，将宿主机的 docs/ 目录直接映射到容器内，实现文档的实时更新和灵活管理。

配置方式

docker-compose.yml 配置

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. 启动服务

# 第一次启动（构建镜像）
docker-compose up -d --build

# 后续启动（使用已有镜像）
docker-compose up -d

2. 修改文档

# 在宿主机直接编辑文档
vim docs/DESIGN_COOKBOOK.md

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

3. 验证更新

# 文档修改后立即生效，无需任何操作
# 浏览器刷新即可看到最新内容

# 或使用 curl 验证
curl http://localhost:3000/docs/DESIGN_COOKBOOK.md

验证挂载

# 检查容器内的挂载情况
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 目录

# 使用 git clone 或 scp 上传整个项目
git clone <repo> /path/to/deploy
cd /path/to/deploy
docker-compose up -d

方式二：单独管理文档

# 文档单独部署在某个目录
mkdir -p /var/www/nex-design-docs
# 上传文档到该目录

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

2. 权限管理

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

# 只读挂载可防止容器内修改，但宿主机权限仍需控制

3. 多环境配置

可以为不同环境创建不同的 docker-compose 文件：

# docker-compose.dev.yml - 开发环境
volumes:
  - ./docs:/app/dist/docs:ro

# docker-compose.prod.yml - 生产环境
volumes:
  - /var/www/docs:/app/dist/docs:ro

使用时指定配置文件：

docker-compose -f docker-compose.prod.yml up -d

故障排查

问题 1：文档无法加载

# 检查挂载是否成功
docker inspect nex-design-app | grep -A 10 Mounts

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

# 检查文件权限
ls -la docs/

问题 2：修改后未生效

# 确认使用的是卷挂载而不是 COPY
docker exec nex-design-app cat /app/dist/docs/DESIGN_COOKBOOK.md

# 检查浏览器缓存
# 使用 Ctrl+Shift+R 强制刷新

# 检查 serve 是否缓存了静态文件
docker-compose restart

问题 3：Windows 路径问题

Windows 下需要注意路径格式：

# 错误
volumes:
  - .\docs:/app/dist/docs:ro

# 正确
volumes:
  - ./docs:/app/dist/docs:ro

性能考虑

1. 卷挂载性能

Linux/macOS: 性能很好，几乎无损耗
Windows/macOS + Docker Desktop: 可能有轻微性能损耗
生产环境: 使用 Linux 主机，性能最佳

2. 优化建议

如果文档很多且访问频繁，可考虑：

使用命名卷：

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

缓存策略：在 Nginx 反向代理中添加缓存：

location /docs/ {
    proxy_pass http://nex_design;
    proxy_cache_valid 200 10m;
    add_header X-Cache-Status $upstream_cache_status;
}

替代方案对比

方案 A: 构建时复制（未采用）

# Dockerfile
COPY docs /app/dist/docs

❌ 缺点：

修改文档需要重新构建镜像
镜像体积更大
更新流程复杂

✅ 优点：

镜像自包含
适合不常修改的场景

方案 B: prebuild 脚本（未采用）

{
  "scripts": {
    "prebuild": "cp -r docs public/"
  }
}