项目笔记：一个基于 Hexo 的高可用、自动化博客系统

创建者： suxiao3316
项目域名： https://linuxnc.xyz

第一部分：环境分析与最终架构

本项目旨在搭建一个视觉风格独特、功能全面、技术架构现代化的个人博客平台。核心要求包括：

  • 花哨美观的前端: 实现玻璃拟态、动态背景、定制化UI等视觉效果。
  • 强大的互动功能: 集成支持社交登录、游客评论的现代评论系统。
  • 高效的内容管理: 支持本地 Markdown 写作 + 图床，或可选的云端可视化CMS。
  • 全自动化的 CI/CD 流程: 实现从代码提交到线上服务更新的全自动化，无需手动干预服务器。
  • 高可控的私有化部署: 所有核心服务（博客前端、评论后端）最终都以 Docker 容器的形式，运行在自主掌控的云服务器上。

经过一系列的探索与实践，项目最终沉淀为一套前后端分离、内容与程序分离、基于 Docker 容器化的现代化 DevOps 架构。

【核心生产环境 (云服务器 - 阿里云 ECS)】

  1. 反向代理层 (Caddy Server):
    • 作为整站的唯一流量入口，运行在宿主机上。
    • 职责:
      • 自动申请和续期 Let’s Encrypt 的 SSL 证书，实现全站 HTTPS。
      • 将 https://linuxnc.xyz 的流量，反向代理到博客前端 Docker 容器。
      • 将 https://waline.linuxnc.xyz 的流量，反向代理到评论后端 Docker 容器。
  2. 应用服务层 (Docker Compose):
    • 博客前端容器 (arknights-blog):
      • 基于官方 nginx:alpine 镜像构建。
      • 内部仅包含由 Hexo 预先生成的纯静态网站文件 (public 目录内容)。
      • 通过 Docker 内部网络 (blog-network) 与 Caddy 通信。
    • 评论后端容器 (waline_service):
      • 基于 walinejs/waline:latest 官方镜像运行。
      • 通过 Docker 环境变量接收所有配置。
      • 通过 Docker 内部网络与 Caddy 通信。

【云端数据库 (腾讯云 TCB)】

  • 服务: 腾讯云开发 CloudBase 文档型数据库。
  • 职责: 作为 Waline 评论系统的持久化数据存储，存放所有评论、用户、统计数据。选择国内云服务以保证最低的访问延迟。

【CI/CD 与代码管理 (GitHub)】

  • my-blog-source (私有源码仓库):
    • 存放 Hexo 项目的所有源文件（Markdown 文章、主题、配置文件、Dockerfile等）。
    • 是整个 CI/CD 流程的触发源。
  • GitHub Actions:
    • 扮演云端 Jenkins 的角色，是自动化流程的核心引擎。
    • 当 my-blog-source 仓库有新的 push 时，自动触发工作流。
  • my-blog-images (公开图床仓库):
    • 与 PicGo + jsDelivr CDN 配合，为本地 Markdown 写作提供免费、高速、全球加速的图床服务。

【内容创作】

  • 主要工作流: 在本地 Windows 环境，使用 Typora + PicGo 进行写作和图片管理，享受极致丝滑的创作体验。
  • 可选工作流: 未来可随时重新启用 Decap CMS (托管于 Netlify) 作为云端可视化编辑器。

