🚀 使用 Docker Compose 部署 Hexo（静态博客生成器）

🚀 使用 Docker Compose 部署 Hexo 博客

本文是一篇关于使用 Docker Compose 部署 Hexo 的详尽教程，旨在帮助您快速搭建一个基于 Docker 的 Hexo 博客，简化环境配置和部署流程。

📝 项目简介

Hexo 是一个快速、简洁且高效的静态博客框架，它基于 Node.js 开发，允许您使用 Markdown 语法编写文章，然后快速生成静态网页。

核心特点：

• 超快速度：Hexo 支持秒级生成数百个静态页面，得益于 Node.js 的高效性能。
• 一键部署：生成的静态网页可以轻松部署到 GitHub Pages、自己的服务器或其他云平台。
• 丰富的插件和主题：拥有庞大的插件生态系统和主题库，方便您扩展功能和定制外观。
• Markdown 支持：使用 Markdown 语法编写文章，简单高效，专注于内容创作。
• Docker 化部署：通过 Docker 容器化技术，可以避免复杂的环境配置，实现跨平台一键部署和运行。

🔧 部署前准备

在开始部署之前，请确保您的环境满足以下要求，并完成必要的准备工作。

系统环境要求

• 操作系统：支持 Linux（如 Ubuntu、CentOS）、Windows 10/11（建议使用 WSL2）或 macOS。
• Docker 引擎：确保已安装 Docker 引擎（版本 20.10 或更高）。您可以参考 官方 Docker 安装文档。
• Docker Compose：确保已安装 Docker Compose（版本 2.0 或更高）。请参考 官方 Docker Compose 安装文档。

环境检查

在终端中执行以下命令，检查 Docker 环境是否就绪：

docker --version
docker compose version

创建部署目录

建议创建一个独立的目录来管理您的 Hexo 部署文件和数据：

mkdir -p /home/compose/hexo && cd /home/compose/hexo

⚙️ 配置 Docker Compose

接下来，我们需要创建 Docker Compose 配置文件。根据您提供的配置，以下是一个详细的解释和说明。

配置文件详解

在您的工作目录（例如 /home/compose/hexo）下，创建名为 docker-compose.yml 的文件，内容如下：

services:
  hexo:
    container_name: hexo2  # 容器名称，便于管理（如停止/查看日志）
    environment:
      - HEXO_SERVER_PORT=4000  # 容器内 Hexo 预览服务端口（固定，不可改）
      # 可选：配置 Git 信息（用于自动部署到 GitHub 等平台，需取消注释并修改）
      #- GIT_USER=Your Name      # 可选：设置 Git 用户名，用于部署
      #- GIT_EMAIL=your.email@domain.tld  # 可选：设置 Git 邮箱，用于部署
    volumes:
      - ./app:/app  # 核心挂载：本地 ./app 目录 → 容器 /app 目录（存储博客源码，实时同步）
    ports:
      - 4001:4000  # 端口映射：主机 4001 → 容器 4000（通过主机 4001 端口访问预览服务）
    image: spurin/hexo  # Hexo 官方优化镜像（集成 Node.js 和 Hexo 环境，开箱即用）
    restart: unless-stopped  # 容器退出后自动重启（除非手动停止，保障服务稳定）

关键配置说明

1. 镜像选择 (image)： 这里使用了 spurin/hexo 镜像。该镜像通常已经预配置了 Hexo 环境，开箱即用。您也可以根据需要选择其他镜像，例如 zuolan/hexo（集成了自动构建和监视功能） 或自行构建的镜像。

2. 端口映射 (ports)：

   • 4001:4000：将容器内部的 Hexo 服务器端口（4000）映射到宿主机的 4001 端口。您可以通过 http://服务器IP:4001 访问博客。
   • 您可以根据需要调整冒号左侧的宿主机端口（例如 8080:4000），确保其未被其他程序占用。

3. 数据持久化 (volumes)：

   • ./app:/app：这是关键的挂载点。它将宿主机当前目录下的 app 文件夹映射到容器内的 /app 工作目录。这样，您的所有 Hexo 项目文件（包括文章、主题、配置）都会保存在宿主机上，即使容器删除也不会丢失数据。
   • 首次启动时，如果 ./app 目录为空，Docker 镜像可能会进行初始化（例如，克隆 Hexo 框架源文件并安装依赖），这可能需要一些时间。

