Initial commit
This commit is contained in:
420
docker/API.md
Normal file
420
docker/API.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
如有问题，请查看容器日志或联系技术支持。
|
||||
Reference in New Issue
Block a user