260 lines
5.5 KiB
Markdown
260 lines
5.5 KiB
Markdown
# 洛尘的技术笔记
|
||
|
||
这是洛尘（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
|