主 题
博客系统自文档 · 第 1/16 篇
目录 · 上一篇：导读：这个系统是什么 · 下一篇：文章、分类、标签与发现
写在前面
导读篇讲了「系统有什么」；本篇回答：用户点一下链接，请求到底经过了谁？
读完后你能画出 jiang-xia.top 上首页、API、静态资源、WebSocket 各走哪条路——这对部署排错和性能优化（第 14 篇）是前置知识。
功能与体验：三个入口
| 入口 | 域名 / 路径 | 用户看到什么 |
|---|---|---|
| C 端前台 | https://jiang-xia.top |
文章、RPG、工具箱 |
| 管理后台 | https://admin.jiang-xia.top |
Arco 管理 SPA |
| API | https://jiang-xia.top/x-blog/api/v1/ |
前台/后台 JSON 接口（Swagger 在 /doc） |
本地开发对应端口：5050（Home）、9856（Admin）、5000（Server）。Home 通过 /blog-api 代理到 localhost:5000/api/v1。
设计与实现：生产请求链路
总览
flowchart TB
Browser[浏览器]
Nginx[Nginx jiang-xia.top]
subgraph static [静态直出 - 不经过 Node]
NuxtAssets["/_nuxt/* hash 资源"]
Fonts["/fonts/*"]
Uploads["/x-blog/api/v1/static/uploads/*"]
end
subgraph dynamic [动态]
NuxtSSR["@nuxt → :5050 SSR"]
NestAPI["/x-blog/api/v1/ → :5000"]
SocketIO["/socket.io/ → :5000"]
end
Browser --> Nginx
Nginx --> NuxtAssets
Nginx --> Fonts
Nginx --> Uploads
Nginx --> NuxtSSR
Nginx --> NestAPI
Nginx --> SocketIO
1. HTML 页面（SSR）
location / 配置为：
- 先在
blog-home-nuxt/output/public找静态文件（如robots.txt） - 未命中则走
@nuxt反代 127.0.0.1:5050
因此首页、详情页等 HTML 由 Nuxt SSR 实时生成，Nginx 不对 HTML 做长期缓存（见 proxy-nuxt.conf）。
关键文件：deploy/nginx/conf.d/jiang-xia.top.conf 第 165–178 行。
2. API 请求
| 路径前缀 | 转发目标 | 限流 |
|---|---|---|
/x-blog/api/v1/rpg/ |
:5000/api/v1/rpg/ |
rpg_perip 专用 |
/x-blog/api/v1/ |
:5000/api/v1/ |
perip 通用 |
/x-blog/api/v1/doc/ |
Swagger 文档 | 较宽松 |
C 端 axios 生产 baseURL 为 https://jiang-xia.top/x-blog/api/v1（见 blog-admin/.env.production 同类配置）。
3. 静态资源分流（2026-06 性能优化）
| 路径 | 策略 | 原因 |
|---|---|---|
/_nuxt/* |
Nginx alias + immutable 1y | 文件名带 content-hash，发版自动换 URL |
/fonts/* |
短缓存 ~1d | 固定文件名，改子集需 bump ?v= |
| uploads | alias 直读磁盘 + 30d | 减轻 Nest 静态 IO |
| HTML | 走 SSR，no-cache | 保证内容新鲜 |
上传文件两种 URL 等价直出：
/x-api/blog-server/static/uploads/...（旧）/x-blog/api/v1/static/...（新）
4. WebSocket（全站 /realtime）
Socket.IO 走 /socket.io/ 反代到 blog-server :5000。Home 连接 ${origin}/realtime namespace，用于 RPG 反馈、站内通知等（详见第 03、10 篇）。
5. 管理后台
admin.jiang-xia.top 为 纯静态 SPA（blog-admin/dist），无 Node 进程；所有数据请求打到主域 API。
一次详情页加载涉及谁？
以 GET /detail/105 为例：
- Nginx → Nuxt SSR 返回 HTML（含文章列表骨架或部分数据）
- 浏览器加载
/_nuxt/*.js→ Nginx 静态直出，长缓存 - 客户端
POST /x-blog/api/v1/article/info→ NestJS → MySQL - 评论等可能客户端懒加载（SSR 瘦身，见 PERFORMANCE-OPTIMIZATION.md）
- 若已登录，Socket.IO
/realtime并行连接
踩坑与取舍
- 为什么静态与 SSR 分离？ 带 hash 的 JS/CSS 占带宽大头，Nginx sendfile 直出比经 Node 转发更省 CPU；HTML 必须动态才能 SEO + 个性化。
location顺序很重要：/_nuxt/、uploads 等必须写在location /之前，否则会被 SSR 吃掉。- MySQL 9 客户端 vs 表 collation：自文档 SQL 导入时需
SET NAMES utf8mb4 COLLATE utf8mb4_general_ci（见docs/self-doc/sql/README.md）。
系列导航
- 目录
- 上一篇：导读 · 第 0 篇
- 下一篇：02 文章与发现（待发布）
延伸阅读
- Nginx 说明：deploy/nginx/README.md
- 首屏优化验收：PERFORMANCE-OPTIMIZATION.md
- Home 代理配置：
blog-home-nuxt/nuxt.config.ts中/blog-apidevProxy
全部评论(0)