MCP Confluence Server

# Confluence Markdown 导出故障排除指南 ## 常见问题 ### 1. 页面访问问题 #### 问题：页面未找到 ``` 错误: 页面未找到: 123456789 ``` **可能原因：** - 页面ID不正确 - 页面已被删除或移动 - 页面在不同的空间中 **解决方案：** 1. 验证页面ID是否正确 2. 检查页面是否存在于Confluence中 3. 尝试使用 `spaceKey` + `title` 的方式获取页面 4. 确认页面没有被删除或归档 #### 问题：权限不足 ``` 错误: 没有权限访问页面: Page Title (123456789) ``` **可能原因：** - 用户没有页面访问权限 - 页面设置了特殊的访问限制 - 空间权限配置问题 **解决方案：** 1. 确认用户有访问该页面的权限 2. 检查空间的权限设置 3. 联系Confluence管理员获取权限 4. 尝试使用具有更高权限的账户 ### 2. 文件系统问题 #### 问题：文件写入失败 ``` 错误: 文件写入失败: /path/to/file.md ``` **可能原因：** - 目录不存在或没有写入权限 - 磁盘空间不足 - 文件被其他程序占用 - 路径包含非法字符 **解决方案：** 1. 检查目标目录的权限设置 2. 确保有足够的磁盘空间 3. 关闭可能占用文件的程序 4. 使用不同的输出目录 5. 检查文件名是否包含特殊字符 #### 问题：目录创建失败 ``` 错误: 目录创建失败: /path/to/directory ``` **可能原因：** - 父目录不存在 - 权限不足 - 路径过长 - 文件系统限制 **解决方案：** 1. 手动创建父目录 2. 检查目录权限 3. 使用较短的路径 4. 更改输出目录到有权限的位置 ### 3. 内容转换问题 #### 问题：内容转换失败 ``` 错误: 内容转换失败: Page Title ``` **可能原因：** - 页面包含不支持的HTML元素 - 内容过大导致内存不足 - 特殊字符编码问题 - Confluence宏无法转换 **解决方案：** 1. 检查页面原始内容是否包含特殊元素 2. 尝试分章节导出大页面 3. 检查页面编码格式 4. 手动处理不支持的宏内容 #### 问题：章节拆分失败 ``` 警告: 页面 "Page Title" 没有找到合适的标题进行拆分 ``` **可能原因：** - 页面没有指定级别的标题 - 标题格式不标准 - 内容结构不适合拆分 **解决方案：** 1. 检查页面是否有H1、H2、H3标题 2. 调整 `splitLevel` 参数 3. 使用单文件导出模式 4. 手动添加标题结构 ### 4. 网络和API问题 #### 问题：网络连接超时 ``` 错误: ETIMEDOUT - 网络请求超时 ``` **可能原因：** - 网络连接不稳定 - Confluence服务器响应慢 - 防火墙阻止连接 - API限制 **解决方案：** 1. 检查网络连接 2. 增加超时时间配置 3. 检查防火墙设置 4. 减少并发请求数量 5. 稍后重试 #### 问题：API限制 ``` 错误: 429 Too Many Requests ``` **可能原因：** - 请求频率过高 - 并发数量过大 - Confluence API限制 **解决方案：** 1. 减少并发数量（concurrency参数） 2. 增加请求间隔 3. 分批处理大量页面 4. 联系管理员调整API限制 ### 5. 性能问题 #### 问题：导出速度慢 **症状：** - 单个页面导出时间过长 - 批量导出进度缓慢 - 系统资源占用高 **解决方案：** 1. **调整并发设置** ```json { "concurrency": 2 // 降低并发数 } ``` 2. **分批处理** ```json { "pageIds": ["1", "2", "3"], // 减少单次处理的页面数 "concurrency": 1 } ``` 3. **优化网络** - 检查网络延迟 - 使用更快的网络连接 - 确保Confluence服务器响应正常 #### 问题：内存使用过高 **症状：** - 系统内存占用持续增长 - 导出过程中出现内存不足错误 - 系统变慢或卡顿 **解决方案：** 1. **启用章节拆分** ```json { "splitByChapters": true, "splitLevel": "2" } ``` 2. **减少并发数** ```json { "concurrency": 1 } ``` 3. **分批处理大文档** - 避免同时处理多个大页面 - 定期重启服务释放内存 ### 6. 特殊内容处理 #### 问题：图片和附件丢失 **症状：** - 导出的Markdown中图片显示异常 - 附件链接无法访问 **解决方案：** 1. **启用附件保留** ```json { "preserveAttachments": true } ``` 2. **检查图片链接** - 确认原始页面中的图片可以访问 - 检查图片URL是否正确 3. **手动处理附件** - 从Confluence下载附件 - 更新Markdown中的链接 #### 问题：表格格式错误 **症状：** - 复杂表格转换后格式混乱 - 表格内容丢失或错位 **解决方案：** 1. **检查原始表格** - 确认Confluence中的表格格式正确 - 简化复杂的表格结构 2. **手动调整** - 导出后手动修复表格格式 - 使用Markdown表格语法重新编写 #### 问题：代码块格式问题 **症状：** - 代码块没有语法高亮 - 代码格式不正确 **解决方案：** 1. **检查原始代码块** - 确认Confluence中使用了代码宏 - 检查语言设置 2. **手动添加语言标识** ```markdown ```javascript // 代码内容 ``` ``` ## 调试技巧 ### 1. 启用详细日志 ```bash DEBUG=* npx @modelcontextprotocol/inspector node dist/index.js ``` ### 2. 检查导出摘要 每次导出完成后，仔细查看导出摘要： - 成功/失败统计 - 文件大小和数量 - 耗时信息 - 错误详情 ### 3. 验证输出文件 - 检查Markdown语法是否正确 - 验证链接和图片引用 - 确认元数据完整性 - 测试文件可读性 ### 4. 分步调试 1. 先导出单个简单页面 2. 逐步增加复杂度 3. 测试不同的导出选项 4. 记录问题和解决方案 ## 性能优化建议 ### 1. 批量导出优化 ```json { "pageIds": ["1", "2", "3", "4", "5"], "concurrency": 2, // 适中的并发数 "outputDir": "batch-export" } ``` ### 2. 大文档处理 ```json { "pageId": "large-doc-id", "splitByChapters": true, // 启用章节拆分 "splitLevel": "2", // 适当的拆分级别 "includeMetadata": false // 减少文件大小 } ``` ### 3. 层次结构导出 ```json { "pageId": "root-page-id", "maxDepth": 3, // 限制递归深度 "includeChildren": true } ``` ## 联系支持 如果遇到无法解决的问题： 1. **收集信息** - 错误消息的完整内容 - 导出参数配置 - 系统环境信息 - 重现步骤 2. **检查日志** - 启用详细日志模式 - 记录完整的错误堆栈 - 注意时间戳和请求ID 3. **提供示例** - 问题页面的ID或URL - 最小化的重现案例 - 预期结果和实际结果 4. **环境信息** - Node.js版本 - 操作系统 - Confluence版本 - 网络环境 --- *本故障排除指南会根据用户反馈持续更新*