VitePress Docker 部署指南

概述

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

功能特性

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

系统要求

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

快速开始

1. 准备配置文件

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

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

# API 服务器端口
API_PORT=3001

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

2. 构建并启动服务

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

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

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 导出配置
│   ├── index.md               # 首页
│   ├── guide/                  # 指南目录
│   ├── getting-started/        # 入门目录
│   └── ...                    # 其他文档
├── docker-compose.yml          # Docker Compose 配置
├── package.json               # 项目依赖 **构建docker时使用**
└── .env                       # 环境变量配置

常用命令

直接拉取image

docker pull xeden3/vitepress-docker:latest

启动服务

# 前台运行
docker-compose up

# 后台运行
docker-compose up -d

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

停止服务

# 停止服务
docker-compose down

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

查看日志

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

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

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

重启服务

# 重启所有服务
docker-compose restart

环境变量配置

可用环境变量

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

配置示例

使用相对路径（默认）

DOCS_DIR=./docs

使用绝对路径

Windows:

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

Linux/Mac:

DOCS_DIR=/home/user/docs

自定义文档目录

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

方法一：通过 .env 文件

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

DOCS_DIR=./docs

方法二：通过命令行

# 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 配置：

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

PDF 导出功能

使用 API 导出 PDF

API 服务提供以下端点：

健康检查

curl http://localhost:3001/health

导出 PDF

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

查看已导出的 PDF

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 系统复制字体文件：

   # 假设容器名称为 vitepress-docker
   docker cp C:\Windows\Fonts\msyh.ttc vitepress-docker:/usr/share/fonts/truetype/
   

2. 进入容器更新字体缓存：

   docker exec vitepress-docker fc-cache -fv
   

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

故障排除

容器无法启动

1. 检查端口占用：

   # Windows
   netstat -ano | findstr 3000
   netstat -ano | findstr 3001
   
   # Linux/Mac
   netstat -tuln | grep -E '3000|3001'
   

2. 检查 Docker 状态：

   docker ps
   docker-compose ps
   

3. 查看错误日志：

   docker-compose logs --tail=50
   

文档目录挂载失败

1. 确认目录存在：

   ls -la ./docs
   

2. 检查权限：

   # Linux/Mac 可能需要授权
   chmod 755 ./docs
   

3. 使用绝对路径尝试

PDF 导出失败

1. 检查容器日志：

   docker-compose logs -f
   

2. 验证 Chromium 安装：

   docker exec vitepress-docker which chromium
   

3. 检查文档目录权限：

   docker exec vitepress-docker ls -la /app/docs
   

4. 确认 VitePress 服务正常运行：

   curl http://localhost:3000
   

服务无法访问

1. 检查容器状态：

   docker ps | grep vitepress
   

2. 检查防火墙设置：

   # Windows
   netsh advfirewall firewall show rule name="Docker VitePress"
   

3. 尝试重启服务：

   docker-compose restart
   

技术栈

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