docker-vitepress/README.md

# VitePress Docker 部署指南

## 概述

本项目提供了完整的 VitePress 文档系统 Docker 部署方案，包含 VitePress 文档服务、API 服务和 PDF 导出功能。

## 功能特性

- ✅ VitePress 文档服务（端口 3000）
- ✅ RESTful API 服务（端口 3001）
- ✅ PDF 导出功能
- ✅ 中文、俄语等多语言字体支持
- ✅ 跨平台部署支持

## 系统要求

- Docker 20.10+
- Docker Compose 2.0+
- 至少 2GB 可用内存

## 快速开始

### 1. 准备配置文件

在项目根目录创建 `.env` 文件：

```bash
# VitePress 文档服务器端口
VITEPRESS_PORT=3000

# API 服务器端口
API_PORT=3001

# 文档目录路径（相对于项目根目录）
DOCS_DIR=./docs
```

### 2. 构建并启动服务

下载当前的docker-compose.yml文件放到项目根目录

运行以下命令构建并启动服务：

```bash
# 构建镜像并启动服务
docker-compose up --build

# 或者后台运行
docker-compose up --build -d
```

**需要创建文档服务最小目录单元**

```
hf-mes-docs-vitepress/
├── docs/                            # VitePress 文档目录 **生产时使用**
│   ├── .vitepress/
│   │   ├── config.mjs               # VitePress 配置
│   │   ├── vitepress-pdf.config.ts  # PDF 导出配置
│   │   └── theme/
│   │       ├── index.ts             # 自定义主题入口，图片放大缩小配置
│   │       └── style/
│   │           └── print.css        # 打印样式，用于pdf导出
│   ├── index.md                     # 首页
│   ├── guide/                       # 指南目录(可选)
│   ├── getting-started/             # 入门目录(可选)
│   └── ...                          # 其他文档(可选)
├── docker-compose.yml               # Docker Compose 配置
└── .env                             # 环境变量配置
```

### 3. 验证服务状态

访问以下地址确认服务正常运行：

- **VitePress 文档**: http://localhost:3000
- **API 健康检查**: http://localhost:3001/health

## 目录结构（全项目）

```
hf-mes-docs-vitepress/
├── docker/
│   ├── api/
│   │   ├── server.js                # API 服务主文件
│   │   └── package.json             # API 依赖
│   ├── Dockerfile                   # Docker 镜像构建文件
│   └── docker-entrypoint.sh         # 容器启动脚本
├── docs/                            # VitePress 文档目录 **生产时使用**
│   ├── .vitepress/
│   │   ├── config.mjs               # VitePress 配置
│   │   ├── vitepress-pdf.config.ts  # PDF 导出配置
│   │   └── theme/
│   │       ├── index.ts             # 自定义主题入口，图片放大缩小配置
│   │       └── style/
│   │           └── print.css        # 打印样式，用于pdf导出
│   ├── index.md                     # 首页
│   ├── guide/                       # 指南目录(可选)
│   ├── getting-started/             # 入门目录(可选)
│   └── ...                          # 其他文档(可选)
├── docker-compose.yml               # Docker Compose 配置
├── package.json                     # 项目依赖 **构建docker时使用**
└── .env                             # 环境变量配置
```

## 常用命令


### 直接拉取image
```bash
docker pull xeden3/vitepress-docker:latest
```

### 启动服务
```bash
# 前台运行
docker-compose up

# 后台运行
docker-compose up -d

# 重新构建并启动
docker-compose up --build
```

### 停止服务

```bash
# 停止服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v
```

### 查看日志

```bash
# 查看所有日志
docker-compose logs -f

# 查看 API 服务日志
docker-compose logs -f api

# 查看最近 100 行日志
docker-compose logs --tail=100
```

### 重启服务

```bash
# 重启所有服务
docker-compose restart
```

## 环境变量配置

### 可用环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `VITEPRESS_PORT` | 3000 | VitePress 文档服务端口 |
| `API_PORT` | 3001 | API 服务端口 |
| `DOCS_DIR` | ./docs | 文档目录（支持绝对路径和相对路径） |
| `DOCS_PATH` | /app/docs | 容器内文档路径（固定值） |

### 配置示例

#### 使用相对路径（默认）

