笔记库与博客迁移升级笔记（精华版）

一句话架构：Obsidian 库 = 唯一内容源；博客工程在库外 zhu-okol-blog/。写完笔记加 published: true，双击库根 bat，静态站上线。演进路线：Hexo → Fuwari → Next.js → Astro 5（当前）。本文只留现状、工作流与关键教训（DeepSeek Harness 协助维护）。 v1.0 正式定版：2026-08-17（git 标签 v1.0 已推 GitHub/Gitee，源码归档 blog-archive/zhu-okol-blog-v1.0-2026-08-17.zip）。 v1.1 发布：2026-08-17（git 标签 v1.1，提交 4704400）：SSH 密钥部署 + certbot 幂等化 + 服务器安全加固闭环（密钥登录 / fail2ban / 同步走 HTTPS / 9000 公网关闭）；归档 blog-archive/zhu-okol-blog-v1.1-2026-08-17.zip。

一、现状总览

项	内容
博客工程	库外 `zhu-okol-blog/`（Astro 5 + React 19 + Tailwind 4，独立 git 仓库，与库同级）
内容源	库内所有 `.md`，frontmatter 带 `published: true` 才发布
渲染管线	不走内容集合：fs 直读 + gray-matter + unified（GFM / KaTeX 数学 / atom-one-dark 代码高亮 / 图片懒加载 / 连续空行保护）
搜索	Pagefind（中文）
音乐	网易云：构建期烘焙 + 自建解析代理自愈 + 公共 meting 兜底；iframe 外壳实现零间隙跨页续播
上线	https://zhu-okol.cn（云服务器 + nginx + Let's Encrypt，ICP 已备案）
多端同步	笔记：fast-note-sync 全量同步；代码：git 仓库（2026-08-17 起两套分离）
评论	Artalk 自建（Go 单二进制 + SQLite，子域名 artalk.zhu-okol.cn，匿名评论 + 侧边栏管理）
统计	自建轻量访问统计（pv/uv，`/api/stats`，无第三方依赖）
页面	首页 / 文章 / 标签 / 时间线 / 搜索 / 关于 / 思绪 / 音乐 / 照片墙 / 友链 / 项目

二、发布工作流（三步）

Obsidian 写笔记，图片直接粘贴（自动进 assets/<笔记名>/，模板见 模板/博客文章模板.md）；
frontmatter 加 published: true；
双击库根 发布到博客.bat（本地生成 dist）或 部署到服务器.bat（同步→构建→打包→SSH 上传→nginx 重载→验证，一步上线）。两个 bat 只是转发到 ..\zhu-okol-blog\ 下的同名脚本。

publish.mjs 自动转换：图片复制 + 路径改写（空格→%20）、> [!NOTE] 呼出框→引用块、<mark>高亮</mark>→<mark>、注释 删除、Obsidian 图片嵌入语法、wiki链接→文本、scl 代码块→pascal 高亮、封面/摘要/日期/标签/分类映射、slug 冲突自动加后缀。支持 --dry-run 预演。

三、音乐系统（重点维护区）

数据链：

siteConfig.cloudMusicIds + fetch-music.mjs（两处必须同步改）
  → 构建期烘焙 public/music/playlist.json（页面秒开）
  → 加载后自建代理 /api/music/url 整单换新链接
  → 播放出错时逐首换链重试
  → 公共 meting 镜像最后兜底

网易云 CDN 直链签名几十分钟过期，是"刚部署能播、过阵失效"的根因；自建代理后已根治。详见博客音乐播放失效问题修复笔记。
零间隙续播：页面自动变身 iframe 外壳，音频引擎住在外壳文档，站内导航发生在内层帧（双帧换页无闪），音乐跨页不断。

四、部署体系

zhu-okol-blog/deploy-tools/deploy.mjs（服务器凭证在 deploy.config.json，不入 git）：上传 dist.tar.gz → 解压 → nginx 配置（幂等，只写一次）→ certbot HTTPS → 自动部署音乐代理（Node 16 运行时 + systemd + nginx 反代）→ 公网验证。

node deploy.mjs：完整部署；node deploy.mjs --proxy-only：只更新音乐代理（不重传站点）。
SSH 已加固（2026-08-17）：root 仅密钥登录（密码登录已关闭）+ fail2ban 防爆破；部署凭证走 deploy.config.json 的 keyPath（私钥 C:\Users\ZHU\.ssh\zhu-okol-server，需离线备份）。详见服务器HTTPS同步与SSH加固步骤。
服务器组件：站点目录、music-proxy（仅监听本机回环，由 nginx 反代对外）、fast-note-sync（端口与部署细节见库内 obsidian-fast-note-sync部署笔记，不公开）。
回滚依据：nginx 原配置备份 /etc/nginx/conf.d/zhu-okol.conf.bak；v1.0 源码归档 blog-archive/Blog-v1.0-2026-08-16.zip（库外）。

五、多端同步策略（笔记插件 + 代码 git，2026-08-17 分离）

笔记：fast-note-sync 全量同步、无排除（库已纯净，不含 node_modules/dist 等生成物）；任何设备写笔记改完即同步。
笔记备份：库根另有 git 仓库（远程 Zhu-OKOL-vault-backup，私有）做版本历史 + 异地备份，双击库根 库备份.bat 即可提交并推送（插件凭证 data.json 已被 .gitignore 排除，不入库）。
代码：zhu-okol-blog/ 是独立 git 仓库。主设备改完代码双击 同步代码.bat（提交+推送远程）；笔记本克隆仓库到库同级目录，双击 拉取代码.bat（拉取 + 首次自动 npm install）。
凭证：deploy-tools/deploy.config.json 不入 git；新设备部署上线前需单独复制一份（或填环境变量）。
换设备：拷笔记库文件夹 + 克隆博客仓库，两件事即可。

六、关键教训（精华）

#	教训
1	静态站性能：装饰性模糊用"低分辨率图放大"替代 filter；全屏 filter 是移动端/核显禁区；React island 能省则省
2	状态流按变更频率分层（快/慢双池），进度 4Hz 节流，避免无关组件白重渲染
3	长文图片全部 `loading=lazy decoding=async`；每页必加载资源要压缩（头像 1MB→35KB）
4	部署脚本必须幂等：站点文件随便覆盖、nginx 配置只写一次（之后交给 certbot 管理）
5	bat 必须是 CRLF + UTF-8 无 BOM，否则双击闪退/乱码
6	生成物（posts/images/dist）不手工编辑、不入 git；音乐 CDN 签名过期是结构性问题，公共镜像不可靠，自建代理才是正解
7	跨页续播/无闪换页这类交互要真浏览器回归再上线；"旧画面保留到新画面就绪"是朴素但绝对成立的方案
8	服务器凭证不入 git（deploy.config.json 走 .gitignore）；代码用 git、笔记用同步插件，两套机制各司其职

七、待办

公安网备案（beian.mps.gov.cn）
留言板 Twikoo 自建（2026-08-17 上线；管理面板设置密码并开启审核）
学习路线页（三年计划做成站点导航）
访问统计（2026-08-17 上线：自建 pv/uv，底部数据面板显示）
Media Session API 接管系统媒体键；发布管线图片压缩瘦身