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 服务是否正常运行。

**响应示例**:
```json
{
  "status": "ok",
  "timestamp": "2026-04-11T12:00:00.000Z",
  "services": {
    "api": "running",
    "vitepress": "running"
  }
}
```

**状态码**:
- `200 OK`: 服务正常运行

**curl 示例**:
```bash
curl http://localhost:3001/health
```

---

### 2. 导出 PDF

**端点**: `GET /export-pdf`

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

**请求参数**:

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

**示例请求**:

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

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

**成功响应**:
```json
{
  "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"
}
```

**错误响应**:
```json
{
  "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 文件。

**响应示例**:
```json
{
  "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 示例**:
```bash
curl http://localhost:3001/pdf-files
```

---

## 使用示例

### 完整的 PDF 导出流程

```bash
# 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 调用

```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 调用

```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 配置正确 |

### 错误响应格式

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

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

---

## 配置说明

### 环境变量

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

### Docker Compose 配置

```yaml
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. 检查容器状态：
   ```bash
   docker ps | grep vitepress
   ```

2. 检查端口占用：
   ```bash
   netstat -ano | findstr 3001
   ```

3. 查看日志：
   ```bash
   docker-compose logs -f vitepress
   ```

### PDF 导出失败

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

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

3. 验证文档目录挂载：
   ```bash
   docker exec vitepress-docker ls -la /app/docs
   ```

4. 检查权限：
   ```bash
   docker exec vitepress-docker whoami
   ```

### 文件列表为空

1. 确认 PDF 文件存在：
   ```bash
   ls -la ./docs/*.pdf
   ```

2. 检查 DOCS_DIR 配置：
   ```bash
   cat .env | grep DOCS_DIR
   ```

---

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