nex_design/docs/DOCKER_DOCS_SETUP.md

# 文档目录 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` - 快速参考