4. 环境变量 (environment)：

   • HEXO_SERVER_PORT=4000：设置容器内 Hexo 服务器运行的端口。
   • GIT_USER 和 GIT_EMAIL：这些是可选的环境变量，如果您计划使用 Git 方式部署博客到远程仓库（如 GitHub Pages），可以取消注释并填写您的信息，这些信息用于 Git 提交记录。

示例：在您的工作目录（例如 /home/compose/hexo/app）下，创建名为 _config.yml 的文件，内容如下：

# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: Hexo
subtitle: ''
description: ''
keywords:
author: John Doe
language: en
timezone: ''

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: http://example.com
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: true # Set to false to remove trailing '.html' from permalinks

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:

# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
titlecase: false # Transform title into titlecase
external_link:
  enable: true # Open external links in new tab
  field: site # Apply to the whole site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
syntax_highlighter: highlight.js
highlight:
  line_number: true
  auto_detect: false
  tab_replace: ''
  wrap: true
  hljs: false
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''

# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
index_generator:
  path: ''
  per_page: 10
  order_by: -date

# Category & Tag
default_category: uncategorized
category_map:
tag_map:

# Metadata elements
## https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
meta_generator: true

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD
time_format: HH:mm:ss
## updated_option supports 'mtime', 'date', 'empty'
updated_option: 'mtime'

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10
pagination_dir: page

# Include / Exclude file(s)
## include:/exclude: options only apply to the 'source/' folder
include:
exclude:
ignore:

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
#theme: landscape

theme: butterfly
#theme: fluid
#theme: icarus
#theme: next
#theme: stellar

#theme: fluid2
#theme: yilia
#theme: meow
#theme: shiroi #卡住是typo的变体




# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: ''

---

🚀 启动与验证

配置完成后，就可以启动 Hexo 服务了。

启动服务

在 docker-compose.yml 文件所在目录执行以下命令：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

1. 检查容器运行状态： 执行 docker ps 命令。如果看到名为 hexo2 的容器状态为 Up，说明容器已成功启动。

2. 查看服务日志（可选）： 您可以通过以下命令查看容器的启动日志，以排查潜在问题或观察初始化过程： bash docker compose logs -f hexo 初次启动时，可能会看到依赖安装和初始化的日志。

3. 访问博客并初始化：

   • 在浏览器中输入 http://你的服务器IP地址:4001 访问博客。
   • 如果服务正常启动，您将看到 Hexo 的默认页面或初始化后的页面。

文件结构确认

启动成功后，您应该在部署目录下看到一个 app 文件夹（由数据卷挂载生成），里面包含了您的 Hexo 项目文件。其结构可能类似：

app
├── _config.yml       # Hexo 主配置文件
├── source            # 存放文章和页面的源文件
│   └── _posts        # 您的 Markdown 文章存放于此
├── themes            # 主题目录
│   └── landscape     # 可能包含默认主题
└── package.json      # 项目依赖配置

（2）验证博客初始化与预览服务

1.检查 ./app 目录是否生成默认文件（初始化成功标志）：

    ls ./app  # 应显示 _config.yml（配置文件）、source（文章目录）、themes（主题目录）等

2.访问预览服务：打开浏览器，输入 http://服务器IP:4001（如本地测试：http://localhost:4001）； 3.若显示 Hexo 默认页面（“Hello World” 示例文章），说明预览服务正常。

🔌 基础配置与使用

成功部署并访问 Hexo 博客后，您可以开始进行个性化配置和内容创作。

基本配置修改

1. 编辑 Hexo 主配置文件： 进入 app 目录，找到 _config.yml 文件（通常被称为站点配置文件），您可以使用文本编辑器修改它。常见的配置项包括：

   • title：网站标题
   • subtitle：网站副标题
   • description：网站描述
   • author：您的名字
   • language：网站语言（例如 zh-CN）
   • url：网站的 URL

2. 应用更改： 修改配置文件后，通常需要重启 Docker 容器才能使更改生效：

    docker compose restart hexo

管理博客内容

1.撰写新文章： - 最简单的方式是在 app/source/_posts 目录下直接创建新的 Markdown (.md) 文件。您可以使用类似 我的第一篇文章.md 这样的文件名。 - 在 Markdown 文件的开头，建议包含 Front-matter 来设置文章属性，例如：

        ---
        title: 我的第一篇文章
        date: 2023-10-10 12:00:00
        tags: [Hexo, Docker]
        ---

