博客运维指南

这篇文章记录本博客当前的使用方式，包含：如何写文章、改文章、删文章、改主题配置、替换各位置图片、预览与部署。

1. 项目结构速览

当前核心目录：

• source/_posts/：文章 Markdown 文件
• source/about/index.md：关于页面
• _config.yml：站点级配置（标题、URL、root、主题名等）
• _config.kratos-rebirth.yml：Kratos-Rebirth 主题配置
• public/：Hexo 生成后的静态文件（不要手改）

2. 脚本与命令

在仓库根目录运行：

1
2
3
4
5
6
7
8

npm run clean
npm run build
npm run server -- -p 4000
npm run deploy
npm run push:static
npm run push
npm run source:status
npm run source:push

说明：

• clean：清空旧构建产物
• build：生成静态站点到 public/
• server：本地预览，默认访问 http://localhost:4000/
• deploy：按 _config.yml 的 deploy 配置发布（仅执行 Hexo deploy）
• push:static：一键执行 clean + build + deploy（推静态站到部署仓库）
• push：执行 source:push（推源码到主仓库，触发 GitHub Actions 部署）
• source:status：查看源码仓库改动状态
• source:push：将源码仓库改动执行 add + commit + push

如果 4000 端口被占用：

1

npm run server -- -p 4001

如果要查看当前项目脚本定义，可直接看 package.json 的 scripts 字段。

注意区分两类“推送”：

• npm run push：推送的是源码仓库改动（用于触发 GitHub Actions 自动部署）。
• npm run push:static：推送的是静态站内容（public -> 部署仓库）。

结论（当前项目推荐）：

• 你现在主要用 npm run push 就可以。
• npm run push:static 不是日常必需，只有在你临时改走 Hexo 部署仓库时才用。

3. 如何写一篇新文章

3.1 创建文章

1

npx hexo new post "你的文章标题"

会在 source/_posts/ 里生成同名 .md 文件。

3.2 推荐 Front Matter 模板

1
2
3
4
5
6
7
8
9
10

---
title: 文章标题
date: 2026-03-29 13:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
cover: /images/default.webp
---

标签与分类建议这样使用：

• tags：可多个，用于主题聚合、跨分类检索。
• categories：建议单个主分类，保持结构稳定。

示例（技术文章）：

1
2
3
4
5
6

tags:
  - ISP
  - FPGA
  - 图像处理
categories:
  - docs

生成后可在以下页面查看效果：

• /tags/
• /categories/
• /tags/标签名/
• /categories/分类名/

封面建议统一放在 source/images/posts/，并在文章里写成：

1

cover: /images/posts/your-post-cover.webp

注意：这里不要写站点根路径之外的前缀，当前站点已经部署在根域名下，资源路径应直接写成 /images/...。

3.3 控制首页摘要预览

在正文中加入：

1

<!-- more -->

这行之前是首页摘要，这行之后只在文章详情页显示。

4. 如何修改与删除文章

4.1 修改文章

