Hugo 部署教程

下面是一份相对完整的 Hugo 部署教程，帮助你在 Ubuntu 24.04 的云服务器（以 wzc 用户身份登录）上搭建并发布个人博客。该教程涵盖了 Hugo 安装、创建站点、使用主题、编译生成、以及通过 Nginx 或直接 Hugo Server 来对外提供服务等步骤。你可以根据实际需求选择性地精简或扩展其中的流程。

[TOC]

1. 一、准备工作

  1. 通过 SSH 登录到服务器

    ssh wzc@<服务器IP地址>

    成功登录后，后续所有命令均在这个远程终端环境下执行。

  2. 更新系统软件包

    sudo apt update && sudo apt upgrade -y

  3. 安装必备工具
    一般来说，后续会用到 git 来管理 Hugo 项目或拉取主题。如果系统中尚未安装，执行：

    sudo apt install git -y

2. 二、安装 Hugo

2.1. 方法 A：使用 APT 包管理器

Ubuntu 24.04 的官方仓库中通常已经包含了较新的 Hugo 版本，可以直接通过 apt 安装：

sudo apt install hugo -y

安装完成后可通过以下命令确认版本和是否成功安装：

hugo version

如果能看到类似 hugo vX.X.X-xxxx ... 说明安装成功。

2.2. 方法 B：从 Release 页面手动安装（可选）

如果你想要安装 Hugo 的最新版本，可以从其 GitHub Release 下载对应的 .deb 或 .tar.gz 包手动安装。这种方法适用于需要最新功能或 apt 仓库版本过旧时使用。示例：

# 根据官网最新版本选择下载链接（示例：hugo_extended_0.120.0_Linux-64bit.deb）
wget https://github.com/gohugoio/hugo/releases/download/v0.120.0/hugo_extended_0.120.0_Linux-64bit.deb

# 安装
sudo dpkg -i hugo_extended_0.120.0_Linux-64bit.deb

# 检查
hugo version

（请将上面示例中的版本号替换为发布时的最新版。）

3. 三、新建 Hugo 站点

  1. 选择工作目录
    为便于管理，你可以在 wzc 用户的家目录下新建一个文件夹，例如 ~/myblog 或者 ~/hugo 来存放你的网站。这里以 ~/myblog 为例：

    cd ~
mkdir myblog
cd myblog

  2. 初始化 Hugo 站点
    使用 hugo new site 命令来初始化站点结构：

    hugo new site blog

    此时会在 ~/myblog/blog 下自动创建一系列文件夹和配置文件，常见目录结构包括：

    ├── archetypes
├── assets
├── content
├── layouts
├── static
└── config.toml (或 config.yaml / config.json)

  3. 初始化 Git 仓库（可选）
    如果你想用 Git 管理整个 Hugo 站点，可以在 blog 目录下执行：

    cd blog
git init
git add .
git commit -m "Initial commit"

    这样后续可方便地进行版本控制或推送到 GitHub/Gitee 等代码托管平台。

4. 四、选择并配置主题

  1. 查找主题
    Hugo 官方主题库： themes.gohugo.io
    你可以在这里找一个自己喜欢的主题，比如常见的文档风 / Blog 风格主题，选择后复制其 Git 仓库地址。

  2. 添加主题到项目
    以 Ananke 为例，在 blog 文件夹下执行：

    git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

    （也可以直接 git clone 到 themes/ananke 下，或下载 zip 后手动解压到 themes/ananke。）

  3. 修改配置文件
    编辑 config.toml（如果你使用的是 config.yaml 或者 config.json，下面示例需要做相应转换）：

    baseURL = "http://example.com/"    # 改成你自己的域名或IP
languageCode = "zh-cn"
title = "我的Hugo博客"
theme = "ananke"

    其他配置信息，比如菜单、导航、SEO 设置等，可以根据主题文档进行自定义。

5. 五、创建内容并本地预览

  1. 新建文章
    在 blog 目录下：

    hugo new posts/hello-world.md

    默认会在 content/posts 目录生成 hello-world.md 文件，可打开编辑：

    ---
title: "Hello World"
date: 2024-12-29T12:00:00+08:00
draft: true
---
这是我的第一篇文章，使用 Hugo。

    将 draft 设置为 false 可以在发布时被包含。

  2. 本地预览
    Hugo 带有内置的开发服务器，可以让你在服务器上实时预览站点：

    hugo server -D
    • -D 选项表示包含 draft 草稿文章。
    • 启动后会显示一个本地访问地址，如 http://localhost:1313/。
    • 如果你希望外网通过 ECS 的 IP 地址访问预览，可以使用 --bind 0.0.0.0 --baseURL http://<服务器IP>:1313/ 启动，让其监听所有网卡。
      例如：
    hugo server -D --bind 0.0.0.0 --baseURL http://<服务器IP>:1313/

    然后通过浏览器访问 http://<服务器IP>:1313/ 就能看到你的 Hugo 站点的实时预览。