在 --- 下方开始撰写您的文章正文。

2.查看更新： 新建或修改文章后，保存文件。通常情况下，您只需要刷新浏览器页面，就能看到更新后的内容。

更换博客主题

1.进入主题目录： Hexo 的主题通常存放在 app/themes/ 目录下。

2.安装新主题： 您可以从 GitHub 或其他来源克隆喜欢的主题到 themes 目录。例如，安装流行的 Next 主题：

    # 确保在 app 目录下操作，或者使用 Docker 命令
    docker exec -it hexo2 git clone https://github.com/next-theme/hexo-theme-next.git themes/next

3.启用主题： 修改 app/_config.yml 文件，找到 theme 配置项，将其值改为新主题的文件夹名（例如 next）：

    theme: next

4.重启容器： 修改主题后，需要重启容器来应用新主题：

    docker compose restart hexo

---

🔌 基础配置与使用2

Hexo 核心操作是 “创建文章→预览→生成静态文件→部署”，所有操作可通过容器命令行或修改本地文件完成：

1. 进入容器命令行（执行 Hexo 命令）

# 进入 hexo2 容器的命令行界面
docker exec -it hexo2 /bin/bash

进入后可执行 Hexo 核心命令（后续操作均在容器内命令行执行）。

2. 创建第一篇文章

# 创建名为“我的第一篇 Hexo 博客”的文章（会在 ./app/source/_posts 目录生成 Markdown 文件）
hexo new "我的第一篇 Hexo 博客"

• 本地查看文章文件：./app/source/_posts/我的第一篇 Hexo 博客.md，可用 Markdown 编辑器（如 Typora）修改内容。

3. 预览文章效果

# 启动预览服务（默认绑定 4000 端口，容器外通过 4001 端口访问）
hexo server

• 浏览器访问 http://服务器IP:4001，即可实时查看文章修改效果（修改 Markdown 文件后刷新页面生效）。

4. 生成静态文件（部署用）

预览满意后，生成可部署的静态 HTML 文件（存储在 ./app/public 目录）：

hexo generate  # 简写：hexo g

5. 配置博客基本信息（修改 _config.yml）

本地编辑 ./app/_config.yml（核心配置文件），修改站点信息：

# 示例：修改站点标题、作者、语言
title: 我的 Hexo 博客  # 博客标题
subtitle: 技术笔记  # 副标题
description: 记录学习过程的个人博客  # 描述（用于 SEO）
author: 用户名  # 作者名
language: zh-CN  # 语言（中文）
timezone: Asia/Shanghai  # 时区

修改后重启预览服务（hexo server）生效。

6. 更换主题（以 Next 主题为例）

1.容器内命令行执行（克隆主题到 themes 目录）：

    git clone https://github.com/next-theme/hexo-theme-next.git themes/next

2.本地编辑 ./app/_config.yml，修改主题配置：

    theme: next  # 主题名称改为 next

3.重启预览服务，页面会显示 Next 主题样式。

---

🛠️ 维护与管理

日常维护

• 服务启停：

    # 停止服务
    docker compose down
    # 启动服务
    docker compose up -d
    # 重启服务
    docker compose restart

• 数据备份： 定期备份部署目录下的 app 文件夹至关重要。这个文件夹包含了您的所有博客文章、主题和配置。

    # 在部署目录的上一级目录执行
    tar -czf hexo-backup-$(date +%Y%m%d).tar.gz hexo/

• 服务更新： 若要更新 Hexo 镜像（例如 spurin/hexo 发布了新版本）：

    # 进入部署目录
    cd /home/compose/hexo
    # 拉取最新镜像
    docker compose pull
    # 重启服务
    docker compose down
    docker compose up -d

注意：在升级前，请务必备份 app 目录。对于生产环境，建议先在测试环境中验证新版本的兼容性。

问题排查与日志

• 查看容器日志： 如果遇到问题，查看容器日志是首要的排查手段：

    docker compose logs hexo
    # 或者实时查看
    docker compose logs -f hexo

• 进入容器排查： 有时可能需要进入容器内部进行检查或执行命令（例如安装额外插件）：

    docker exec -it hexo2 /bin/sh

在容器内，您可以运行 `hexo version` 等命令进行检查。

🐛 常见问题排查

