博客系统自文档 · 第 1/16 篇
目录 · 上一篇：导读：这个系统是什么 · 下一篇：文章、分类、标签与发现
写在前面
导读篇讲了「系统有什么」；本篇回答：用户点一下链接，请求到底经过了谁？
读完后你能画出 jiang-xia.top 上首页、API、静态资源、WebSocket 各走哪条路——这对部署排错和性能优化（第 14 篇）是前置知识。
功能与体验：四个入口
| 入口 | 域名 / 路径 | 用户看到什么 |
|---|---|---|
| C 端 Web | https://jiang-xia.top |
文章、RPG、工具箱（Nuxt SSR） |
| C 端移动 | 微信小程序 / H5 | 与 Web 对齐的阅读、RPG、工具（uni-app） |
| 管理后台 | https://admin.jiang-xia.top |
Arco 管理 SPA |
| API | https://jiang-xia.top/x-blog/api/v1/ |
前台/后台 JSON 接口（Swagger 在 /x-blog/api/v1/doc） |
本地开发对应端口：5050（Home Web）、9000（uni-app H5）、9856（Admin）、5000（Server）。
| 客户端 | API baseURL（开发） | 说明 |
|---|---|---|
| blog-home-nuxt | http://localhost:5000/api/v1 或 Nitro /blog-api 代理 |
移动端联调 LAN 时推荐走 Nuxt 代理 |
| blog-home-uniapp | env/.env.development → VITE_SERVER_BASEURL=http://localhost:5000/api/v1 |
H5/小程序直连 Nest |
| blog-admin | VITE_API_BASE_URL |
同生产 API 前缀 |
设计与实现：Web 生产请求链路
总览
1. HTML 页面（SSR）
location / 配置为：
- 先在
blog-home-nuxt/.output/public找静态文件（如robots.txt；线上目录可能 symlink 为output/public） - 未命中则走
@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-home-nuxt/.env.production）；Admin 为 blog-admin/.env.production 的 VITE_API_BASE_URL。
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 与 uni-app 均连接 ${origin}/realtime namespace，用于 RPG 反馈、站内通知、充值到账等（详见第 03、10 篇）。
5. 管理后台
admin.jiang-xia.top 为 纯静态 SPA（blog-admin/dist），无 Node 进程；所有数据请求打到主域 API。
6. uni-app（移动端 / 小程序）
与 Web 不走同一条 Nginx SSR 链路：
| 形态 | 构建 | 运行 |
|---|---|---|
| H5 | pnpm build |
可独立部署静态站，或开发时 :9000 |
| 微信小程序 | pnpm build:mp |
微信开发者工具加载 dist/build/mp-weixin |
| App | pnpm dev:app |
HBuilderX / 模拟器 |
uni-app 无 SSR/RSS/Nitro，SEO 与订阅能力以 Web 端为准；API 与 WebSocket 与 Nuxt 共用 blog-server。
一次详情页加载涉及谁？（Web）
以 GET /detail/139 为例：
- Nginx → Nuxt SSR 返回 HTML（含文章列表骨架或部分数据）
- 浏览器加载
/_nuxt/*.js→ Nginx 静态直出，长缓存 - 客户端
GET /x-blog/api/v1/article/info?id=...→ 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）。 - 四端共用 API：改接口或 RBAC 时须同时考虑 Nuxt、uni-app、Admin 三个客户端。
系列导航
- 目录：博客系统分类
- 上一篇：00 导读：这个系统是什么
- 下一篇：02 文章、分类、标签与发现
- 导读：导读 · 第 0 篇
延伸阅读
- Nginx 说明：deploy/nginx/README.md
- 首屏优化验收：PERFORMANCE-OPTIMIZATION.md
- Home 代理配置：
blog-home-nuxt/nuxt.config.ts中/blog-apidevProxy - uni-app 联调：
blog-home-uniapp/env/.env.development
全部评论(0)