Scriptorium 配置指南¶

站点部署(Cloudflare Pages + Access)+ 笔记同步(Obsidian)的完整流程。一次配置,长期受益。

架构总览¶

                ┌──────────────────────────────────┐
                │        scriptorium (git)         │  ← 数据正本
                │  README / curriculum / notes /   │
                │  trading-exchanges-zh            │
                └────────────┬─────────────────────┘
                             │ git push
                             ▼
              ┌─────────────────────────────────┐
              │       GitHub Actions            │
              │  uv sync + uv run mkdocs build  │
              │  wrangler pages deploy site/    │
              └────────────┬────────────────────┘
                           │ wrangler API
                           ▼
              ┌─────────────────────────────────┐
              │    Cloudflare Pages (静态站点)   │
              │      scriptorium.pages.dev       │
              └────────────┬────────────────────┘
                           │ 鉴权前置
                           ▼
              ┌─────────────────────────────────┐
              │  Cloudflare Access(私有保护)    │
              │   Email/OTP 或 Google OAuth     │
              └────────────┬────────────────────┘
                           │ 通过验证
                           ▼
                ┌──────────────────────┐
                │  手机/桌面浏览器     │  ← 温习入口
                │  (PWA 可加主屏离线)  │
                └──────────────────────┘

并行通道:
  scriptorium (git) ──→ Obsidian Vault(本地写作 + 双向链接)
                    ──→ 移动端同步(Working Copy / iCloud / Syncthing)

第一部分:Cloudflare Pages + Access(私有站点)¶

1. 注册 Cloudflare 账号¶

cloudflare.com → Sign Up,免费账号即可。Pages 流量无上限,Access 50 用户以下免费。

2. 创建 API Token¶

dash.cloudflare.com/profile/api-tokens → Create Token:

选 "Custom Token"
权限(Permissions):
Account → Cloudflare Pages → Edit
Account Resources: Include → 你的账号
创建后复制 Token(只显示一次)

3. 获取 Account ID¶

Cloudflare Dashboard 任一站点页面 → 右侧栏 "Account ID",复制。

4. 把 Secrets 加入 GitHub¶

scriptorium 的 GitHub 仓库 → Settings → Secrets and variables → Actions → New repository secret,加两个:

Secret 名	值
`CLOUDFLARE_API_TOKEN`	第 2 步复制的 Token
`CLOUDFLARE_ACCOUNT_ID`	第 3 步复制的 Account ID

5. 创建 Cloudflare Pages 项目¶

Cloudflare Dashboard → Workers & Pages → Create application → Pages → Upload assets:

Project name: scriptorium(必须与 .github/workflows/docs.yml 中 --project-name=scriptorium 一致)
上传一个临时文件(随便一个 index.html 占位即可)
创建完成后,Production branch 自动是 main

选 "Upload assets" 而不是 "Connect to Git",这样 Cloudflare 看不到你的源码,只接收 GitHub Actions build 出来的 site/ 目录。

6. 配置 Cloudflare Access(私有保护)¶

Cloudflare Dashboard → Zero Trust → Access → Applications → Add an application:

Type: Self-hosted
Application name: Scriptorium
Application domain: scriptorium.pages.dev(或你绑定的自定义域名)
Session Duration: 24 hours(自选)
Identity providers: 至少加 One-time PIN(免注册,邮箱收一次性验证码)。可选 Google/GitHub OAuth。
Add a policy:
Policy name: Owner Only
Action: Allow
Include rule: Emails → 填入你自己的邮箱(可加多个)

保存后,任何访问 scriptorium.pages.dev 的请求都会被 Access 拦截,先验证邮箱才放行。

7. 触发首次部署¶

在 scriptorium 本地推一次代码到 main,GitHub Actions 自动跑 docs.yml workflow,build 完后 wrangler 推到 Pages:

git push

或者在 GitHub Actions 页面手动 Run workflow(因为 workflow 配了 workflow_dispatch)。

部署日志成功后,访问 https://scriptorium.pages.dev → Access 拦截 → 输入邮箱 → 收 PIN → 登录 → 看到站点。

8. 手机端"加到主屏幕"¶

在手机浏览器打开 site URL,Access 登录后:

iOS Safari: 分享按钮 → "添加到主屏幕"
Android Chrome: 菜单 → "添加到主屏幕"

之后从主屏图标打开,看起来像原生 App。MkDocs Material 内置 PWA 支持,断网也能看缓存过的页面。

第二部分:Obsidian(桌面写作 + 移动温习)¶

1. 桌面安装 Obsidian¶

obsidian.md 下载安装。打开后:

Open folder as vault → 选 ~/data/repos/github/the-alephain-guild/scriptorium
弹出 "Trust author" → 选 Trust

2. 推荐插件(Settings → Community plugins → Browse)¶

插件	用途	优先级
Obsidian Git	自动 commit/push,定时 backup	必装
Templater	笔记模板引擎,可绑定 `notes/_template.md`	必装
Dataview	用 SQL-like 查询 frontmatter,自动生成笔记索引	强推
Tag Wrangler	标签批量重命名/合并	推荐
Excalidraw	手绘画板,适合做架构图、市场结构示意	可选
Advanced Tables	表格快速编辑	可选
Mathematica / MathJax	LaTeX 渲染(de Prado 笔记会用)	与站点一致

