Hello World
` - 注意：需要 URL 编码 - `theme` (string): 主题设置 - 可选值: `light` | `dark` - 示例: `?theme=dark` - `locale` (string): 语言设置 - 可选值: `zh-CN` | `en-US` - 示例: `?locale=en-US` ### 高级配置（JSON 格式） - `editorProps` (JSON string): 自定义编辑器属性 - `document` (JSON string): 自定义文档配置 - `page` (JSON string): 自定义页面配置 详细配置说明请参考 [frontend/README.md](./frontend/README.md) ## API 接口 ### POST /api/docx/parse 解析 DOCX 文件（支持文件上传或 URL） **请求参数：** - `file` (File, 可选): DOCX 文件（与 url 二选一） - `url` (string, 可选): DOCX 文件 URL（与 file 二选一） - `imageMode` (string): 图片处理方式，可选值: `base64` | `skip` | `placeholder` - `includeHeaders` (boolean): 是否包含页眉 - `includeFooters` (boolean): 是否包含页脚 - `includeMetadata` (boolean): 是否包含元数据 - `includeComments` (boolean): 是否包含批注 **响应格式：** ```json { "code": 200, "data": { "html": "解析后的HTML内容
", "messages": [ { "type": "info", "message": "解析完成" } ] } } ``` 详细 API 文档请参考 [backend/README.md](./backend/README.md) ## Docker 部署 本项目支持使用 Docker 和 Docker Compose 进行容器化部署，这是最简单快速的部署方式。 ### 前置要求 - Docker >= 20.10 - Docker Compose >= 2.0（或 Docker Desktop，已内置 Compose） ### 快速开始 #### 1. 构建并启动所有服务 ```bash # 在项目根目录执行 docker compose up -d --build ``` 此命令会： - 构建后端和前端镜像 - 创建独立的 Docker 网络 - 启动所有服务（后端、前端、Nginx 代理） #### 2. 查看服务状态 ```bash # 查看所有服务状态 docker compose ps # 查看服务日志 docker compose logs -f # 查看特定服务日志 docker compose logs -f backend docker compose logs -f frontend ``` #### 3. 访问服务 - **前端应用**: http://localhost:8080 - **后端 API**: http://localhost:8080/api - **Swagger 文档**: http://localhost:8080/api > 注意：默认使用 8080 端口，如需修改请设置 `NGINX_PORT` 环境变量 ### Docker 常用命令 #### 服务管理 ```bash # 启动所有服务 docker compose up -d # 停止所有服务 docker compose down # 停止并删除卷（清理数据） docker compose down -v # 重启服务 docker compose restart # 重启特定服务 docker compose restart backend ``` #### 构建和更新 ```bash # 重新构建并启动 docker compose up -d --build # 只构建特定服务 docker compose build backend docker compose build frontend # 不使用缓存重新构建 docker compose build --no-cache ``` #### 查看日志 ```bash # 查看所有服务日志（实时） docker compose logs -f # 查看后端日志 docker compose logs -f backend # 查看前端日志 docker compose logs -f frontend # 查看最近 100 行日志 docker compose logs --tail=100 backend ``` #### 进入容器调试 ```bash # 进入后端容器 docker compose exec backend sh # 进入前端容器 docker compose exec frontend sh # 在容器内查看 PM2 状态（后端） docker compose exec backend pm2 status # 在容器内查看 PM2 日志（后端） docker compose exec backend pm2 logs ``` #### 镜像管理 ```bash # 查看项目镜像 docker images | grep file-word # 删除项目镜像 docker rmi file-word-backend:latest file-word-frontend:latest # 清理未使用的镜像 docker image prune -a ``` ### 环境变量配置 在项目根目录创建 `.env` 文件来配置环境变量： ```bash # Nginx 端口（默认 8080） NGINX_PORT=8080 # 前端构建时环境变量 VITE_BASE_URL=http://localhost:8080 VITE_API_URL=/api # 后端环境变量（可选，已在 docker-compose.yml 中配置） APP_PORT=3000 APP_NAME=file-server-api GLOBAL_PREFIX=api LOGGER_LEVEL=info LOGGER_MAX_FILES=7 MAX_FILE_SIZE_MB=10 ``` ### 服务说明 #### 后端服务（backend） - **容器名**: `file-word-backend` - **镜像**: `file-word-backend:latest` - **端口**: 3000（内部，不对外暴露） - **进程管理**: 使用 PM2 管理 Node.js 进程 - 自动重启（最多 10 次） - 内存监控（超过 1GB 自动重启） - 日志管理 - **健康检查**: 每 30 秒检查 `/api` 端点 #### 前端服务（frontend） - **容器名**: `file-word-frontend` - **镜像**: `file-word-frontend:latest` - **端口**: 80（内部，不对外暴露） - **服务**: Nginx 静态文件服务 #### Nginx 反向代理（file-word-nginx-proxy） - **容器名**: `file-word-nginx-proxy` - **镜像**: `nginx:latest` - **端口**: 8080:80（对外暴露） - **功能**: 统一入口，代理前后端请求 ### 数据持久化 以下目录会被挂载到宿主机： - `./backend/logs`: 后端日志目录 - `./backend/docx`: 后端测试文件目录（可选） ### 故障排查 #### 1. 检查容器状态 ```bash docker compose ps ``` 确保所有容器状态为 `Up` 且健康检查通过。 #### 2. 查看容器日志 ```bash # 查看所有日志 docker compose logs # 查看特定服务日志 docker compose logs backend ``` #### 3. 检查端口占用 ```bash # Windows netstat -ano | findstr :8080 # Linux/Mac lsof -i :8080 ``` 如果 8080 端口被占用，可以修改 `.env` 文件中的 `NGINX_PORT`。 #### 4. 重启服务 ```bash # 重启所有服务 docker compose restart # 重启特定服务 docker compose restart backend ``` #### 5. 完全重建 ```bash # 停止并删除所有容器 docker compose down # 重新构建并启动 docker compose up -d --build ``` ### 生产环境建议 1. **修改端口映射**: 通过 `.env` 文件设置 `NGINX_PORT` 环境变量 2. **配置 HTTPS**: 在 `docker/nginx/nginx.conf` 中添加 SSL 证书配置 3. **设置资源限制**: 在 `docker-compose.yml` 中添加资源限制配置 4. **配置日志轮转**: 确保日志文件不会无限增长 5. **环境变量管理**: 使用 `.env` 文件管理敏感信息 6. **网络隔离**: 项目已使用独立网络 `file-word-network`，不会与其他项目冲突 ### Docker 部署 vs 传统部署 | 特性 | Docker 部署 | 传统部署（PM2） | |------|------------|----------------| | 部署速度 | ✅ 快速（一条命令） | ⚠️ 需要多步操作 | | 环境一致性 | ✅ 完全一致 | ⚠️ 依赖系统环境 | | 隔离性 | ✅ 完全隔离 | ❌ 共享系统资源 | | 扩展性 | ✅ 易于扩展 | ⚠️ 需要手动配置 | | 进程管理 | ✅ PM2 + Docker 双重保护 | ✅ PM2 管理 | | 适用场景 | 推荐用于所有环境 | 适合已有服务器环境 | ## 部署指南 ⚠️ **重要：必须按照以下顺序部署，先部署后端服务，获取 API 请求路径后，再部署前端应用。** ### 第一步：部署后端服务（backend） #### 1. 构建后端应用 ```bash cd backend pnpm install pnpm build ``` #### 2. 配置环境变量 在 `backend` 目录下创建 `.env` 文件，配置生产环境变量： ```bash APP_NAME=file-server-api APP_PORT=3000 APP_BASE_URL=https://api.example.com # 替换为实际的后端服务地址 GLOBAL_PREFIX=api APP_LOCALE=zh-CN LOGGER_LEVEL=info LOGGER_MAX_FILES=7 MAX_FILE_SIZE_MB=10 ``` #### 3. 安装 PM2（如果未安装） ```bash # 全局安装 PM2 npm install -g pm2 # 或使用 pnpm pnpm add -g pm2 ``` #### 4. 启动后端服务（使用 PM2） ⚠️ **重要：生产环境必须使用 PM2 进行进程管理，确保服务稳定运行。** ```bash # 使用 PM2 启动生产环境服务 pnpm pm2:start # 或直接使用 PM2 命令 pm2 start ecosystem.config.js --env production ``` **PM2 常用管理命令：** ```bash # 查看服务状态 pm2 status # 查看日志 pnpm pm2:logs # 或 pm2 logs file-server-api # 重启服务 pnpm pm2:restart # 或 pm2 restart file-server-api # 停止服务 pnpm pm2:stop # 或 pm2 stop file-server-api # 删除服务 pnpm pm2:delete # 或 pm2 delete file-server-api # 查看详细信息 pm2 show file-server-api # 监控服务 pm2 monit ``` **设置 PM2 开机自启：** ```bash # 保存当前 PM2 进程列表 pm2 save # 设置 PM2 开机自启 pm2 startup ``` #### 5. 验证后端服务 访问 API 文档确认服务正常运行： - API 文档地址：`http://your-backend-domain/api` - 健康检查：`http://your-backend-domain/api/docx/parse`（POST 请求） **记录后端 API 地址：** - API 基础 URL：`https://api.example.com`（示例，替换为实际地址） - API 路径前缀：`/api` - 完整 API 地址：`https://api.example.com/api` ### 第二步：部署前端应用（frontend） ⚠️ **注意：确保第一步中的后端服务已通过 PM2 成功启动并正常运行。** #### 1. 配置前端环境变量 在 `frontend` 目录下创建 `.env.prod` 文件，配置后端 API 地址： ```bash # 后端 API 基础 URL（从第一步获取） VITE_BASE_URL=https://api.example.com # API 路径前缀 VITE_API_URL=/api # 前端服务端口（可选） VITE_PORT=4000 ``` **重要：** `VITE_BASE_URL` 必须与第一步中部署的后端服务地址一致。 #### 2. 构建前端应用 ```bash cd frontend pnpm install pnpm build ``` 构建产物将输出到 `frontend/dist` 目录。 #### 3. 部署前端静态文件 将 `dist` 目录中的文件部署到静态文件服务器（如 Nginx、Apache 等）。 #### 4. 配置 Nginx（示例） ```nginx server { listen 80; server_name your-frontend-domain.com; root /path/to/frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } # 如果需要代理 API 请求 location /api { proxy_pass https://api.example.com; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` #### 5. 验证前端应用 访问前端地址，测试 DOCX 文件解析功能是否正常。 ### 部署检查清单 **后端服务：** - [ ] PM2 已安装 - [ ] 后端服务已通过 PM2 成功启动 - [ ] PM2 服务状态正常（使用 `pm2 status` 检查） - [ ] 后端 API 文档可正常访问 - [ ] 已获取后端 API 基础 URL - [ ] PM2 已设置开机自启（可选但推荐） **前端应用：** - [ ] 前端环境变量已正确配置后端 API 地址 - [ ] 前端应用已成功构建 - [ ] 前端静态文件已部署 - [ ] 前端可以正常调用后端 API - [ ] CORS 配置正确（如果前后端不同域） ## 开发 ### 本地开发环境 本地开发时也需要按照相同顺序启动服务： #### 1. 启动后端服务 ```bash cd backend pnpm install pnpm start:dev ``` 后端服务默认运行在 `http://localhost:3000`，API 文档地址：`http://localhost:3000/api` #### 2. 配置前端环境变量 在 `frontend` 目录下创建 `.env.dev` 文件： ```bash VITE_BASE_URL=http://127.0.0.1:3000 VITE_API_URL=/api VITE_PORT=4000 ``` #### 3. 启动前端应用 ```bash cd frontend pnpm install pnpm dev ``` 前端应用默认运行在 `http://localhost:4000` ### 构建生产版本 **后端：** ```bash cd backend pnpm install pnpm build # 使用 PM2 启动生产环境服务 pnpm pm2:start ``` **前端：** ```bash cd frontend pnpm install pnpm build ``` ## 技术栈 ### 前端 - Vue 3 - TypeScript - TipTap - Element Plus - UnoCSS - Vite ### 后端 - NestJS - TypeScript - Fastify - Mammoth.js - Swagger ## 注意事项 1. **部署顺序很重要**：必须先部署后端服务，获取 API 地址后，再配置和部署前端应用 2. **PM2 是必需的**：生产环境必须使用 PM2 启动和管理后端服务，不能直接使用 `node` 命令启动 3. **环境变量配置**：前端的环境变量 `VITE_BASE_URL` 必须指向实际的后端服务地址 4. **CORS 配置**：如果前后端部署在不同域名，确保后端服务已正确配置 CORS 5. **API 地址验证**：部署前端前，务必验证后端 API 可正常访问，可通过 `pm2 status` 和 `pm2 logs` 检查服务状态 6. 使用 `url` 参数时，确保 DOCX 文件 URL 可访问 7. JSON 格式的参数需要进行 URL 编码 8. 只读模式下，工具栏和底部信息栏会自动隐藏 ## 相关文档 - [前端编辑器文档](./frontend/README.md) - [后端 API 文档](./backend/README.md) ## License 本项目采用私有许可证，仅供内部使用。