372 lines
7.8 KiB
Markdown
372 lines
7.8 KiB
Markdown
# 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
|
||
|