Obsidian Git 设置: - Backup interval: 10 min - Auto pull on launch: ✓ - Auto push interval: 0(不自动 push,避免抢占 GitHub Actions 触发节奏;手动 push 更可控)

3. Templater 绑定模板¶

Settings → Templater: - Template folder location: notes/ - 之后新建笔记时,命令面板 (Cmd-P) → "Templater: Replace templates in active file" 自动填充模板

4. 移动端同步方案(按手机系统选)¶

选项 A:Working Copy + Obsidian Mobile(iOS 推荐)¶

App Store 装 Working Copy(一次买断,约 $20)
Working Copy 添加 scriptorium 仓库(SSH key 或 GitHub HTTPS + token)
Working Copy → Repository Settings → "Setup Folder",授权 Files.app 访问
App Store 装 Obsidian Mobile
Obsidian Mobile → Open vault → 选 Working Copy 仓库目录
写完笔记后,Working Copy 中手动 commit & push(或开启 Auto-push)

选项 B:iCloud Drive(iOS,免费,与 git 解耦)¶

这个方案下 Obsidian vault 通过 iCloud 同步,与 git 仓库逻辑分离。适合"手机只读温习"而不写笔记。

桌面 Obsidian vault 仍是 scriptorium 目录(写作主战场)
手机侧用 Cloudflare Pages 站点温习,不在手机写笔记
跳过本地 vault 同步问题

选项 C:Syncthing(跨平台,免费,P2P)¶

桌面装 Syncthing
iOS 装 Möbius Sync(Syncthing 兼容客户端) / Android 装 Syncthing-Android
配置 scriptorium 为 sync folder
注意 .obsidian/workspace*.json 等冲突文件加入 ignore patterns

选项 D:Obsidian Sync($4-8/月,官方)¶

一键设置,端到端加密,跨所有平台
收费,但省心

5. 推荐组合(按你的设备)¶

设备	桌面写作	手机温习	同步
macOS + iOS	Obsidian + Obsidian Git 插件	Cloudflare Pages 站点(主)+ Obsidian Mobile + Working Copy(可选)	Working Copy / Obsidian Sync
macOS + Android	Obsidian + Obsidian Git	Cloudflare Pages 站点(主)+ Obsidian Mobile + Syncthing-Android	Syncthing / Obsidian Sync
Windows + iOS	Obsidian + Obsidian Git	Cloudflare Pages 站点 + Obsidian Mobile + Working Copy	Working Copy

个人建议:手机端主要靠 Cloudflare Pages 站点温习(浏览体验最好,搜索/目录/深色模式齐全),Obsidian Mobile 作为补充。这样手机不需要 git 同步,大幅简化配置。

第三部分:End-to-End 验证¶

走一遍流程,确认全链路通畅:

桌面 Obsidian 用模板新建 notes/ai/A1-ml-foundations/2026-05-08-test.md
写一段内容 → Obsidian Git 自动 commit(10 分钟后)
手动 git push(或在 Obsidian Git 命令面板触发 push)
GitHub 仓库 → Actions → 看 Deploy docs to Cloudflare Pages workflow 是否成功
1-2 分钟后,访问 https://scriptorium.pages.dev
Cloudflare Access 拦截 → 邮箱验证 → 登录
站点能看到新笔记
手机浏览器打开 → 验证可访问
iOS:分享 → 添加到主屏 / Android:菜单 → 添加到主屏
飞行模式打开 PWA → 验证缓存的页面可看(离线温习)

故障排查¶

问题	原因	解决
Actions workflow 失败	secrets 未设置	重新检查 `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` 是否正确
`wrangler pages deploy` 报 401	API Token 权限不足	重新创建 Token,确保有 `Cloudflare Pages: Edit` 权限
Cloudflare 显示 "Project not found"	项目名不一致	确认 workflow 中 `--project-name=scriptorium` 与 Cloudflare 项目名一致
中文搜索不准	lunr.js 默认分词对中文不友好	后续可加 `mkdocs-jieba` 插件
Obsidian Git 在 iOS 不工作	iOS 沙箱限制	切换到 Working Copy 方案
`.obsidian/` 文件冲突	桌面/手机 Obsidian workspace 文件互相覆盖	`.gitignore` 已经 ignore `workspace*.json`,确认其他冲突项也加入
PWA 不显示"添加到主屏"	iOS Safari 必须用 Safari(不是其他浏览器)	用 Safari 打开站点

后续优化方向¶

加 mkdocs-git-revision-date-localized-plugin,显示每篇笔记的最后修改时间
加 mkdocs-rss-plugin,生成新笔记 RSS,可用 RSS 阅读器订阅自己
加 mkdocs-blog-plugin,把 retros/ 月度复盘做成博客时间线
替换默认 lunr 搜索为 mkdocs-jieba 或 Algolia DocSearch(大量中文笔记后)
自定义域名:scriptorium.<your-domain>.com(Cloudflare Pages 免费支持)
加 mkdocs-pdf-export-plugin,可导出整个 Layer 为 PDF 离线阅读

Setup once, study forever.