第二部分：关键操作与调试历程回顾

  • 初始化: 创建了标准的 Hexo 项目，并集成了 Butterfly 主题。
  • 核心配置:
    • 修改 _config.yml 和 _config.butterfly.yml，完成了对网站标题、作者、菜单（包括多级下拉菜单）的明日方舟化定制。
    • 配置了全局背景图和首页全屏顶部图 (index_top_img_height: 100vh)。

  • 关键调试:

    • 解决了内页“一片漆黑”的问题，通过自定义CSS (custom.css)，为非首页的 post 布局强制创建了顶部图区域 (::before 伪元素)。
    • 解决了代码块不换行和 macStyle 不生效的问题，通过禁用 Hexo 默认高亮 (highlight: false) 并启用 PrismJS，让主题完全接管样式渲染。

  • 后端部署:

    • 最初尝试使用阿里云函数计算 (FC) + 表格存储 (OTS)。
    • 遭遇重大挫折: OTSAuthFailed(Request denied by instance ACL policies) 错误，通过配置表格存储的网络管理和安全策略（IP白名单） 解决了底层连接问题。
    • 遭遇根本性障碍: lizheming/waline 镜像存在硬编码的 LeanCloud 初始化逻辑，无论如何配置都无法连接 Tablestore。这是整个项目最重要的转折点。
    • 最终方案: 放弃 Tablestore，决定采用 Waline 原生支持的腾讯云开发 (TCB) 方案。
    • 在 TCB 控制台手动创建了 Waline_Comment, Waline_User, Waline_Counter 三个集合，并正确设置了权限。
    • 纠正了环境变量: 通过查阅文档，将错误的 TCB_SECRET_ID/KEY 修正为正确的 TCB_ID/KEY。
    • 最终通过 Docker Compose + 环境变量的方式，在阿里云服务器上成功启动了 Waline 后端服务。

  • 前端集成:

    • 在 _config.butterfly.yml 中配置 serverURL 指向云服务器。
    • 解决了因 serverURL 缺少协议头 (http://) 而导致前端无法连接的问题。
    • 成功初始化: 访问 /ui/register 页面，注册了第一个管理员账号，解决了 Not initialized 的错误。
    • 后台访问: 确认了 Waline v3 的后台UI没有固定侧边栏，并通过直接访问 /ui/comments 或点击左上角图标的方式进入了评论管理。

  • PicGo + GitHub + jsDelivr: 成功配置了 PicGo 客户端，使用 github-plus 插件、GitHub 个人访问令牌 (PAT) 和 jsDelivr，搭建了免费高速图床。

  • Typora 集成: 解决了因 Node.js 环境变量 (PATH) 未正确配置导致 PicGo 无法调用的问题，并成功在 Typora 中配置了 PicGo，实现了拖拽/粘贴图片自动上传的体验。

  • 历史笔记迁移: 掌握了在 VS Code 或 Typora 中，通过插件功能将旧笔记的本地图片一键批量上传到图床的方法。

  • GitHub Actions:

    • 学习并编写了两个版本的 deploy.yml 工作流。
    • 版本一: 部署到 GitHub Pages。期间调试了 Deploy Key（区分公钥/私钥的用途）和分支名不匹配 (master vs main) 的问题。
    • 版本二 (最终版): 构建 Docker 镜像并推送到阿里云ACR。期间解决了 Actions Secrets 配置错误 (Error: missing server host) 和 Action 插件网络超时 (The operation was canceled.) 的问题。
    • 为流水线增加了邮件通知功能，实现了部署成功/失败的实时反馈。

  • Docker 部署:

    • 在阿里云服务器上，通过 Docker Compose 编排 blog 前端和 waline 后端两个服务。
    • 通过 Caddy 解决了 ERR_TOO_MANY_REDIRECTS (重定向循环) 和 Failed to fetch (混合内容)` 的问题，为所有服务提供了统一的 HTTPS 入口。

  • 探索了该方案：在 Netlify 上创建了站点，启用了 Identity 和 Git Gateway。

  • 在 Hexo 源码中添加了 source/admin/ 目录和配置文件。
  • 遇到的问题: 部署后 /admin 路径 404 或显示空白，根源在于 Netlify 构建命令 (Build command) 未正确配置，以及与本地hexo-admin插件缓存的路由冲突。
  • 最终决策: 由于与云服务器部署方案存在逻辑冲突，且集成过程略显繁琐，决定暂时搁置，回归到更纯粹、更可控的“本地写作 + Git Push + Actions 部署”的核心流程。