docker-vitepress/docker/API.md

VitePress API Documentation

概述

VitePress Docker 服务提供了一套完整的 RESTful API，用于管理文档系统和 PDF 导出功能。

服务地址

• API 服务: http://localhost:3001
• VitePress 文档: http://localhost:3000

API 端点概览

方法	端点	描述
GET	/health	健康检查
GET	/export-pdf	导出 PDF
GET	/pdf-files	列出所有 PDF 文件

---

API 端点详情

1. 健康检查

端点: GET /health

检查 API 服务和 VitePress 服务是否正常运行。

响应示例:

{
  "status": "ok",
  "timestamp": "2026-04-11T12:00:00.000Z",
  "services": {
    "api": "running",
    "vitepress": "running"
  }
}

状态码:

• 200 OK: 服务正常运行

curl 示例:

curl http://localhost:3001/health

---

2. 导出 PDF

端点: GET /export-pdf

启动 PDF 导出流程，将当前 VitePress 文档导出为 PDF 文件。

请求参数:

参数	类型	必需	默认值	说明
fileName	string	否	export-{timestamp}.pdf	导出文件名

示例请求:

# 使用默认文件名
curl "http://localhost:3001/export-pdf"

# 指定文件名
curl "http://localhost:3001/export-pdf?fileName=HF-MES-Manual.pdf"

成功响应:

{
  "success": true,
  "message": "PDF exported successfully",
  "pdfPath": "/app/docs/HF-MES-Manual.pdf",
  "pdfUrl": "HF-MES-Manual.pdf",
  "fileName": "HF-MES-Manual.pdf",
  "fileSize": 1234567,
  "fileSizeMB": "1.18"
}

错误响应:

{
  "success": false,
  "error": "PDF file was not created",
  "stack": "Error: PDF file was not created..."
}

状态码:

• 200 OK: PDF 导出成功
• 500 Internal Server Error: 导出失败

工作流程:

1. 清理旧的 .vitepress/dist 目录
2. 检查 VitePress 开发服务器是否运行
3. 执行 npm run export-pdf 命令
4. 查找生成的 PDF 文件
5. 返回 PDF 文件信息

注意事项:

• PDF 文件会保存到配置的 DOCS_DIR 目录下
• 如果 VitePress 服务未运行，导出会失败
• 首次导出可能需要较长时间

---

3. 列出 PDF 文件

端点: GET /pdf-files

列出 DOCS_DIR 目录下所有已导出的 PDF 文件。

响应示例:

{
  "count": 2,
  "files": [
    {
      "name": "HF-MES-Manual.pdf",
      "size": 1234567,
      "sizeMB": "1.18",
      "created": "2026-04-11T12:00:00.000Z",
      "modified": "2026-04-11T12:00:00.000Z"
    },
    {
      "name": "export-123456.pdf",
      "size": 2345678,
      "sizeMB": "2.24",
      "created": "2026-04-11T11:00:00.000Z",
      "modified": "2026-04-11T11:00:00.000Z"
    }
  ]
}

文件信息字段:

字段	类型	说明
name	string	文件名
size	number	文件大小（字节）
sizeMB	string	文件大小（MB，保留两位小数）
created	string	文件创建时间（ISO 8601）
modified	string	文件最后修改时间（ISO 8601）

状态码:

• 200 OK: 成功获取文件列表
• 500 Internal Server Error: 读取目录失败

curl 示例:

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

---

使用示例

完整的 PDF 导出流程

# 1. 检查服务状态
curl http://localhost:3001/health

# 2. 导出 PDF（指定文件名）
curl "http://localhost:3001/export-pdf?fileName=My-Document.pdf"

# 3. 查看导出的文件
curl http://localhost:3001/pdf-files

# 4. 在浏览器中访问
# http://localhost:3000/My-Document.pdf

使用 JavaScript 调用

// 检查服务状态
async function checkHealth() {
  const response = await fetch('http://localhost:3001/health');
  const data = await response.json();
  console.log('Service Status:', data);
}

// 导出 PDF
async function exportPDF(fileName = null) {
  const url = fileName 
    ? `http://localhost:3001/export-pdf?fileName=${fileName}`
    : 'http://localhost:3001/export-pdf';
  
  const response = await fetch(url);
  const data = await response.json();
  
  if (data.success) {
    console.log('PDF exported:', data.fileName);
    console.log('File size:', data.fileSizeMB, 'MB');
  } else {
    console.error('Export failed:', data.error);
  }
}

