perf(comments): 评论加载提速 + 骨架屏 + 友链弹窗 pjax 修复 + toast 统一 Message.js
优化： - initArtalk 加节点级幂等守卫（mount.__atkInited，失败回滚）， 消除 artalk.html/mypjax 多入口导致的 4× comments + 4× pv 重复请求 - fetch 包装层对无 body 的 GET/HEAD 去掉多余 content-type， 消掉 Artalk 对 GET /comments 的 CORS 预检（按完整 URL 缓存， 每篇文章都重付一次 RTT）。实测评论列表 +1150~1565ms → +626ms 修复： - 评论列表骨架屏改注入 .atk-list-body（原骨架在 #Comments 内， 被 Artalk.init 清空），list-loaded/故障/12s 兜底移除 - 友链申请弹窗抽成 modules/friendlink.js 进 page-only bundle （原内联脚本在 #pjax-container 外，pjax 后 flApplyOpenModal 未定义） - toast 统一走本地化 Message.js/Qmsg 适配层（保留 window.Toast/showToast 旧 API） 文档： - README / 架构总览 更新；新增 评论加载优化方案.md
This commit is contained in:
zqlit committed
1 parent
9e972f2b61
commit
50a906e07c
14 files changed
+1018
-486
No files matched your search
@@ -1,86 +1,155 @@
|
||||
# 博客项目说明
|
||||
# 优世界博客（usj.cc）
|
||||
|
||||
本项目使用 Hugo 构建，主题为 `Ying`。以下是主要的配置说明与脚本使用指南，方便后续查阅和维护。
|
||||
Hugo 静态博客 + 自研评论后端 + 写作后台。
|
||||
**构建与发布跑在腾讯云 CNB**（国内节点），单次发布约 3.5 分钟，境内/境外两条线路一次推完。
|
||||
|
||||
## 1. 常用脚本与工具 (Scripts)
|
||||
|
||||
项目包含多个 PowerShell 和 Node.js 脚本，用于自动化维护、检查和部署。
|
||||
|
||||
### 1.1 日常维护
|
||||
|
||||
* **新建文章 (`./new_post.ps1`)**
|
||||
* **用途**: 交互式创建新的博客文章。
|
||||
* **功能**: 自动引导输入标题、Slug、分类、标签等信息，并按 `YYYY-MM-DD-Slug` 格式创建 Page Bundle 目录和文件。
|
||||
* **运行**:
|
||||
```powershell
|
||||
./new_post.ps1
|
||||
```
|
||||
|
||||
* **手动构建与检查 (`./deploy.ps1`)**
|
||||
* **用途**: 手动执行构建，包含友链健康检查。
|
||||
* **流程**:
|
||||
1. 运行 `scripts/check_links.js` 检查友链连通性。
|
||||
2. 如果检查通过，执行 `hugo --minify` 生成静态文件。
|
||||
* **运行**:
|
||||
```powershell
|
||||
./deploy.ps1
|
||||
```
|
||||
|
||||
### 1.2 自动化与 CI/CD 工具
|
||||
|
||||
以下脚本主要在 GitHub Actions (`.github/workflows/upy.yml`) 中自动运行，也可手动用于调试：
|
||||
|
||||
* **友链数据同步 (`scripts/update_link_lite_json.ps1`)**
|
||||
* **功能**: 将 `themes/Ying/data/links.yaml` (YAML源数据) 转换为 `themes/Ying/static/json/link_lite.json`，供前端 JS 和检查脚本使用。
|
||||
|
||||
* **友链健康检查 (`scripts/check_links.js`)**
|
||||
* **功能**: 读取 `link_lite.json`，并发检查所有友链的可访问性。
|
||||
* **依赖**: `node-fetch` (内置于 Node 18+ 或作为依赖)。
|
||||
|
||||
* **朋友圈数据生成 (`scripts/generate_circle_data.js`)**
|
||||
* **功能**: 根据友链抓取 RSS/Atom 订阅源，生成朋友圈更新数据 (`friend_circle_data.json`)。
|
||||
* **依赖**: `rss-parser`.
|
||||
|
||||
* **构建安全预处理 (`scripts/add_draft_to_hidden.ps1`)**
|
||||
* **功能**: 在构建前扫描 `content/post`，将标记为 `status: hidden` 的文章强制设置为 `draft: true`，防止隐私文章意外泄露到公共列表。
|
||||
|
||||
* **CDN 刷新 (`scripts/RefreshCDN.py`)**
|
||||
* **功能**: 部署完成后调用 DogeCloud API 刷新 CDN 缓存。
|
||||
* **配置**: 需要在环境变量中设置 `DOGECLOUD_ACCESS_KEY` 等参数。
|
||||
> 架构全貌、迁移前后对比、运维要点 → [`架构总览.md`](架构总览.md)
|
||||
|
||||
---
|
||||
|
||||
## 2. 基础配置 (`hugo.toml`)
|
||||
## 一、项目构成
|
||||
|
||||
位于项目根目录下，控制网站的全局行为。
|
||||
| 子系统 | 位置 | 技术栈 |
|
||||
|---|---|---|
|
||||
| **内容** | `content/`、`themes/Ying/` | Hugo 0.128.2 extended + Ying 主题 |
|
||||
| **评论后端** | `blog-admin/` | artalk-cf：Cloudflare Workers + D1 + KV（`api.200181.xyz`） |
|
||||
| **写作后台** | `write-server/`（线上 `post.usj.cc`）、`write/`（本地 Windows） | Next.js |
|
||||
| **发布** | `.cnb.yml`、`deploy/` | CNB 流水线 + Dockerfile |
|
||||
|
||||
* **网站信息**: 标题、BaseURL、语言等。
|
||||
* **固定链接 (Permalinks)**:
|
||||
```toml
|
||||
[permalinks]
|
||||
post = "/:slug"
|
||||
```
|
||||
文章页面使用 Front Matter 中的 `slug` 字段作为文件名（例如 `https://usj.cc/my-post.html`）。
|
||||
---
|
||||
|
||||
## 3. 主题配置
|
||||
## 二、目录结构
|
||||
|
||||
* **主题目录**: `themes/Ying/`
|
||||
* **友链数据**: `themes/Ying/data/links.yaml`
|
||||
* 添加友链请直接编辑此 YAML 文件，构建时会自动同步到 JSON。
|
||||
|
||||
## 4. 文章管理指南
|
||||
|
||||
### URL 设置
|
||||
文章默认使用 `slug` 字段作为 URL 的文件名。
|
||||
```yaml
|
||||
title: "我的文章"
|
||||
date: 2023-01-01
|
||||
slug: "my-post"
|
||||
```
|
||||
生成的链接为: `https://usj.cc/my-post.html`
|
||||
blog/
|
||||
├── .cnb.yml # ★ CNB 流水线（push + 每日定时）
|
||||
├── deploy/Dockerfile # 构建镜像（hugo 二进制由 bin/linux/hugo 提供）
|
||||
├── bin/linux/hugo # Hugo extended 0.128.2（linux/amd64，供 CNB 构建用）
|
||||
├── content/
|
||||
│ ├── posts/<年>/<日期>-<标题>/ # 文章（Page Bundle，index.md + 图片）
|
||||
│ ├── about.md / links.md / circles.md / archives.md
|
||||
├── themes/Ying/ # 主题（layout / assets / data）
|
||||
├── static/ # 原样复制进产物（emotion 表情、image、js …）
|
||||
├── blog-admin/ # 评论后端（artalk-cf）
|
||||
├── write-server/ # 线上写作后台
|
||||
├── write/ # 本地写作前端
|
||||
├── scripts/ # 各类工具脚本（见第六节）
|
||||
├── hugo.toml # Hugo 主配置
|
||||
└── 架构总览.md # ★ 架构文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、内容写作
|
||||
|
||||
### 文章结构
|
||||
|
||||
每篇文章是一个 **Page Bundle**：
|
||||
|
||||
```
|
||||
content/posts/2024/2024-05-01-文章标题/
|
||||
├── index.md # 正文
|
||||
└── 配图.jpg # 同目录图片（可用相对路径引用）
|
||||
```
|
||||
|
||||
### URL 规则
|
||||
|
||||
由 front matter 的 `slug` 决定（`hugo.toml` 里 `permalinks.post = "/:slug"`）：
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "我的文章"
|
||||
date: 2024-05-01
|
||||
slug: "my-post"
|
||||
---
|
||||
```
|
||||
|
||||
生成 `https://usj.cc/my-post.html`（uglyURLs，带 `.html`）。
|
||||
|
||||
### 隐藏文章
|
||||
如果你想写一篇不公开在列表显示的文章（但可以通过链接访问）：
|
||||
1. 在 Front Matter 中添加 `status: hidden`。
|
||||
2. 自动化脚本会在构建时将其标记为 `draft: true` (配合特殊构建逻辑) 或进行其他处理。
|
||||
*注：具体表现取决于 CI 脚本的逻辑，通常用于草稿或隐藏页。*
|
||||
|
||||
在 front matter 加 `status: hidden`。构建前 `scripts/add_draft_to_hidden.py` 会把它转成
|
||||
`draft: true`，**不出现在列表里，但直达链接仍可访问**。
|
||||
|
||||
### 本地预览
|
||||
|
||||
```bash
|
||||
hugo server -D # 含草稿
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、发布流程
|
||||
|
||||
```
|
||||
写作（write-server / write/）
|
||||
│ git pushall
|
||||
▼
|
||||
CNB 主仓 zqlit/blog ──触发──► CNB 流水线（国内节点，约 3.5 分钟）
|
||||
├─ Hugo 构建
|
||||
├─ 同步到又拍云（境内源站）
|
||||
├─ 刷新又拍云 CDN
|
||||
├─ 刷新多吉云 CDN
|
||||
├─ 部署 EdgeOne Pages（境外线路）
|
||||
└─ 邮件通知
|
||||
```
|
||||
|
||||
- **推送**：`git pushall` = `git push origin main; git push gh main`
|
||||
（`origin` = CNB 主仓，`gh` = GitHub 备份）
|
||||
- **触发**：推送到 `main`；另有每日 `0 9 * * *`（北京时间）定时构建
|
||||
- **密钥**：全部来自 CNB 密钥仓库 `zqlit/blog-secrets`，经 `.cnb.yml` 的 `imports` 注入，
|
||||
**仓库里没有任何明文密钥**
|
||||
- 改动 `main` 即自动上线，本地无需构建
|
||||
|
||||
---
|
||||
|
||||
## 五、三个子系统
|
||||
|
||||
### 内容系统
|
||||
|
||||
Hugo + Ying 主题。`hugo.toml` 控站点信息、永久链接、Artalk 地址、弹幕等。
|
||||
|
||||
### 评论系统（`blog-admin/`）
|
||||
|
||||
自研的 **Artalk v2 兼容服务端**，跑在 Cloudflare Workers + D1（SQLite）+ KV：
|
||||
|
||||
- 前端用官方 Artalk 客户端（`themes/Ying/assets/js/libs/Artalk.js`，本地打包，非 CDN）
|
||||
- 后端 API 基址 `https://api.200181.xyz`（评论 `/api/v2/*` 与 RSS 订阅 `/api/*` 同一 Worker）
|
||||
- 部署：`cd blog-admin && npm run deploy`（详细步骤见 `blog-admin/README.md`、`部署清单.md`）
|
||||
|
||||
### 写作后台
|
||||
|
||||
- `write-server/`：线上版（Next.js），部署在独立主机
|
||||
- `write/`：本地 Windows 版
|
||||
|
||||
---
|
||||
|
||||
## 六、常用脚本（`scripts/`）
|
||||
|
||||
| 脚本 | 用途 | 在哪跑 |
|
||||
|---|---|---|
|
||||
| `add_draft_to_hidden.py` | 构建前把 `status: hidden` 转成草稿 | **CI** |
|
||||
| `refresh_cdn.js` | 刷新多吉云 CDN（零依赖） | **CI** |
|
||||
| `send_mail.js` | 构建结果邮件通知（零依赖 SMTP） | **CI** |
|
||||
| `setup-cnb-remotes.sh` | 切换/重建 git 远端（CNB 主仓 + GitHub 备份） | 本机 |
|
||||
| `optimize_images.js` | 图片批量压缩优化 | 本机 |
|
||||
| `generate_circle_data.js` | 抓友链 RSS 生成朋友圈数据 | 本机 |
|
||||
| `update_link_lite_json.ps1` | 友链 `links.yaml` → JSON | 本机 |
|
||||
| `add_ancient_chars.py` / `check_ancient_chars.py` / `merge_chars.py` | 字体生僻字增补与校验 | 本机 |
|
||||
| `cleanup_duplicates.js` / `migrate_slugs.js` | 一次性维护脚本 | 本机 |
|
||||
|
||||
> `deploy_*.sh`（又拍云 / EdgeOne / 定时）是本机手动部署的旧入口，**日常已不需要**——
|
||||
> 推送 `main` 由 CNB 自动完成。
|
||||
|
||||
---
|
||||
|
||||
## 七、相关文档
|
||||
|
||||
| 文档 | 内容 |
|
||||
|---|---|
|
||||
| `架构总览.md` | **当前架构全貌**（子系统、发布链路、迁移前后对比、运维要点） |
|
||||
| `CNB构建落地方案.md` | 迁 CNB 的实施方案与实测数据 |
|
||||
| `代码源与构建平台选型.md` | 平台对比（CNB / Gitee / GitLab / EdgeOne / 阿里云 ESA） |
|
||||
| `砍COS改造步骤.md` | 腾讯云 COS 下线记录 |
|
||||
| `blog-admin/README.md` | 评论后端完整说明 |
|
||||
| `blog-admin/部署清单.md` | 评论后端部署步骤 |
|
||||
Reference in new issue
Block a user