这篇文章记录当前博客的日常维护方式和技术结构。它不是面向读者的功能介绍，而是一份给以后自己的运行手册：写文章应该从哪里开始，发布链路经过哪些地方，访问入口为什么有多个，换电脑或排查问题时又该看哪些文件。
当前维护目标
这个博客现在被拆成两件事：内容维护和访问分发。
内容维护尽量放在本地完成。我在 Obsidian 里写文章，通过本地的图形化工具同步到 Hexo 仓库；构建检查通过后，只需要把 source 分支推到 GitHub。真正的静态页面生成、GitHub Pages 发布，以及服务器托管版本的同步，都交给 GitHub Actions 处理。
访问分发则提供多个入口。主入口是 https://blog.orizhen.xyz/，它不是文章列表，而是一个选择页面。这里会根据网络环境引导到服务器托管版本、腾讯云 EdgeOne 加速版本，以及 GitHub Pages 版本。这样做的好处是：写作和部署保持统一，访问体验可以按线路分流。
日常写作流程
日常维护优先使用图形界面：
1 | npm run blog |
图形界面会自动寻找带 Qt 的 Python 环境。当前机器上使用的是 Anaconda 里的 PyQt 环境；如果以后换电脑，只要 npm run blog:check 能显示 Python 路径和 Qt binding，就说明 GUI 可以启动。
正常写文章的流程是：
- 在 Obsidian 的
Blog/Posts目录写 Markdown。 - 确认文章 front matter 里
draft: false，否则同步时会被当作草稿跳过。 - 使用 GUI 的
同步到 Hexo，把 Obsidian 文章复制到仓库的source/_posts。 - 使用
构建检查，确认 Hexo 可以生成静态页面。 - 使用
发布全站或一键完成，推送source分支，让 GitHub Actions 接管后续部署。
命令行也可以完成同样的事情：
1 | npm run blog:sync |
其中 blog:publish 的本质是推送源码分支。它不会在本机直接上传每个线上站点，线上部署由 GitHub Actions 统一执行。
文章和图片
文章源文件以 Hexo 的 source/_posts 为准，Obsidian 是更舒服的写作入口。同步脚本会把 Obsidian 中的文章复制到 Hexo 目录。
封面字段可以写本地站内路径，也可以写图床链接：
1 | cover: /images/posts/example.webp |
如果封面为空，或者仍然是占位路径，同步时会自动使用默认封面：
1 | cover: /images/theme/default-cover.webp |
GUI 里也有两个辅助操作：
选择封面：把本地图片复制到博客图片目录，并写入最近修改文章的cover。封面 URL：直接把图床链接写入最近修改文章的cover。
如果图片已经放在图床上，直接在 Obsidian front matter 里写 URL 就可以，不需要额外处理。
删除文章
删除文章不要只删仓库里的 Markdown。推荐用 GUI 的 删除文章：
- 可以按标题或文件名搜索。
- 默认优先显示最近修改的文章。
- 删除前会显示 Obsidian 原文路径、回收站路径和 Hexo 文件路径。
- 确认后会把 Obsidian 原文移动到
Blog/Trash，同时删除source/_posts里的同名文件。 - 随后构建并发布，让线上页面同步下线。
这个流程的目的不是复杂化删除，而是避免“本地删了，线上还在”的情况。
发布链路
当前仓库使用 source 分支维护博客源码。推送到 source 后，GitHub Actions 会运行 .github/workflows/deploy.yml。
Actions 做三件事：
- 安装 Node.js 依赖。
- 使用 Hexo 构建 GitHub Pages 版本，并发布到
main分支。 - 使用单独的 HK 配置构建服务器托管版本，并通过 SSH 同步到服务器目录。
GitHub Pages 是公开静态源站，访问地址是：
1 | https://ori2333.github.io/ |
服务器托管版本部署在：
1 | https://blog.orizhen.xyz/blog/ |
入口页面部署在：
1 | https://blog.orizhen.xyz/ |
入口页展示三条线路：服务器托管版本、中国大陆加速访问、GitHub Pages 源站。这个顺序是有意安排的：默认入口优先给自有服务器版本，再给大陆 CDN 加速版本，最后保留 GitHub Pages 作为稳定备用。
服务器托管版本
服务器托管相关脚本在：
1 | tools/hk_deploy/ |
关键文件包括：
deploy_hk.py：构建并上传服务器托管版本，同时生成入口页面。_config.hk.yml：覆盖 Hexo 的url、root、public_dir，让博客在/blog/下正常工作。hk_deploy.config.json：记录服务器、域名、远程目录、入口链接等配置。nginx-ori2333-blog.conf：Nginx 站点配置模板。setup_hk_server.py：初始化服务器 Nginx 和 HTTPS 的辅助脚本。
线上目录固定为：
1 | /var/www/ori2333-blog |
脚本只清理和同步这个目录，不碰服务器上已有的其他服务。旧的 /hk/ 路径会重定向到 /blog/，这是为了兼容早期测试阶段留下的地址。
HTTPS 使用 Let’s Encrypt。证书有效期 90 天，服务器上需要保持自动续签任务开启。当前设计依赖 certbot.timer 或等效的定时任务，不应该手动等到证书过期后再处理。
EdgeOne 加速入口
腾讯云 EdgeOne 作为中国大陆访问加速线路。它不是独立写作源，也不是另一套博客内容，而是访问分发层的一条加速入口。
入口页中的大陆加速访问指向 EdgeOne 地址。日常维护时不需要单独为 EdgeOne 写文章或手动同步内容；只要 GitHub Pages 和服务器托管版本部署正常，EdgeOne 侧按它的源站和缓存策略更新即可。
如果发现 EdgeOne 看到的内容落后，优先检查：
- GitHub Actions 是否部署成功。
- EdgeOne 配置的源站是否正常。
- 是否命中旧缓存。
- 页面 URL 是否带了旧的临时 token 或过期参数。
仓库结构
常用目录可以按下面理解：
1 | source/_posts/ # Hexo 文章源文件 |
不要手动维护 public/。它是构建产物，会被 hexo clean 和 hexo generate 重建。真正应该提交的是源码、文章、图片、脚本和配置。
换电脑时要恢复什么
换电脑时，重点不是复制 public/，而是恢复这几类东西：
- Node.js 和 npm。
- 仓库依赖：
npm ci。 - 一个带 Qt 的 Python 环境，例如 Anaconda 里的 PyQt。
- Obsidian 库路径，并在
tools/blog/blog.config.json里配置正确。 - GitHub 访问权限，可以推送
source分支。 - 如需本地手动部署服务器版本，恢复 SSH key。
GitHub Actions 的服务器部署密钥在仓库的 Actions Secrets 里维护，主要包括：
1 | HK_HOST |
这些 secret 不应该写进仓库。仓库里只保留脚本和配置模板。
常见排查路径
如果 GUI 打不开，先运行：
1 | npm run blog:check |
如果同步后文章没有出现，检查：
- Obsidian 文章是否在
Blog/Posts。 - front matter 是否还写着
draft: true。 tools/blog/blog.config.json里的 Obsidian 路径是否正确。
如果本地构建失败，运行：
1 | npm run blog:build |
如果线上没有更新，按顺序看：
- 本地是否已经推送
source分支。 - GitHub Actions 是否成功。
- GitHub Pages 是否更新。
- 服务器托管版本是否更新。
- EdgeOne 是否仍然命中缓存。
维护原则
这个博客系统现在的核心原则是：写作入口简单，部署链路自动，访问线路可替换。
Obsidian 负责写作体验，GUI 负责减少重复操作，Hexo 负责生成静态站点，GitHub Actions 负责编排部署，服务器和 EdgeOne 负责访问体验。只要这个边界不乱，后续换主题、换域名、换服务器，成本都会比较低。
