> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2024921.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 项目架构

> 了解 Qingyu'Blog 的整体架构设计

## 目录结构

```
├── public/                    # 站点本体（部署目录）
│   ├── index.html             # 页面入口
│   ├── config.js              # 全站配置
│   ├── style.css              # 前台样式
│   ├── app.js                 # 前台逻辑
│   ├── admin.js               # 后台管理 SPA
│   ├── admin.css              # 后台样式
│   ├── i18n.js                # 国际化模块
│   ├── posts.js               # 静态模式文章数据
│   └── locales/               # 语言包
├── functions/                 # Cloudflare API
│   ├── _lib/
│   │   └── api-core.js        # API 核心逻辑
│   └── api/                   # 各端点路由
├── worker.js                  # Workers 入口
├── migrations/                # D1 数据库迁移
└── .github/workflows/
    └── deploy.yml             # 自动部署
```

## 双通道架构

Qingyu'Blog 的核心设计是**双通道架构**——同一份代码支持两种运行模式：

```mermaid theme={null}
graph TB
    A[app.js 前台逻辑] --> B{mode: auto 自动检测}
    B -->|/api/posts 成功| C[云端模式]
    B -->|/api/posts 失败| D[静态模式]
    C --> E[Cloudflare D1]
    C --> F[Session 会话]
    D --> G[posts.js]
    D --> H[localStorage]
```

## 前端架构

### 前台 (`app.js`)

* **真实路径路由**：无 hash，基于 `history.pushState`
* **Markdown 渲染**：内置解析器，支持代码高亮、TOC 生成
* **评论系统**：云端 D1 / 静态 localStorage，支持嵌套回复
* **文章加密**：PBKDF2 + AES-GCM 端到端加密
* **搜索**：实时匹配标题/标签/摘要
* **主题切换**：深色/浅色模式
* **多语言**：5 种语言，自动识别浏览器语言

### 后台 (`admin.js`)

完整的 SPA 管理界面：

| 模块   | 功能                    |
| ---- | --------------------- |
| 仪表盘  | 7 项统计卡片 + 30 天趋势图     |
| 文章管理 | 搜索/分类筛选/分页/置顶/加密      |
| 编辑器  | Markdown 实时预览 + 元数据编辑 |
| 评论管理 | 全局列表，审核/删除，回复链追踪      |
| 媒体库  | 图片上传（base64 存 D1）     |
| 站点设置 | 站点信息/个人资料/导航菜单        |

## 后端架构

### API 核心 (`api-core.js`)

所有 API 逻辑集中在单个文件中，被两处复用：

1. **Cloudflare Pages Functions**：`functions/api/` 下的路由文件
2. **Cloudflare Workers**：`worker.js` 的路由分发

### 缓存策略

| 接口类型        | Cache-Control                                      |
| ----------- | -------------------------------------------------- |
| 只读接口        | `public, s-maxage=60, stale-while-revalidate=300`  |
| RSS/Sitemap | `public, s-maxage=300, stale-while-revalidate=600` |
| 写操作         | `no-store`                                         |