在使用过程中，可能会遇到一些问题，以下是一些常见问题的排查思路：

1. 无法通过浏览器访问博客（http://服务器IP:4001 无响应）

   • 检查防火墙：确保您的服务器安全组（云服务商控制台）和系统防火墙（如 ufw）已放行 4001 端口。例如：sudo ufw allow 4001。
   • 检查容器状态：运行 docker ps 确认容器是否正常运行。如果状态异常，使用 docker compose logs hexo 查看详细错误日志。
   • 确认端口占用：检查宿主机 4001 端口是否被其他程序占用：netstat -tulpn | grep 4001。

2. 文章或配置修改后未生效

   • 确保文件已正确保存到挂载的 app 目录中。
   • 尝试重启容器：docker compose restart hexo。
   • 检查 Hexo 配置文件的语法是否正确，特别是 YAML 文件的缩进和冒号后的空格。

3. 容器启动失败或不断重启

   • 查看日志获取具体错误信息：docker compose logs hexo。
   • 检查 app 目录的权限，确保 Docker 容器有读写权限。
   • 确认 docker-compose.yml 文件的语法正确。

4. 关于 spurin/hexo 镜像初始化

   • 首次启动时，如果 ./app 目录为空，该镜像可能会执行初始化流程（如克隆基础框架、运行 npm install），这可能需要几分钟，请耐心等待并查看日志。

5. Alpine 镜像兼容性问题

   • 如果您使用或构建基于 Alpine Linux 的镜像，有时可能会遇到某些 Node.js 模块或依赖的兼容性问题（例如 command not found 错误）。可以考虑换用基于其他 Linux 发行版（如 Debian）的 Node.js 基础镜像，或确保在 Alpine 中正确安装了所有依赖。

---

希望这篇教程能帮助你顺利完成 Hexo 博客的 Docker Compose 部署！Docker 化部署大大简化了环境配置，让你能更专注于内容创作。如果在使用中遇到更复杂的问题，可以参考 Hexo 官方文档、所使用的 Docker 镜像的说明页，或在相关的技术社区寻求帮助。

---

🐛 常见问题排查2

1. 预览服务访问不了（ERR_CONNECTION_REFUSED）

• 原因 1：4001 端口未开放或被占用。解决：

  1. 检查端口占用：sudo lsof -i :4001，若占用则停止对应服务；
  2. 重新开放端口：sudo ufw allow 4001/tcp，云服务器同步安全组。
  3. 原因 2：容器内预览服务未启动。解决：进入容器命令行执行 hexo server，确保服务启动（日志显示 Hexo is running at http://localhost:4000）。

2. 文章修改后预览不更新

• 原因 1：未重启预览服务或未刷新浏览器。解决：修改后执行 hexo server 重启服务，或按 Ctrl+Shift+R 强制刷新浏览器。

• 原因 2：Markdown 文件路径错误（未放在 source/_posts 目录）。解决：确保文章文件存储在 ./app/source/_posts 目录下，Hexo 仅识别该目录的文章。

3. 主题更换后页面空白或报错

• 原因 1：主题名称配置错误（与 themes 目录下的主题文件夹名不一致）。解决：检查 _config.yml 中 theme 的值（如 Next 主题文件夹名为 next，则 theme: next）。

• 原因 2：主题未正确克隆（文件夹为空或缺失）。解决：容器内重新克隆主题：rm -rf themes/next && git clone https://github.com/next-theme/hexo-theme-next.git themes/next。

4. 执行 hexo deploy 部署失败（提示 Git 错误）

• 原因 1：未配置 GIT_USER 和 GIT_EMAIL 环境变量。解决：修改 docker-compose.yml，取消注释并填写实际信息：

    environment:
      - GIT_USER=你的用户名
      - GIT_EMAIL=你的邮箱

重启容器：docker compose up -d。

• 原因 2：未配置部署目标（如 GitHub Pages）。解决：编辑 ./app/_config.yml，添加部署配置（以 GitHub 为例）：

    deploy:
      type: git
      repo: https://github.com/你的用户名/你的仓库名.git
      branch: main

通过以上步骤，新手可快速搭建 Hexo 静态博客，并掌握文章发布、主题更换等核心操作。Hexo 生态丰富，后续可探索评论插件（如 Waline）、SEO 优化等功能，具体可参考 Hexo 官方文档。