```bash
DOCS_DIR=./docs
```

#### 使用绝对路径

**Windows:**
```bash
DOCS_DIR=C:\Users\xeden\Desktop\MES使用手册\hf-mes-docs-vitepress\docs
```

**Linux/Mac:**
```bash
DOCS_DIR=/home/user/docs
```

## 自定义文档目录

默认情况下，Docker 会挂载项目根目录下的 `./docs` 文件夹到容器的 `/app/docs`。

### 方法一：通过 .env 文件

在项目根目录的 `.env` 文件中修改：

```bash
DOCS_DIR=./docs
```

### 方法二：通过命令行

```bash
# Linux/Mac
DOCS_DIR=/custom/path docker-compose up -d

# Windows PowerShell
$env:DOCS_DIR="C:\custom\docs"; docker-compose up -d
```

### 方法三：修改 docker-compose.yml

直接修改 `docker-compose.yml` 文件中的 `volumes` 配置：

```yaml
volumes:
  - /your/custom/path:/app/docs
```

## PDF 导出功能

### 使用 API 导出 PDF

API 服务提供以下端点：

#### 健康检查

```bash
curl http://localhost:3001/health
```

#### 导出 PDF

```bash
curl "http://localhost:3001/export-pdf"
```

#### 查看已导出的 PDF

```bash
curl http://localhost:3001/pdf-files
```

### PDF 文件位置

导出的 PDF 文件保存在你配置的 `DOCS_DIR` 目录下。

### 导出配置

PDF 导出使用 `vitepress-export-pdf` 插件，配置位于：

```
docs/.vitepress/vitepress-pdf.config.ts
```

如需自定义 PDF 导出选项，请修改该配置文件。

**导出文件名与 `vitepress-pdf.config.ts` 配置一致**

## 多语言支持

Docker 镜像已包含以下字体支持：

- ✅ 中文字体（文泉驿、Noto CJK）
- ✅ 俄文字体（DejaVu）
- ✅ 其他语言字体

### 使用自定义字体

如需使用 Windows 雅黑字体，可以：

1. 从 Windows 系统复制字体文件：
   ```bash
   # 假设容器名称为 vitepress-docker
   docker cp C:\Windows\Fonts\msyh.ttc vitepress-docker:/usr/share/fonts/truetype/
   ```

2. 进入容器更新字体缓存：
   ```bash
   docker exec vitepress-docker fc-cache -fv
   ```

3. 重新导出 PDF 即可使用新字体

## 故障排除

### 容器无法启动

1. 检查端口占用：
   ```bash
   # Windows
   netstat -ano | findstr 3000
   netstat -ano | findstr 3001
   
   # Linux/Mac
   netstat -tuln | grep -E '3000|3001'
   ```

2. 检查 Docker 状态：
   ```bash
   docker ps
   docker-compose ps
   ```

3. 查看错误日志：
   ```bash
   docker-compose logs --tail=50
   ```

### 文档目录挂载失败

1. 确认目录存在：
   ```bash
   ls -la ./docs
   ```

2. 检查权限：
   ```bash
   # Linux/Mac 可能需要授权
   chmod 755 ./docs
   ```

3. 使用绝对路径尝试

### PDF 导出失败

1. 检查容器日志：
   ```bash
   docker-compose logs -f
   ```

2. 验证 Chromium 安装：
   ```bash
   docker exec vitepress-docker which chromium
   ```

3. 检查文档目录权限：
   ```bash
   docker exec vitepress-docker ls -la /app/docs
   ```

4. 确认 VitePress 服务正常运行：
   ```bash
   curl http://localhost:3000
   ```

### 服务无法访问

1. 检查容器状态：
   ```bash
   docker ps | grep vitepress
   ```

2. 检查防火墙设置：
   ```bash
   # Windows
   netsh advfirewall firewall show rule name="Docker VitePress"
   ```

3. 尝试重启服务：
   ```bash
   docker-compose restart
   ```

## 技术栈

- **基础镜像**: Node.js 25
- **Web 服务器**: Express.js
- **文档框架**: VitePress
- **PDF 导出**: vitepress-export-pdf
- **浏览器引擎**: Chromium (Puppeteer)
- **容器化**: Docker + Docker Compose