有道云笔记本地备份完全指南：从安装到自动化备份

一、为什么需要备份云笔记？

云笔记作为数字时代的知识管理工具，存储了大量个人和工作信息。然而，云端服务可能面临数据丢失、服务终止或账号异常等风险。有道云笔记备份工具通过将笔记导出为通用的Markdown格式，帮助用户建立本地数据副本，确保信息安全可控。本工具支持完整格式转换、图片自动下载和批量处理，特别适合需要数据主权的用户。

二、准备工作

2.1 环境要求

• 操作系统：Windows/macOS/Linux
• 运行环境：Python 3.6及以上
• 存储空间：至少100MB（根据笔记数量调整）

2.2 安装步骤

2.2.1 获取工具源码

打开终端（Windows用户建议使用PowerShell），执行以下命令下载工具：

git clone https://gitcode.com/gh_mirrors/yo/youdaonote-pull
cd youdaonote-pull

2.2.2 安装依赖包

工具需要以下Python库支持（已在requirements.txt中列出）：

pip install -r requirements.txt

三、核心配置详解

3.1 登录凭证配置（cookies.json）

这是连接有道云笔记的关键文件，需要手动创建并填写登录凭证：

1. 在项目根目录创建cookies.json文件
2. 按以下格式填写内容：

{
    "cookies": [
        [
            "YNOTE_CSTK",
            "您的CSTK值",
            ".note.youdao.com",
            "/"
        ],
        [
            "YNOTE_LOGIN", 
            "您的LOGIN值",
            ".note.youdao.com",
            "/"
        ],
        [
            "YNOTE_SESS",
            "您的SESS值",
            ".note.youdao.com",
            "/"
        ]
    ]
}

技术说明：这些Cookie值用于模拟登录状态，可通过浏览器开发者工具获取（网络请求中的Request Headers）

3.2 导出参数设置（config.json）

编辑项目根目录的config.json文件定制备份行为：

{
    "local_dir": "/Users/yourname/Documents/youdaonote_backup",  // 本地存储路径
    "ydnote_dir": "",  // 要备份的有道云笔记文件夹ID（留空备份全部）
    "smms_secret_token": "",  // 可选，SMMS图床Token（用于图片外链）
    "is_relative_path": true  // 图片路径是否使用相对路径
}

四、执行备份操作

4.1 基本备份流程

在项目目录执行以下命令启动备份：

python3 pull.py

工具执行流程：

1. 验证配置文件完整性
2. 建立与有道云笔记API的连接
3. 递归获取笔记目录结构
4. 按文件类型（笔记/图片/附件）分类处理
5. 将笔记转换为Markdown格式
6. 下载关联资源并更新链接

4.2 备份过程说明

• 进度显示：终端会实时显示当前处理的文件名和进度
• 错误处理：网络错误时会自动重试3次，严重错误会记录到app.log
• 增量备份：工具会对比本地文件修改时间，仅更新变更内容

五、功能解析与高级应用

5.1 核心功能模块

格式转换引擎（covert.py）

实现专有格式到Markdown的转换，支持：

• 标题层级转换（convert_heading_func）
• 图片自动下载与路径替换（convert_image_func）
• 代码块格式化（convert_code_func）
• 表格、待办事项等元素转换

云笔记API交互（api.py）

封装有道云笔记接口调用：

• 基于Cookie的身份验证（login_by_cookies）
• 目录结构获取（get_dir_info_by_id）
• 笔记内容下载（get_file_by_id）

图片处理模块（image.py）

提供两种图片存储方案：

• 本地存储：图片保存到images子目录
• 图床存储：通过SMMS API上传（需配置token）

5.2 高级使用技巧

按文件夹备份

修改config.json的ydnote_dir参数，填入特定文件夹ID实现部分备份：

{
    "ydnote_dir": "1234567890"  // 替换为目标文件夹ID
}

定期自动备份（Linux/macOS）

使用crontab设置每月自动备份：

# 编辑定时任务
crontab -e
# 添加以下行（每月1日凌晨2点执行）
0 2 1 * * cd /path/to/youdaonote-pull && python3 pull.py >> backup.log 2>&1

六、常见问题解决

6.1 登录失败

• 检查Cookie有效性：Cookie有效期通常为30天，过期需重新获取
• 确认域名匹配：确保Cookie的domain字段为.note.youdao.com

6.2 图片无法显示

• 检查is_relative_path配置是否为true
• 确认local_dir目录有写入权限
• 查看app.log中的图片下载错误信息

6.3 备份中断

• 网络不稳定时建议分批次备份
• 大文件（>10MB）可能导致超时，可单独处理

七、数据安全与管理建议

1. 备份存储：建议将备份文件同步到外部硬盘或加密云盘
2. 定期验证：每月随机抽查1-2篇笔记，确认格式和图片完整性
3. 版本管理：重要备份可添加时间戳（如backup_20231001）
4. 配置备份：定期导出cookies.json和config.json到安全位置

通过本工具，您可以将有道云笔记的内容完全掌控在自己手中，既避免了云端服务的依赖风险，也为知识管理提供了更多可能性。无论是个人用户还是小型团队，都能通过简单配置实现专业级的数据备份方案。