docs: update README

2026-06-02 07:42:09 +08:00
parent c6eb1e1654
commit bdef80e05e
1 changed files with 183 additions and 62 deletions
--- a/README.md
+++ b/README.md
@@ -1,138 +1,259 @@
-# Hugo Blog
+# 洛尘的技术笔记

-洛尘（luochen570）的技术博客，使用 Hugo 静态站点生成器 + PaperMod 主题。
+这是洛尘（luochen570）的个人技术博客源码仓库，使用 [Hugo](https://gohugo.io/) 生成静态站点，主题为 [PaperMod](https://github.com/adityatelange/hugo-PaperMod)，通过自建 Gitea Actions 构建并部署到 k3s 集群。

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

 ## 技术栈

- **Hugo** — 静态站点生成器
- **PaperMod** — 主题（git submodule）
- **Caddy** — HTTPS 反向代理（部署在 UC 服务器）
- **Git** — 源码托管在自建 Gitea
+- **Hugo Extended**：静态站点生成器
+- **PaperMod**：博客主题，作为 Git submodule 管理
+- **Gitea Actions**：CI/CD 构建与部署
+- **Docker / Nginx**：将 Hugo 构建产物打包成容器镜像
+- **k3s**：运行博客服务
+- **Traefik + cert-manager**：Ingress 与 HTTPS 证书

-## 目录结构
+## 仓库结构

-```
+```text
 hugo-blog/
-├── archetypes/              # 文章模板
-├── content/
-│   └── posts/               # 博客文章（Markdown）
-├── public/                  # 构建输出（临时生成，不提交）
-├── themes/
-│   └── PaperMod/            # 主题（git submodule）
-├── hugo.toml                # Hugo 配置文件
-├── .gitmodules              # 子模块配置
+├── .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
-# 安装 Hugo（NixOS / 非 NixOS 均可）
-# 详见 https://gohugo.io/installation/
-
-# 克隆仓库并初始化子模块
-git clone git@git.luochen570.cn:luochen570/hugo-blog.git
+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
 ```

-访问 http://localhost:1313，`-D` 参数会显示草稿文章。
+访问：
+
+```text
+http://localhost:1313
+```
+
+`-D` 会显示草稿文章。生产构建不会包含 `draft: true` 的内容。

 ## 写作规范

 ### 新建文章

-在 `content/posts/` 下创建 `<slug>.md` 文件，格式如下：
+文章放在 `content/posts/` 下，文件名建议使用英文 slug：
+
+```text
+content/posts/example-post.md
+```
+
+基础 front matter：

 ```yaml
 ---
-date: '2026-05-24T09:00:00+08:00'
+date: '2026-06-01T20:00:00+08:00'
 draft: false
 title: '文章标题'
 tags:
  - tag1
  - tag2
 categories:
-  - 分类
+  - 技术
 ---
 ```

-### 内容规则
+### 重要规则

- **日期必须在过去** — Hugo 默认跳过未来日期的文章。构建后检查 `public/posts/<slug>/` 是否存在
- **草稿** — `draft: true` 的文章不会出现在生产构建中。发布前确保为 `false`
- **节点/IP 准确性** — 仅提及实际存在的节点/服务器
- **隐私保护** — 不暴露真实地理位置，使用"私有云/公有云"替代；IP 使用 `x.x.x.x` 替代
- **ASCII 图表** — 网络拓扑图使用纯 ASCII 字符（`+` `-` `|`），不使用 Unicode 框线字符
+- **日期必须是过去时间**：Hugo 默认不会构建未来日期的文章。
+- **发布前设置 `draft: false`**：草稿不会进入生产站点。
+- **不要暴露真实公网 IP**：文档、文章、示例配置中统一使用 `x.x.x.x`。
+- **不要暴露真实服务器地理位置**：使用“私有云”“公有云”等泛化表述。
+- **拓扑图使用 ASCII**：避免使用 Unicode 框线字符，防止博客字体渲染错位。
+- **基础设施细节要可验证**：不要在文章里编造节点、域名、服务或部署方式。

 ## 构建

-```bash
-cd ~/hugo-blog
+清理旧产物并构建：

-# 清理构建（推荐）
+```bash
 rm -rf public/
-hugo
-
-# 验证新文章已生成
-ls public/posts/<slug>/
+hugo --minify
 ```

-## 部署
+构建结果位于：

-构建完成后，通过 SSH 将 `public/` 目录同步到 UC 服务器：
+```text
+public/
+```
+
+验证某篇文章是否生成：

 ```bash
-cd ~/hugo-blog
-tar czf - public/ | ssh.exe root@x.x.x.x \
-  "rm -rf /www/hugo.luochen570.cn/*; \
-   tar xzf - -C /www/hugo.luochen570.cn --strip-components=1; \
-   chown -R root:root /www/hugo.luochen570.cn/"
+ls public/posts/<slug>/index.html
 ```

-Caddy 会自动加载新文件，无需重启。
+## 部署流程
+
+本仓库通过 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
 ```

-远程仓库：`git@git.luochen570.cn:luochen570/hugo-blog.git`
+更新 README 或配置：

-## 配置说明
-
-`hugo.toml`：
-
-```toml
-baseURL = 'https://hugo.luochen570.cn/'
-locale = 'zh_cn'
-title = 'My New Hugo Project'
-theme = 'PaperMod'
+```bash
+git add README.md hugo.toml .gitea/workflows/deploy.yml deploy/
+git commit -m "docs: update blog documentation"
+git push
 ```

-PaperMod 主题作为 git submodule 管理，更新方式：
+## 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`
- 部署服务器：UC（公有云）
- Caddy 配置：`/etc/caddy/Caddyfile`（服务器端）
- PaperMod 主题：https://github.com/adityatelange/hugo-PaperMod
+- 主题：PaperMod
+- 运行环境：k3s + Traefik + cert-manager