利用GitHub Action自动备份Notion数据到仓库

为什么要备份 Notion

Notion 这两年虽然总体稳定,但服务崩溃几次都把人吓出冷汗。"Local first"(本地优先)的呼声越来越大 —— 数据存哪都没在自己机器 / 仓库里靠谱。

但 Notion 的多端同步、协作、视图能力实在难以替代,完全切换到本地工具(Logseq、Obsidian)又有舍不得。折中方案:继续用 Notion,但自动备份到 GitHub 仓库。

实现方式:GitHub Actions 定时跑一个脚本,调用 Notion 非官方 API 把所有页面拉下来转 Markdown,推到 Git 仓库。出问题时本地 clone 仓库就有一份完整数据快照。

(顺便,Notion 本身的可用性其实还行 —— 看 Notion Status,但备份不为常态,为意外。)

需要 3 个 Token

这套方案依赖几个凭证:

1. token_v2

Notion 的用户 session token。F12 拿:

1. 登录 Notion 网页版
2. F12 → Network 标签 → 随便打开一个页面
3. 找到 getSpaces 这个 XHR 请求
4. 查看请求 Headers → Cookie → 找 token_v2=xxx,复制 xxx 这一长串

2. space_id

同样在 getSpaces 请求里,查看 Response,JSON 路径 spaces.{id} 里的 id 就是 space_id。

3. page_id

你要备份的 Notion 根页面 ID。在 Notion 里打开你想备份的页面,看 URL:

https://www.notion.so/your-name/Some-Page-Title-abcdef0123456789abcdef0123456789

URL 最末尾那段 32 位无连字符 hex 串就是 page_id。把它格式化成带连字符的标准 UUID:

abcdef01-2345-6789-abcd-ef0123456789

GitHub 仓库配置

1. 创建仓库

登录 GitHub → New Repository → 起个名字(notion-backup),勾选 Private(保护数据),Create。

2. 配置 Secrets

仓库 → Settings → Secrets and variables → Actions → New repository secret,添加三个:

• NOTION_TOKEN_V2
• NOTION_SPACE_ID
• NOTION_PAGE_ID

3. 添加 GitHub Action 工作流

在仓库根目录创建 .github/workflows/backup.yml:

name: Backup Notion

on:
  schedule:
    - cron: '0 0 * * *'  # 每天 UTC 0 点(北京 8 点)
  workflow_dispatch:        # 支持手动触发

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install notion-export
        run: npm install -g notion-export

      - name: Export Notion to Markdown
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN_V2 }}
          NOTION_SPACE_ID: ${{ secrets.NOTION_SPACE_ID }}
          NOTION_PAGE_ID: ${{ secrets.NOTION_PAGE_ID }}
        run: |
          notion-export --token "$NOTION_TOKEN" 
                        --space "$NOTION_SPACE_ID" 
                        --page "$NOTION_PAGE_ID" 
                        --format markdown 
                        --output ./backup

      - name: Commit changes
        run: |
          git config user.name "GitHub Action Bot"
          git config user.email "actions@github.com"
          git add ./backup
          git commit -m "Backup: $(date +%Y-%m-%d)" || echo "No changes"
          git push

用 notion-page-to-md 替代

有几个开源工具可以选,效果差不多:

• notion-to-md —— 用 Notion 官方 API,需要 integration token
• notionapi (Go) —— 用非官方 API,跟 token_v2 配套
• NotionExporter —— Python 版,用官方 Export API

各有取舍:

• 官方 API 派:稳定但有 rate limit + 部分 block 类型不支持
• token_v2 派:能拿到所有内容,但 token 失效需要重新刷

实际备份频率

建议 每天 1 次。Notion 内容更新频率不高,每天备份 ≈ 每 1 天损失,完全可接受。频次更高:

• 消耗 GitHub Actions 免费额度(每月 2000 分钟,够每天 1-2 次跑)
• Notion 文章特别多(几千页)的话,一次 export 可能要十几分钟,频次太高会撞前一次还没跑完

备份后的几个增强

1. 同步通知。备份完成或失败时,发 Telegram / 邮件通知:

- name: Notify on failure
  if: failure()
  run: |
    curl -X POST "https://api.telegram.org/bot$TG_BOT/sendMessage" 
         -d "chat_id=$TG_CHAT&text=Notion backup failed: $GITHUB_RUN_ID"

2. 增量备份。脚本只拉最近修改过的页面,而不是每天全量。需要 export 工具支持。

3. 加密备份。提交前用 GPG 加密 markdown 文件,只有自己能解。防止 GitHub 数据泄露。

4. 多目的地。同时推送到 GitHub + GitLab + 自己的 NAS,做多副本。

Token 失效怎么办

Notion 的 token_v2 是 cookie session,有效期 1 年。1 年后会失效,Action 跑起来报 401。

解决:再次登录 Notion 网页,F12 拿新 token,更新 GitHub Secret。一年一次,可以接受。

如果用官方 API + integration token,这种 token 不会过期,长期更稳定。但需要在 Notion 里把整个 workspace 共享给 integration,设置稍麻烦。

恢复流程

真到 Notion 挂了 / 账号被封,恢复:

1. 克隆备份仓库:git clone https://github.com/your-name/notion-backup.git
2. 整个 backup/ 目录就是你所有 Notion 内容的 Markdown 版本
3. 用 Obsidian / Logseq / 任何 Markdown 编辑器打开,继续工作
4. 如果一定要回 Notion 风格,导入工具(md-to-notion 之类)能把 Markdown 推回去

这套方案的核心价值:你的笔记从依赖一个 SaaS 服务,变成独立于任何 SaaS 的 Markdown 文件。Notion 仍然是日常用的"编辑器和视图层",但数据所有权一直在自己手里。

—— 别看了 · 2026