Origin-Blogs 博客构建介绍（Next.js + python + Vercel部署）

该博客基于 XHBlogs 框架进行搭建，感谢 XingHuiSama 大佬的开源。

XHBlogs 作为一个 Next.js 16 个人博客系统，采用 Glassmorphism 风格，拥有独立的本地 CMS 控制台，以及一个名为 Creative Workshop 的角色扮演风格游戏化系统。它涵盖了完整的部署故事：Node.js 18+ 和 Python 3.10+ 的前置条件、Vercel 和 GitHub Pages 部署选项、图片托管配置、AI 助手设置以及音乐小部件集成。

一、博客壳与布局（Layout）

layout 作为整个博客壳的汇编点。它设置全局元数据，拉取 globals.css Glassmorphism 设计代币（自定义 CSS 属性、Tailwind 指令、基序重置），并将每个页面包裹在一系列服务体系中——ThemeProvider 用于暗/光模式，MusicProvider 用于全局音乐播放器，ToastProvider 用于通知。背景特效（BackgroundSlider、ClickEffect、Danmaku）、全局 UI 元素（CyberCat 吉祥物、FloatingPlayer、GlobalToolbox）和 SplashScreen 都安装在这里，使得这个布局成为理解博客运行时结构的唯一平台。

二、siteConfig.ts —— 全局配置中心

siteConfig.ts 文件是整个项目中最被广泛依赖的模块，它是网站元数据、导航链接、社交资料、音乐播放列表 ID、主题默认和构建信息的唯一真实来源。几乎每个页面和组件都从该模块导入，包括作者姓名、网站标题、DeepSeek API 和音乐 API 端点。

‍

‍

‍

‍

‍

三、page.tsx —— 着陆页编排

page.tsx 是排位第二高的导出文件（14 次导入），负责协调着陆体验。它会在请求时读取并排序文件系统中的帖子和聊天记录，然后组装配置文件卡、搜索栏、帖子聊天轮播、歌词栏、音乐播放器、网站仪表盘和弹幕背景。MusicProvider 支撑整个网站的音乐系统，从网易云音乐 API 获取播放列表，管理音频播放，解析与同步显示的 LRC 歌词，并通过 React Context 实现播放控制。

Tip：在 Next.js 应用路由器中，服务器组件可以在请求时执行文件系统读取和数据获取，无需单独的 API 层。page.tsx 通过 Node.js fs API 直接读取 Markdown 文件，进行排序，并将数据作为 prop 传递给客户端组件——消除了基于 useEffect 的数据获取静态内容的需求。

让我很惊喜的是，React Context 结合 useReducer，可以创建一个无需外部库的轻量级状态管理模式。

四、my-blog-manager —— CMS 控制台

my-blog-manager 布局是整个项目中最高的 fan-out 文件，作为博客根布局的 CMS 对应文件。它包装所有管理页面，同时增加了 CMS 专属元素。维护带有时间戳的用户操作队列（添加、删除、清除）。每个内容管理页面都会推送到该队列，导航栏显示待处理的操作计数，创建了一个统一的同步工作流程，在提交到博客文件系统之前，先在本地分阶段处理变更。

‍

五、FastAPI 后端层

FastAPI 服务器（cms_core/main.py）是后端层的 BFS 根节点，安装了 11 个 API 路由器，这些路由器共同构成了 CMS 数据平面。每个路由器负责特定的内容域：

• config.py：双向读写 TypeScript siteConfig.ts（Python dict 转 TS 对象语法）
• drafts.py：通过 YAML 前页管理带 JSON 存储的草稿 CRUD 和 Markdown 同步
• sync.py：验证博客目录路径并执行文件级同步操作
• deploy.py：通过子进程调用处理 SSH 密钥生成、Git 环境搭建和 GitHub Pages/Vercel 部署

整个后端内部是统一的——所有路由器共享相同的文件系统访问模式和配置文件约定。

Tip：FastAPI 的路由器挂载模式（app.include_router(router, prefix='/api/...')）创建了一个模块化的 API 结构，每个域拥有自己的文件，包含路径操作、用于请求/响应验证的 Pydantic 模型，以及自动 OpenAPI 文档。FastAPI 支持 async/await 以支持文件操作和 HTTP 代理的非阻塞 I/O。

# 注册所有路由
app.include_router(music.router, prefix="/api/music", tags=["Music"])
app.include_router(config.router, prefix="/api/config", tags=["Config"])
app.include_router(picbed.router, prefix="/api/picbed", tags=["PicBed"])
app.include_router(drafts.router, prefix="/api/drafts", tags=["Drafts"])
app.include_router(gallery.router, prefix="/api/gallery", tags=["Gallery"])
app.include_router(friends.router, prefix="/api/friends", tags=["Friends"])
app.include_router(projects.router, prefix="/api/projects", tags=["Projects"])
app.include_router(moments.router, prefix="/api/moments", tags=["Moments"])
app.include_router(sync.router, prefix="/api/sync", tags=["Sync"])
app.include_router(deploy.router, prefix="/api/deploy", tags=["Deploy"])

六、灵境 —— RPG 游戏化层

tree/page.tsx 是 RPG 游戏化层，栏目上为"灵境"。负责汇总帖子、聊天和瞬间，然后传递给 CreativeWorkshopClient，计算用户 RPG 等级、经验进度和活动天数，然后呈现两个主题视图之一：AlchemyLab，一个带有收藏徽章、烧瓶动画和社炼金书架以及帝江号的三维 Three.js 粒子飞船，并基于二进制点云数据（spaceship.bin）渲染。

Tip：Three.js 加载性能优良粒子系统的二进制几何数据——spaceship.bin 文件包含预先计算的顶点位置，以点云形式渲染，而非传统网格，支持数千个粒子以 60fps 运行。PyWebView 通过嵌入系统 WebView 桥接了 Web 前端和原生桌面，提供 CMS 原生窗口控件和文件系统访问，同时保持 Web 技术中的界面。

‍

写在最后

XHBlogs 还有诸多隐藏的细节功能，期待极客朋友们在实际使用中慢慢探索。本项目旨在提供一套开箱即用的前端静态展示与后台管理方案。

如果你觉得这个项目对你有帮助，请务必在 GitHub 上为原作者点亮一颗 ⭐ Star！
‍