// 获取 PDF 列表
async function listPDFs() {
  const response = await fetch('http://localhost:3001/pdf-files');
  const data = await response.json();
  
  console.log(`Found ${data.count} PDF files:`);
  data.files.forEach(file => {
    console.log(`  - ${file.name} (${file.sizeMB} MB)`);
  });
}

使用 Python 调用

import requests

# 检查服务状态
def check_health():
    response = requests.get('http://localhost:3001/health')
    print(response.json())

# 导出 PDF
def export_pdf(file_name=None):
    url = 'http://localhost:3001/export-pdf'
    if file_name:
        url += f'?fileName={file_name}'
    
    response = requests.get(url)
    data = response.json()
    
    if data['success']:
        print(f"PDF exported: {data['fileName']}")
        print(f"File size: {data['fileSizeMB']} MB")
    else:
        print(f"Export failed: {data['error']}")

# 列出 PDF 文件
def list_pdfs():
    response = requests.get('http://localhost:3001/pdf-files')
    data = response.json()
    
    print(f"Found {data['count']} PDF files:")
    for file in data['files']:
        print(f"  - {file['name']} ({file['sizeMB']} MB)")

---

错误处理

常见错误

错误信息	可能原因	解决方案
PDF file was not created	VitePress 服务未运行	确认 http://localhost:3000 可访问
Export command failed	PDF 导出命令执行失败	检查容器日志
ENOENT: no such file or directory	文档目录不存在	确认 DOCS_DIR 配置正确

错误响应格式

所有错误响应都遵循以下格式：

{
  "success": false,
  "error": "错误描述信息",
  "stack": "错误堆栈信息（仅在开发环境显示）"
}

---

配置说明

环境变量

变量名	默认值	说明
API_PORT	3001	API 服务端口
DOCS_PATH	/app/docs	容器内文档目录路径
VITEPRESS_PORT	3000	VitePress 服务端口
NODE_ENV	production	Node.js 运行环境

Docker Compose 配置

services:
  vitepress:
    environment:
      - API_PORT=3001
      - DOCS_PATH=/app/docs
      - VITEPRESS_PORT=3000
      - NODE_ENV=production
    ports:
      - "3001:3001"
    volumes:
      - ${DOCS_DIR:-./docs}:/app/docs

---

注意事项

1. PDF 文件位置: 导出的 PDF 文件保存在配置的 DOCS_DIR 目录下，可直接在浏览器中通过 VitePress 服务访问

2. VitePress 服务依赖: PDF 导出功能依赖 VitePress 开发服务器运行，请确保 http://localhost:3000 可访问

3. 导出超时: PDF 导出命令超时时间设置为 3 分钟，大型文档可能需要更长的时间

4. 并发限制: 不建议同时发起多个 PDF 导出请求

5. CORS 支持: API 服务已启用 CORS，允许来自任何源的请求

6. 文件覆盖: 如果指定文件名已存在，导出时会被覆盖

---

技术实现

API 服务架构

Express.js Server (端口 3001)
├── /health        → 直接返回状态
├── /export-pdf    → 执行 export-pdf 脚本
└── /pdf-files     → 读取 DOCS_DIR 目录

PDF 导出流程

1. Client Request
   ↓
2. Clean .vitepress/dist
   ↓
3. Check VitePress Server
   ↓
4. Execute npm run export-pdf
   ↓
5. Find Generated PDF
   ↓
6. Return Response

依赖项

• express: Web 框架
• cors: 跨域资源共享
• fs-extra: 文件系统操作
• vitepress-export-pdf: PDF 导出插件

---

故障排除

服务无法访问

1. 检查容器状态：

   docker ps | grep vitepress
   

2. 检查端口占用：

   netstat -ano | findstr 3001
   

3. 查看日志：

   docker-compose logs -f vitepress
   

PDF 导出失败

1. 确认 VitePress 服务运行：

   curl http://localhost:3000
   

2. 检查容器日志：

   docker-compose logs -f
   

3. 验证文档目录挂载：

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

4. 检查权限：

   docker exec vitepress-docker whoami
   

文件列表为空

1. 确认 PDF 文件存在：

   ls -la ./docs/*.pdf
   

2. 检查 DOCS_DIR 配置：

   cat .env | grep DOCS_DIR
   

---

如有问题，请查看容器日志或联系技术支持。