Cherry Studio 思源笔记导出问题排查指南

问题现象分析

在 Windows 和 macOS 系统环境下，部分用户在使用 Cherry Studio 导出内容到思源笔记时遇到失败情况。主要表现特征为：

1. 基础连接测试通过（API 地址和密钥验证正常）
2. 简单文本导出失败
3. 直接导出 Markdown 文件功能正常
4. 开发者工具显示 createDocWithMd 接口返回 403 状态码

根本原因定位

经过技术团队深入排查，发现该问题主要涉及两个技术层面因素：

1. 本地回环地址限制
   部分系统环境下，127.0.0.1 本地回环地址存在特殊限制策略，导致 API 调用被拒绝。改用局域网实际 IP（如 192.168.x.x）后通信恢复正常。

2. 端口配置冲突
   思源笔记服务默认使用 6808 端口，当该端口被其他服务占用或存在防火墙限制时，会导致 API 调用失败。切换备用端口可解决此问题。

解决方案

方法一：修改连接地址

1. 获取本机局域网 IP 地址
2. 在 Cherry Studio 设置中将 API 地址从 127.0.0.1 替换为实际 IP
3. 确保思源笔记配置中允许该 IP 访问

方法二：调整服务端口

1. 修改思源笔记配置文件 config.json
2. 将 serverPort 调整为未被占用的端口（如 6809）
3. 重启思源笔记服务使配置生效
4. 同步更新 Cherry Studio 中的端口设置

技术原理补充

思源笔记的导出功能实际上是通过以下技术流程实现的：

1. 内容转换引擎将对话记录转换为标准 Markdown 格式
2. 通过 REST API 调用思源笔记的文档创建接口
3. 接口鉴权采用 Token 验证机制
4. 请求体包含笔记本ID、文档路径和Markdown内容三要素

当遇到 403 状态码时，表明虽然连接建立成功，但服务端拒绝了具体操作请求。这通常意味着：

• 身份验证令牌失效
• 请求来源 IP 不在白名单
• 端口通信存在策略限制

最佳实践建议

1. 网络配置方面：

   • 优先使用局域网实际 IP 替代 127.0.0.1
   • 在路由器设置中固定本机 IP 地址
   • 关闭可能干扰的防火墙规则

2. 软件配置方面：

   • 定期更新思源笔记和 Cherry Studio 到最新版本
   • 为开发环境配置专用端口组
   • 在测试环境验证导出功能后再投入生产使用

3. 故障排查流程：

   • 先验证基础连接（ping/telnet）
   • 再检查接口级通信（开发者工具）
   • 最后分析服务端日志（思源笔记工作目录下的日志文件）

通过以上技术方案，用户可以有效解决思源笔记导出失败的问题，确保知识管理流程的顺畅运行。