# 洛尘的技术笔记

这是洛尘（luochen570）的个人技术博客源码仓库，使用 [Hugo](https://gohugo.io/) 生成静态站点，主题为 [PaperMod](https://github.com/adityatelange/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 证书

## 仓库结构

```text
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
```

## 本地开发

### 克隆仓库

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

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

```bash
git submodule update --init --recursive
```

### 安装 Hugo

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

```text
Hugo Extended 0.161.1
```

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

### 启动本地预览

```bash
hugo server -D
```

访问：

```text
http://localhost:1313
```

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

## 写作规范

### 新建文章

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

```text
content/posts/example-post.md
```

基础 front matter：

```yaml
---
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 框线字符，防止博客字体渲染错位。
- **基础设施细节要可验证**：不要在文章里编造节点、域名、服务或部署方式。

## 构建

清理旧产物并构建：

```bash
rm -rf public/
hugo --minify
```

构建结果位于：

```text
public/
```

验证某篇文章是否生成：

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

## 部署流程

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

触发方式：

- 推送到 `main` 分支
- 手动触发 `workflow_dispatch`

工作流文件：

```text
.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 资源位于：

```text
deploy/
```

## 必需的 Gitea Actions Secrets

工作流依赖以下 Secrets：

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

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

## Git 工作流

常规内容更新：

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

更新 README 或配置：

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

## PaperMod 主题维护

查看 submodule 状态：

```bash
git submodule status
```

更新主题：

```bash
git submodule update --remote themes/PaperMod
```

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

```bash
rm -rf public/
hugo --minify
```

## 站点配置

主配置文件：

```text
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