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

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

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

- **花哨美观的前端**: 实现玻璃拟态、动态背景、定制化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 部署”的核心流程。



1.博客的架构