米来吉的个人站
正在准备天气信息...

README

2026年2月3日

Mirage Site 技术文档

文档目的：描述当前站点的技术栈、架构、数据流、核心模块与运维方式，方便后续维护与扩展。

1. 项目概览

Mirage Site 是一个基于 Next.js App Router 的个人站点，提供主页、壁纸、文章、友链、留言等功能。项目重点在于：

  • 玻璃拟态风格与动效体验
  • 本地文件持久化的留言板
  • 从本地 docs/articles 加载 Markdown 文章
  • 天气小组件（QWeather API）
  • Bing 壁纸代理与展示

2. 技术栈

  • 框架：Next.js 14（App Router）
  • 前端：React 18
  • 运行时：Node.js 20（Docker 镜像）
  • 样式：全局 CSS（app/globals.css）
  • 数据存储：文件系统（data/guestbook.json、docs/articles/*.md）
  • API：Next.js Route Handlers（app/api/*）

3. 目录结构

关键目录与文件：

  • app/：App Router 页面、组件、API 端点
  • app/api/：后端 API 路由
  • app/lib/：文章加载和 Markdown 解析工具
  • app/components/：可复用 UI 组件
  • docs/articles/：文章 Markdown 文件（驱动文章页）
  • data/guestbook.json：留言板持久化数据
  • public/：静态资源与 public/assets/main.js

4. 路由与页面

App Router 页面：

  • /：主页（打字机效果 + 社交入口）
  • /wallpaper：Bing 每日壁纸展示
  • /docs：文章列表（读取 docs/articles）
  • /docs/[slug]：文章详情页（渲染 Markdown）
  • /friends：友链展示
  • /guestbook：留言板（客户端渲染）

5. 核心模块说明

5.1 文章系统（本地 Markdown）

数据来源：docs/articles/*.md

  • 读取逻辑：app/lib/docs.js
  • Markdown 渲染：app/lib/markdown.js

行为：

  • 文章列表：读取目录所有 .md 文件，按 mtime 排序
  • 文章详情：根据 slug 读取文件并转为 HTML
  • 标题提取：首行 # 作为标题
  • 摘要生成：剥离 Markdown 与代码块，截断至 120 字

5.2 留言板（文件持久化）

客户端组件：app/guestbook/GuestbookClient.js

后端 API：app/api/guestbook/route.js

数据持久化：data/guestbook.json

接口功能：

  • GET /api/guestbook：分页返回留言（默认每页 8 条，最大 40）
  • POST /api/guestbook：新增留言（限制字数与昵称长度）

安全控制：

  • IP 简单频率限制（20 秒内禁止重复提交）
  • 留言长度上限 200 字，昵称上限 20 字
  • 文件持久化保存最新 200 条

5.3 天气组件（QWeather API）

客户端组件：app/components/WeatherWidget.js

服务端 API：app/api/qweather/route.js

功能：

  • 自动定位天气（浏览器定位）
  • 失败时允许手动搜索城市
  • 支持反向地理查询与天气展示

API 端点：

  • type=now：当前天气
  • type=geo：地点搜索（限制范围中国）
  • type=reverse：经纬度反查

缓存策略：

  • 地理数据缓存 10 分钟
  • 天气数据缓存 5 分钟

5.4 Bing 壁纸

页面：app/wallpaper/page.js

API：

  • /api/bing-wallpaper：返回当天壁纸元信息
  • /api/bing-wallpaper-image：图片代理与防盗链

特性：

  • 代理接口限制域名，只允许 *.bing.com
  • 页面显示今日壁纸 + 最近 6 天
  • 图片下载通过代理 URL

5.5 页面布局与交互

  • 布局：app/layout.js
  • 导航：app/components/Nav.js
  • 页面切换动效：app/components/PageTransition.js
  • 壁纸路由效果：app/components/WallpaperRouteEffect.js

5.6 全局样式

全局 CSS 位于 app/globals.css，包含：

  • 玻璃拟态变量（--glass-*）
  • 明暗主题色切换
  • 背景渐变与动态光晕
  • 导航、面板、卡片等统一样式

6. 数据流与渲染方式

  • 文章页：服务端读取 Markdown 并在服务端渲染
  • 留言页：客户端加载数据 + 无限滚动
  • 天气组件：客户端定位 + API 请求
  • 壁纸页：服务端获取 Bing API 并渲染

7. 环境变量

  • QWEATHER_KEY：和风天气 API Key（必填）

8. 本地开发

bash
npm install
npm run dev

默认地址：http://localhost:3000

9. 生产构建

bash
npm run build
npm run start

10. Docker 部署

bash
docker build -t mirage-site .
docker run -p 3001:3000 \
  -e QWEATHER_KEY=your_key \
  -v $PWD/data:/app/data \
  -v $PWD/docs:/app/docs \
  mirage-site

或使用 docker-compose.yml：

bash
docker-compose up -d --build

11. 安全与边界

  • 留言内容以纯文本存储，前端由 React 默认转义渲染
  • docs 渲染采用自定义 Markdown 解析器并先行转义，避免任意 HTML 注入
  • /api/bing-wallpaper-image 强制限制域名，降低 SSRF 风险

12. 扩展建议

  • 增加文章元数据（日期、标签）并支持筛选
  • 留言板加入验证码或更完整的速率限制
  • 天气搜索增加国际范围支持
  • 文章 Markdown 支持表格与图片