From dd3dbe8323a2494f217ac0d764ce2c63f89450ef Mon Sep 17 00:00:00 2001
From: luochen570 <1160510664@qq.com>
Date: Sun, 24 May 2026 10:52:41 +0800
Subject: [PATCH] docs: add README with project overview and workflow

---
 README.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1c10c06
--- /dev/null
+++ b/README.md
@@ -0,0 +1,138 @@
+# Hugo Blog
+
+洛尘（luochen570）的技术博客，使用 Hugo 静态站点生成器 + PaperMod 主题。
+
+线上地址：https://hugo.luochen570.cn
+
+## 技术栈
+
+- **Hugo** — 静态站点生成器
+- **PaperMod** — 主题（git submodule）
+- **Caddy** — HTTPS 反向代理（部署在 UC 服务器）
+- **Git** — 源码托管在自建 Gitea
+
+## 目录结构
+
+```
+hugo-blog/
+├── archetypes/              # 文章模板
+├── content/
+│   └── posts/               # 博客文章（Markdown）
+├── public/                  # 构建输出（临时生成，不提交）
+├── themes/
+│   └── PaperMod/            # 主题（git submodule）
+├── hugo.toml                # Hugo 配置文件
+├── .gitmodules              # 子模块配置
+└── README.md
+```
+
+## 本地开发
+
+### 前置条件
+
+```bash
+# 安装 Hugo（NixOS / 非 NixOS 均可）
+# 详见 https://gohugo.io/installation/
+
+# 克隆仓库并初始化子模块
+git clone git@git.luochen570.cn:luochen570/hugo-blog.git
+cd hugo-blog
+git submodule update --init --recursive
+```
+
+### 启动本地调试服务器
+
+```bash
+hugo server -D
+```
+
+访问 http://localhost:1313，`-D` 参数会显示草稿文章。
+
+## 写作规范
+
+### 新建文章
+
+在 `content/posts/` 下创建 `<slug>.md` 文件，格式如下：
+
+```yaml
+---
+date: '2026-05-24T09: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 框线字符
+
+## 构建
+
+```bash
+cd ~/hugo-blog
+
+# 清理构建（推荐）
+rm -rf public/
+hugo
+
+# 验证新文章已生成
+ls public/posts/<slug>/
+```
+
+## 部署
+
+构建完成后，通过 SSH 将 `public/` 目录同步到 UC 服务器：
+
+```bash
+cd ~/hugo-blog
+tar czf - public/ | ssh.exe root@152.32.213.27 \
+  "rm -rf /www/hugo.luochen570.cn/*; \
+   tar xzf - -C /www/hugo.luochen570.cn --strip-components=1; \
+   chown -R root:root /www/hugo.luochen570.cn/"
+```
+
+Caddy 会自动加载新文件，无需重启。
+
+## Git 工作流
+
+```bash
+git add content/posts/<slug>.md
+git commit -m "add post: 文章标题"
+git push
+```
+
+远程仓库：`git@git.luochen570.cn:luochen570/hugo-blog.git`
+
+## 配置说明
+
+`hugo.toml`：
+
+```toml
+baseURL = 'https://hugo.luochen570.cn/'
+locale = 'zh_cn'
+title = 'My New Hugo Project'
+theme = 'PaperMod'
+```
+
+PaperMod 主题作为 git submodule 管理，更新方式：
+
+```bash
+git submodule update --remote themes/PaperMod
+```
+
+## 相关链接
+
+- 线上博客：https://hugo.luochen570.cn
+- 源码仓库：`git@git.luochen570.cn:luochen570/hugo-blog.git`
+- 部署服务器：UC（152.32.213.27）
+- Caddy 配置：`/etc/caddy/Caddyfile`（服务器端）
+- PaperMod 主题：https://github.com/adityatelange/hugo-PaperMod