6. 六、生成静态文件

在确认内容、配置都没问题后，就可以生成静态文件用于正式部署：

hugo

执行成功后，会在 blog/public 目录下生成所有静态页面文件。你可以把 public 目录下的文件发布到任何静态 Web 服务器（Nginx、Apache 等）上即可对外访问。

7. 七、使用 Nginx 对外提供服务

7.1. 1. 安装 Nginx 

sudo apt update
sudo apt install nginx -y

安装完成后，Nginx 会自动启动，可以查看状态：

systemctl status nginx

7.2. 2. 配置 Nginx

  1. 创建网站目录
    一种常见做法是把 Hugo 生成的 public 文件复制或同步到 /var/www/<your_site> 下，也可以直接将 Hugo 的 public 目录设为网站根目录。下面以 /var/www/myhugosite 为例：

    sudo mkdir -p /var/www/myhugosite
sudo chown -R www-data:www-data /var/www/myhugosite

  2. 将 Hugo 输出的静态文件复制过去
    在 ~/myblog/blog 目录下执行：

    hugo
# 把生成的 public 文件夹内容拷贝到 /var/www/myhugosite
cp -r public/* /var/www/myhugosite/
# 注意复制后，最好确保文件属主属组为 www-data
sudo chown -R www-data:www-data /var/www/myhugosite

  3. 配置 Nginx 虚拟主机
    创建一个新的配置文件，比如 /etc/nginx/sites-available/myhugosite.conf：

    server {
    listen 80;
    server_name example.com;  # 改成你的域名或者服务器IP

    root /var/www/myhugosite;
    index index.html;

    # 如果需要处理一些 404 或者特定规则可以在此处添加
    location / {
        try_files $uri $uri/ =404;
    }
}

    建立符号链接使其生效：

    sudo ln -s /etc/nginx/sites-available/myhugosite.conf /etc/nginx/sites-enabled/

  4. 测试并重启 Nginx

    sudo nginx -t
sudo systemctl reload nginx

    现在，你访问 http://example.com（或 IP 地址）即可看到 Hugo 生成的网页内容。

7.3. 3. 配置 HTTPS（可选但强烈推荐）

如果你已经有自己的域名并正确解析到 ECS 服务器，可以通过 Certbot 免费申请并自动配置 HTTPS 证书：

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d example.com

根据命令行提示进行操作，最终可以获得有效的 SSL/TLS 证书并自动更新。

8. 八、使用 Hugo Server 直接对外提供服务（可选）

如果你不想使用 Nginx，也可以让 Hugo 自带的 Server 在 80 或其他端口直接对外提供服务。但这并不是生产环境的最佳做法，原因是 Hugo Server 不等同于专业的 Web 服务器，而且 SSL 证书、负载均衡、缓存等功能 Hugo Server 并不直接提供。不过若你只是轻量使用或临时展示，可这样操作：

# 以 80 端口对外 (需要 sudo 权限，因为端口 < 1024)
sudo hugo server -D --bind 0.0.0.0 --baseURL http://<服务器IP> --port 80

注意：端口 80 一般被系统占用，需要先停止 Nginx，否则会冲突。

9. 九、后续优化建议

  1. 自动化部署

    • 你可以通过 Git + CI/CD（GitHub Actions、Gitee Pages、GitLab CI 等）来实现每次提交更新后，自动在服务器上拉取代码并 hugo 编译。
    • 或者写一个简单的脚本，把代码更新 + hugo + 复制到 /var/www/myhugosite 的流程自动化。

  2. 多站点或子目录部署

    • 如果你计划维护多个站点或者想在子目录下部署 Hugo，可以在 Nginx 里配置多个 server 块或 location 块。
    • Hugo 的 baseURL 配置也需要做相应调整。

  3. 主题自定义

    • 若需要深度定制主题，可以编辑 themes/xxx/layouts/ 或在 layouts 下创建同名文件覆盖主题默认模板，实现更灵活的定制化。

  4. 安全与备份

    • 生产环境建议定期备份 /var/www/myhugosite 以及你的 Hugo 源码（~/myblog/blog），防止意外丢失。
    • 建议使用防火墙、Fail2Ban 等措施，确保服务器安全。

  5. 升级 Hugo

    • 定期升级 Hugo 和系统依赖，以获取最新特性和安全补丁。
    • 如果遇到 Hugo 大版本更新，需要留意主题或插件的兼容性。

10. 结语

通过上述步骤，你就能在 Ubuntu 24.04（ECS 服务器）上，以 wzc 用户身份，在家目录下搭建并部署一个基于 Hugo 的个人博客 / Wiki 站点。若有进一步需求（如搜索功能、评论系统、定制导航栏等），可查看所用主题或 Hugo 官方文档，往往能通过 配置 或 短代码（shortcodes）扩展来实现。

祝你搭建顺利，玩得开心！