直接编辑对应的 source/_posts/*.md 文件，然后执行：

1

npm run build

4.2 删除文章

删除 source/_posts/对应文章.md，再执行：

1

npm run build

5. 如何替换各种位置的图片

建议把你自己的图片放到 source/images/（或 source/assets/）下。

示例：

• source/images/avatar.webp
• source/images/banner-light.webp
• source/images/banner-dark.webp
• source/images/bg-light.webp
• source/images/bg-dark.webp
• source/images/post-cover.webp

这样 Hexo 生成后会变成：

• /images/avatar.webp
• /images/banner-light.webp
• …

5.1 侧栏头像

在 _config.kratos-rebirth.yml：

1
2

image:
  avatar: /images/avatar.webp

5.2 顶部横幅 Banner

在 _config.kratos-rebirth.yml：

1
2
3
4

image:
  banner:
    light: /images/banner-light.webp
    dark: /images/banner-dark.webp

5.3 全局背景图

在 _config.kratos-rebirth.yml：

1
2
3
4

image:
  background:
    light: /images/bg-light.webp
    dark: /images/bg-dark.webp

5.4 文章封面

在文章 front matter：

1

cover: /images/posts/post-cover.webp

建议每篇文章用独立封面文件名，例如：

• source/images/posts/2026-03-29-hexo-cover.webp
• source/images/posts/isp-bilinear-cover.webp

5.5 站点图标 Favicon

在 _config.kratos-rebirth.yml：

1
2

image:
  favicon: /images/theme/favicon.svg

当前图标文件位置：source/images/theme/favicon.svg。

如果你要换图标，直接替换该文件，或改成你自己的路径（例如 source/images/theme/my-favicon.png 并同步修改上面的配置）。

6. 常见问题

6.1 首页显示全文，不是摘要

原因：没有 <!-- more -->。

处理：在正文合适位置加入 <!-- more -->。

6.2 首页卡片图片裂开

原因：cover 路径不存在或不可访问。

处理：确认文件放在 source/images/，并检查路径拼写。

6.3 头像裂开

原因：路径与站点 root 不一致（本项目现在是 /）。

处理：头像路径使用可访问地址，并在本地预览验证。

6.4 审查时临时关闭评论

本项目支持通过一个开关临时关闭评论（用于审查/内测）。

在 _config.kratos-rebirth.yml 里找到：

1
2

additional_injections:
  after_footer: "<script>window.__COMMENTS_ENABLED=false;</script>"

将 window.__COMMENTS_ENABLED 改为：

• true：开启评论
• false：关闭评论（页面显示“评论已关闭（审查中）”提示）

关闭时会同时隐藏评论计数，避免出现“0 条评论”的占位文案。

6.5 文章页有阅读量，但首页列表不显示

原因：

• 当前项目采用纯静态阅读量方案（不依赖 Waline 服务），统计脚本只针对当前页面生效。
• 首页列表是一页里多篇文章卡片，纯静态方案无法稳定返回每篇文章各自的独立阅读量。

处理：

1. 在 _config.kratos-rebirth.yml 中保持 visit_count.enable_at 只启用 post。
2. visit_count.template 使用不蒜子脚本与 busuanzi_container_page_pv 模板。

说明：

• 阅读量统计可以独立于评论开关运行；即使评论关闭（__COMMENTS_ENABLED=false），文章页阅读量仍可显示。
• 如果你以后想在首页列表也显示“每篇文章阅读量”，需要接入带后端存储的计数服务（如 Waline pageview）。

7. 发布流程

7.1 日常推荐流程（最简单，适合 90% 场景）

编辑完文章或配置后，直接在命令行执行：

1
2
3

git add -A
git commit -m "你的提交信息"
git push origin source

或用仓库脚本一键推送：

1

npm run push

就这样！ GitHub Actions 会自动 build + deploy 到 GitHub Pages。

补充：

• npm run push 本身不做构建，构建发生在 CI（GitHub Actions）里
• 推送时会自动排除 public/、db.json、.deploy_git/
• 等待 2-5 分钟，网站会自动更新

7.2 本地完整预览（发布前验证）

如果想在本地看到最终效果再推送：

1
2
3

npm run clean          # 清理旧构建
npm run build          # 本地生成
npm run server -- -p 4000  # 在 http://localhost:4000 预览

检查无误后再执行 npm run push 推送。

7.3 备用流程：本地直接部署（不常用）

如果你临时不想用 GitHub Actions，可以在本地直接构建并推送到 main 分支：

1

npm run push:static    # 等价于：clean + build + deploy

这个流程需要：

• 本地配置好 SSH
• _config.yml 的 deploy 配置指向正确的仓库

日常不推荐用这个。

7.4 双托管（GitHub Pages + 腾讯云）说明

如果同时保留腾讯云静态托管：

• GitHub Pages 由 source -> (CI build) -> main 自动发布
• 腾讯云由独立的 CloudBase workflow 或控制台配置负责
• 两边都会自动同步更新

腾讯云控制台配置要点：

• 分支：选 source（需要源码）
• 目标目录：.（仓库根）
• 安装命令：npm install
• 构建命令：npm run build
• 构建产物目录：public
• 部署路径：blog 或根据实际需求（不要填 /）

注意：当前 Hexo 配置是 root: /（根域名），如果腾讯云部署到 /blog/ 子路径，会出现样式加载失败。两边要保持一致：

• 都用根路径 /，或
• 都用子路径 /blog/（需要改 Hexo 配置）

9. Obsidian + 菜单式日常流程

现在仓库里加了一套更省心的日常入口：

• tools/blog/blog.config.json：配置 Obsidian vault、文章目录和图片目录
• templates/blog-post.md：新文章模板
• tools/blog/blog_gui.py：图形化日常面板
• tools/blog/blog_cli.py：命令行入口，方便自动化和 Codex 调用
• npm run blog：启动图形界面

推荐流程：

1. 在 Obsidian 的 Blog/Posts 里写文章
2. 图片放到 Blog/Assets
3. 准备发布时，把文章 front matter 里的 draft: true 改成 draft: false 或删除这一行
4. 运行 npm run blog
5. 在图形界面里点 Sync 或 All
6. 需要预览就选 Preview
7. 需要发布就选 Publish

首次使用时，可以先选 Import，把仓库现有文章和图片导入到 Obsidian。

如果你要调整同步位置，只需要改 tools/blog/blog.config.json。

迁移到新电脑或切换 Python 环境时，查看仓库里的 docs/blog-workflow-migration.md。

8. 🎉 新部署架构说明（2026 年 4 月更新）

本仓库已进行重大架构升级，采用业界标准的”源码与产物分离“策略。这彻底解决了之前混合托管带来的问题。

这部分就是原来独立的部署说明内容，现已并入本文，方便你只维护一篇文档。

主要改进

问题回顾

• ❌ 源码、配置、依赖混杂在同一分支
• ❌ node_modules 被上传，仓库臃肿
• ❌ 安全隐患：配置文件和密钥暴露
• ❌ GitHub Pages 可能解析混淆

新方案

• ✅ source 分支：存放源代码、文章、配置
• ✅ main 分支：仅存放编译后的静态 HTML
• ✅ CI 自动化：GitHub Actions 自动构建和部署
• ✅ 安全隔离：敏感信息不再进入 GitHub Pages

安全边界：会不会有密钥泄漏风险

如果你基本没有后端交互，风险通常很低，但不是绝对为零。关键看你有没有把真正的 Secret 放进仓库。

• 通常没问题的内容：文章正文、图片、CSS、JS、主题配置里只用于前端展示的公开站点 ID 或地址。
• 仍然要避免的内容：真正的 API Secret、Token、数据库密码、云存储私钥、可写权限密钥。

对于你现在这种纯静态博客，如果只是做展示、评论和统计，而且没有自建后端，那么大多数情况下不会产生“服务器密钥泄漏”问题。真正需要警惕的是以后如果接入了第三方后端能力，别把私钥直接写进 _config.yml、_config.kratos-rebirth.yml 或文章内容里。

新工作流（强烈推荐）

你只需关心一件事：编辑 source 分支并推送。

1
2
3
4
5
6
7
8
9
10
11
12
13

# 1. 在 source 分支编辑（默认分支）
vim source/_posts/xxx.md

# 2. 本地预览
npm run server

# 3. 提交并推送
git add -A
git commit -m "docs: update article"
git push origin source

# 4. 完成！✨ 
# GitHub Actions 自动构建 → 直接部署到 GitHub Pages → 网站更新

分支说明

常见场景

场景 1：发布新文章

1
2
3
4
5

# source 分支上
npx hexo new post "我的新文章"
vim source/_posts/我的新文章.md  # 编辑内容
npm run server  # 本地预览检查
npm run push    # 推送，触发自动部署

场景 2：修改配置或主题

1
2
3
4
5
6

# 修改配置
vim _config.yml
vim _config.kratos-rebirth.yml
npm run clean && npm run build  # 本地验证
npm run server  # 预览检查
npm run push    # 推送，自动重建和部署

关键脚本命令

1
2
3
4
5
6
7

npm run build            # 生成 public/（本地用）
npm run clean            # 清理构建产物
npm run server           # 启动本地服务器
npm run deploy           # 推送 public 到 main（本地用）
npm run push             # 推送源码到 source（日常用）
npm run push:static      # 本地完整流程：clean → build → deploy
npm run source:status    # 查看当前改动

跟进行动

如果这是你第一次看到这个新架构：

1. 切到 source 分支（应该已经是默认）

   1 2	git checkout source git branch -v # 验证 * source

2. 阅读详细文档
   直接看本文第 7、8 节即可，相关部署说明已经合并到这里。

3. 验证 CI 工作流
   进入 GitHub 仓库 > Actions 标签页，查看最新的工作流执行结果

4. 有任何疑问

   • 查看 Hexo 官方文档：https://hexo.io/docs/
   • 查看 GitHub Actions 文档：https://docs.github.com/en/actions

总结：现在你的博客采用了专业的 CI/CD 部署流程。编辑 → 推送 source → 自动部署。简单、安全、规范。