一、为什么要搭这套系统

深湾.AI 是记录 AI/ 科技 / 金融 / 旅行的知识库。最核心的需求是：

  • 编辑自由：支持 Markdown、本地编辑、版本控制
  • 自动化：减少手工操作，防止发布错误
  • AI 辅助而非代替：AI 可以检查、建议，但本人保留决策权
  • 数据独立性：正文以本地 Markdown 保存，不把内容唯一托管在某个在线写作平台

我们选择了一条 DIY 路线：Obsidian 管理正文，editorial 管线负责检查和同步，人类掌控最终的 commit 和 deploy。

二、五个角色的分工

Obsidian

  • 职责：存储正文源
  • 特点：正文以本地 Markdown 文件为主，是否使用同步服务由本人决定，支持 Wiki 链接

Claudian（AI 写作助手）

  • 权限：经用户确认后，可在 Publish/Blog/Drafts/ 创建和修改草稿
  • 能做：大纲建议、拼写检查、元数据补充、重述建议
  • 规则限制：
    • 不修改 content/posts/（发布区）
    • 不执行 git commit / push / deploy
    • 禁止创建 symlink；覆盖、移动和删除文件必须再次取得本人确认

Editorial 工作流

  • 职责：检查、同步、测试、构建
  • 流程：
    • editorial:check：检查 frontmatter、日期、ID、slug、图片和同步冲突
    • editorial:release：按顺序执行 check → sync → test → build
  • 特点：fail-closed，出错就停止

Admin

  • 认证：Cloudflare Access 邮箱 OTP
  • 功能：查看构建时收录的文章快照，包括草稿 / 发布状态、缺失摘要或封面、配置和评论状态
  • 特点：只读仪表板（本来也想着管理面板里面写作，但权衡后放弃）

网站（shenwan.ai）

  • 框架：Next.js + Vinext（把 Next.js 应用适配到 Cloudflare Workers）
  • 评论：Artalk 后端部署在独立 VPS，通过 comments 提供服务
  • 部署命令：pnpm deploy:vinext

三、搭建中遇到的真实问题

问题 1：在开源项目的基础上起步

这套博客不是从零搭起，而是基于罗老师的开源博客改造而来——站在成熟的工程实践上，省下大量从头摸索的时间。

致谢在前，内容归己。

问题 2：AI 幻觉导致误导读者

AI 曾自动生成不存在的文章标题和 URL，会误导读者。解决方案：在 AI 输出前增加标题和 URL 白名单校验与引用防护。

问题 3：登录系统从 PBKDF2 迁移到 Cloudflare Access

最初实现了自建 PBKDF2 密码登录在 Cloudflare Workers。但 Workers Free 的 CPU 限制导致加密计算返回 500 错误。

解决方案：迁移到 Cloudflare Access 的邮箱 OTP 认证，既解决了性能问题，也简化了权限管理。

问题 4：评论系统与主站的独立性

评论功能选择用 Artalk 后端部署在独立 VPS，通过 comments 提供服务。

收益：评论后端和数据可独立运维；主站部署异常不会删除 Artalk 数据。注意：文章页不可用时用户仍无法通过主站查看评论。

问题 5：把本地文件安全同步到仓库

本地文件同步到仓库时需要多层防护：

  • draft 隔离：Drafts 和 Posts 分开管理，draft 文件不发布
  • 固定 id：每篇文章的 id 一次性生成（UUID v4），永不修改，用于保持文章身份和识别重命名；重复 id 会被同步管线拒绝
  • 覆盖保护：同一 sourceId 可更新自己的同步产物；目标无 sourceId 或属于不同 sourceId 时拒绝覆盖
  • symlink 防护：防止符号链接导致的意外访问

四、为什么必须限制 AI 权限

AI 的角色是辅助而非代替。限制的目的是：

  1. 缩小误操作影响范围 — AI 无法直接部署，从而显著缩小风险；最终仍需本人审查
  2. 明确责任边界 — 清楚地知道谁负责最终决策
  3. 可审计的关键步骤 — 检查输出、同步报告和 Git diff 可在提交前审查

具体限制：

  • ✓ 可在 Drafts 创建和修改（需确认）
  • ✗ 不能直接改 Posts（发布区）
  • ✗ 不能执行 commit/push/deploy
  • ✗ destructive 操作需再次确认

五、当前工作流（完整步骤）

1. 在 Obsidian 中创建或编辑草稿（Publish/Blog/Drafts/）
   ↓
2. Claudian 提供大纲建议、检查、元数据补充
   （用户确认后修改）
   ↓
3. 运行 editorial:check 验证 frontmatter、日期、ID、slug、图片和同步冲突
   ↓
4. 检查通过，用户手工将文件移到 Posts/，设 draft: false
   ↓
5. 运行 editorial:release
   （按顺序：check → sync → test → build）
   ↓
6. 审查生成的 git diff
   ↓
7. 用户手工执行 git commit
   ↓
8. 用户手工执行 pnpm deploy:vinext

关键细节：

  • editorial:sync 只同步文件，不创建 commit
  • commit 和 deploy 始终由本人确认
  • 已发布文章若修改，使用 updated 字段，不修改原 date
  • 图片语法：Obsidian 嵌入写成 ! + [[文件名]]；标准 Markdown 写成 ! + [说明](路径)

六、当前系统的不足

本文所述的基础框架已上线，写作工作流完成首轮打通。但仍有改进空间：

  • 本地预览：写作后台是很纯粹，没有加任何插件，展示效果可能没有很好
  • 增量检查：目前是全量验证，可优化为只检查修改部分
  • 多人协作：当前单人写作，哈哈，暂时还没考虑开放多人写作
  • 访问分析：admin 仪表板目前不展示访问日志

作者：爱旅游的马老板
网站：shenwan.ai
本文仍在完善中