洛尘的技术笔记

这是洛尘（luochen570）的个人技术博客源码仓库，使用 Hugo 生成静态站点，主题为 PaperMod，通过自建 Gitea Actions 构建并部署到 k3s 集群。

线上地址：https://hugo.luochen570.cn

技术栈

• Hugo Extended：静态站点生成器
• PaperMod：博客主题，作为 Git submodule 管理
• Gitea Actions：CI/CD 构建与部署
• Docker / Nginx：将 Hugo 构建产物打包成容器镜像
• k3s：运行博客服务
• Traefik + cert-manager：Ingress 与 HTTPS 证书

仓库结构

hugo-blog/
├── .gitea/workflows/        # Gitea Actions 工作流
├── archetypes/              # Hugo 内容模板
├── content/                 # Markdown 内容
│   ├── about.md             # 关于页面
│   ├── archives.md          # 归档页面
│   ├── search.md            # 搜索页面
│   └── posts/               # 博客文章
├── deploy/                  # k3s 部署清单
├── themes/PaperMod/         # PaperMod 主题 submodule
├── Dockerfile               # 静态站点容器镜像
├── hugo.toml                # Hugo 主配置
└── README.md

本地开发

克隆仓库

git clone --recurse-submodules git@git.luochen570.cn:luochen570/hugo-blog.git
cd hugo-blog

如果克隆时没有带 --recurse-submodules：

git submodule update --init --recursive

安装 Hugo

需要安装 Hugo Extended。版本建议与 CI 中的版本保持一致，当前工作流使用：

Hugo Extended 0.161.1

安装方式参考官方文档：https://gohugo.io/installation/

启动本地预览

hugo server -D

访问：

http://localhost:1313

-D 会显示草稿文章。生产构建不会包含 draft: true 的内容。

写作规范

新建文章

文章放在 content/posts/ 下，文件名建议使用英文 slug：

content/posts/example-post.md

基础 front matter：

---
date: '2026-06-01T20:00:00+08:00'
draft: false
title: '文章标题'
tags:
  - tag1
  - tag2
categories:
  - 技术
---

重要规则

• 日期必须是过去时间：Hugo 默认不会构建未来日期的文章。
• 发布前设置 draft: false：草稿不会进入生产站点。
• 不要暴露真实公网 IP：文档、文章、示例配置中统一使用 x.x.x.x。
• 不要暴露真实服务器地理位置：使用“私有云”“公有云”等泛化表述。
• 拓扑图使用 ASCII：避免使用 Unicode 框线字符，防止博客字体渲染错位。
• 基础设施细节要可验证：不要在文章里编造节点、域名、服务或部署方式。

构建

清理旧产物并构建：

rm -rf public/
hugo --minify

构建结果位于：

public/

验证某篇文章是否生成：

ls public/posts/<slug>/index.html

部署流程

本仓库通过 Gitea Actions 自动部署。

触发方式：

• 推送到 main 分支
• 手动触发 workflow_dispatch

工作流文件：

.gitea/workflows/deploy.yml

CI/CD 大致流程：

1. Checkout 源码
2. 安装 Hugo
3. 执行 hugo --minify
4. 构建 Docker 镜像
5. 推送镜像到自建 Gitea Container Registry
6. 使用 kubeconfig 更新 k3s 中的 hugo-blog Deployment 镜像
7. 等待 Kubernetes rollout 完成

相关 Kubernetes 资源位于：

deploy/

必需的 Gitea Actions Secrets

工作流依赖以下 Secrets：

• REGISTRY_TOKEN：推送镜像到 Gitea Container Registry
• KUBECONFIG_B64：用于部署到 k3s 的 kubeconfig，内容为 base64 编码

不要把 token、kubeconfig 或其它密钥提交到仓库。

Git 工作流

常规内容更新：

git status
git add content/posts/<slug>.md
git commit -m "add post: 文章标题"
git push

更新 README 或配置：

git add README.md hugo.toml .gitea/workflows/deploy.yml deploy/
git commit -m "docs: update blog documentation"
git push

PaperMod 主题维护

查看 submodule 状态：

git submodule status

更新主题：

git submodule update --remote themes/PaperMod

更新后建议本地构建并检查页面样式：

rm -rf public/
hugo --minify

站点配置

主配置文件：

hugo.toml

当前站点配置包括：

• 站点标题：洛尘的技术笔记
• 语言环境：zh_cn
• 主题：PaperMod
• 首页信息块：PaperMod homeInfoParams
• 搜索输出：JSON
• 菜单：首页、文章、归档、标签、分类、搜索、关于

常见问题

新文章构建后看不到

检查：

• date 是否是未来时间
• draft 是否为 true
• 文件是否放在 content/posts/
• 构建后 public/posts/<slug>/index.html 是否存在

CI 下载 Hugo 或依赖失败

Runner 环境会通过集群内代理改善外网访问。如果仍失败，优先检查：

• Gitea Actions runner 是否在线
• Docker daemon 是否能拉取镜像
• k3s 中代理服务是否 Running
• 工作流中的 Secrets 是否存在

部署成功但线上没变化

检查：

• Gitea Actions 是否跑在最新 commit
• 镜像 tag 是否更新到当前 commit SHA
• hugo namespace 下的 Deployment rollout 是否完成
• Ingress host 是否仍包含 hugo.luochen570.cn

相关链接

• 线上博客：https://hugo.luochen570.cn
• 源码仓库：git@git.luochen570.cn:luochen570/hugo-blog.git
• 主题：PaperMod
• 运行环境：k3s + Traefik + cert-manager