Skip to content

Commit 94b4735

Browse files
InneiInnei
authored
docs(migrate): add v12 → v13 upgrade guide (#40)
mx-core v13.0.0 ships the V3 response envelope, snake_case schema, named views, and bumps the route prefix from `/api/v2/*` to `/api/v3/*`. Document the upgrade path: server upgrade is mechanical (no data migration), mx-admin must move to v8 in lockstep, and `@mx-space/api-client@5`'s legacy adapter lets frontend consumers stay on V1 wire shape while they migrate endpoint-by-endpoint. Hook the new page into the migrate section meta and the overview index card.
1 parent d6dac11 commit 94b4735

3 files changed

Lines changed: 224 additions & 0 deletions

File tree

‎content/docs/migrate/index.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@ import { Card, Cards } from 'fumadocs-ui/components/card'
88
import { ArrowUp, Globe } from 'lucide-react'
99

1010
<Cards>
11+
<Card
12+
icon={<ArrowUp />}
13+
href={'/docs/migrate/v12-to-v13'}
14+
title="v12 → v13 升级"
15+
>
16+
V3 API 响应契约切换、api-client v5 与 mx-admin v8 同步升级
17+
</Card>
1118
<Card
1219
icon={<ArrowUp />}
1320
href={'/docs/migrate/v11-to-v12'}

‎content/docs/migrate/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"root": true,
55
"pages": [
66
"index",
7+
"v12-to-v13",
78
"v11-to-v12",
89
"from-wordpress"
910
]

‎content/docs/migrate/v12-to-v13.mdx‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: v12 升级到 v13
3+
description: 从 v12 升级到 v13 的指南，含 V3 API 响应契约切换、api-client v5 与 mx-admin v8 同步升级
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Card, Cards } from 'fumadocs-ui/components/card'
8+
import { AlertTriangle, CheckCircle, Container, Pickaxe, RotateCcw } from 'lucide-react'
9+
10+
<Callout type="warn">
11+
v13 是一次 **API 契约的 breaking change**：列表与详情端点改用 V3 响应封套 `{ data, meta }`，字段命名一律 snake_case，路由前缀由 `/api/v2/*` 改为 `/api/v3/*`。前端可经 `@mx-space/api-client@5` 之 legacy adapter 渐进迁移，无须一次改尽。
12+
13+
数据层、文章/评论/图片等数据本身**不会改动**，亦无须数据库迁移。仅是接口形态变了。
14+
</Callout>
15+
16+
## 升级前必读（2 分钟）
17+
18+
### 这次升级会变什么？
19+
20+
- **路由前缀**：`/api/v2/*` → `/api/v3/*`
21+
- **响应封套**：`{ ...resource }` 直平展 → `{ data, meta }`，资源字段进 `data`，平台元数据（pagination、translation、enrichments、related、insights）进 `meta`
22+
- **字段命名**：mixedCase / camelCase 不再混用，统一 **snake_case**
23+
- **named views**：列表端点用 `card` 视图（精简字段），详情端点用 `detail` 视图（全字段）
24+
- **后台 dashboard**：mx-core v13 的 dashboard 钉版从 v7.4.0 升到 **v8.0.0**，自建用户须同步部署 mx-admin v8
25+
26+
### 什么不会变？
27+
28+
- 数据库 schema、文章/评论/图片/配置等数据**完全不变**
29+
- 登录方式、密码、API Key、Better-Auth 会话不受影响
30+
- WebSocket / SSE 端点形态不变
31+
- 文件上传、备份机制不变
32+
33+
### 我需要停站多久？
34+
35+
| 场景 | 预估时间 |
36+
|---|---|
37+
| Docker 拉新镜像 + dashboard 升级 | 2–5 分钟 |
38+
| 源码部署 `pnpm i + build` | 5–10 分钟 |
39+
40+
无数据迁移步骤，停站窗口比 v11→v12 短得多。
41+
42+
---
43+
44+
## 升级 Checklist
45+
46+
开始前请确认：
47+
48+
- [ ] 当前版本是 **v12.x**（若仍在 v11，先依 [v11→v12 指南](/docs/migrate/v11-to-v12)）
49+
- [ ] 准备好与 mx-core v13 配套的 **mx-admin v8.0.0** 部署
50+
- [ ] 直调 mx-core REST 的第三方脚本/工具已盘点（小程序、外部聚合等）
51+
52+
---
53+
54+
## 第一步：升级 mx-core 服务端
55+
56+
### Docker 部署
57+
58+
```bash
59+
cd ~/mx-space/core
60+
61+
# 拉取 v13 镜像
62+
docker compose pull app
63+
64+
# 重启业务进程（PostgreSQL/Redis 保持运行）
65+
docker compose up -d app
66+
```
67+
68+
确认日志中出现 `Mix Space v13.x.x started`。
69+
70+
### 源码 / PM2 部署
71+
72+
```bash
73+
cd ~/mx-space/core
74+
75+
git fetch origin --tags
76+
git checkout v13.x.x # 或 master
77+
pnpm i
78+
pnpm build
79+
80+
cd apps/core
81+
pm2 restart ecosystem.config.cjs
82+
```
83+
84+
### 验证
85+
86+
向新路由前缀发一个最简单的 GET 请求：
87+
88+
```bash
89+
curl -s http://localhost:2333/api/v3/aggregate | head -c 200
90+
```
91+
92+
应返回形如 `{"data":{...},"meta":{...}}` 之 JSON。`/api/v2/*` 不再可用。
93+
94+
---
95+
96+
## 第二步：升级 mx-admin Dashboard
97+
98+
mx-core v13 的 `dashboard.version` 字段钉版 `8.0.0`。若你使用 mx-core 自动下载的 dashboard 资源，重启后会自动拉新版；若你自部署 admin，请手动同步：
99+
100+
```bash
101+
# Docker 自动下载 dashboard（默认）— 重启已生效，无须额外步骤
102+
# 如显式部署
103+
cd ~/mx-space/mx-admin
104+
git fetch origin --tags
105+
git checkout v8.0.0
106+
pnpm i && pnpm build
107+
# 把 apps/admin/dist 部署到原路径
108+
```
109+
110+
打开后台 `你的域名/proxy/qaqdmin`，确认登入正常、文章列表可见。
111+
112+
---
113+
114+
## 第三步：升级前端 / 接口消费者
115+
116+
前端调用 mx-core 的方式分两类，迁移路径不同。
117+
118+
### A 类：使用 `@mx-space/api-client`（含 Shiro / Yohaku 等官方主题）
119+
120+
升级到 **v5.x**，其内置 **legacy adapter** 会把 V3 envelope 反向还原为 V1 wire 形态（camelCase、扁平 meta、`currentPage`/`totalPage` 分页键），现有调用代码**无须改动**即可工作。
121+
122+
```bash
123+
pnpm add @mx-space/api-client@^5
124+
```
125+
126+
随后逐 endpoint 把读取处迁移到 V3 envelope：
127+
128+
```ts
129+
// 旧：res.pagination.total
130+
// 新：res.meta.pagination.total
131+
132+
// 旧：post.translation
133+
// 新：post.meta.translation
134+
135+
// 旧：post.enrichments
136+
// 新：post.meta.enrichments
137+
```
138+
139+
legacy adapter 是迁移桥梁，非终态。新代码请直读 V3 envelope。
140+
141+
### B 类：直接 HTTP / REST 调用
142+
143+
- 路由前缀全替：`/api/v2/*` → `/api/v3/*`
144+
- 分页：读 `meta.pagination`（含 `page`、`size`、`total`、`total_pages`）
145+
- 翻译/相关/插件元数据：读 `meta.translation` / `meta.related` / `meta.enrichments` / `meta.insights`
146+
- 字段名一律 snake_case：`createdAt` → `created_at`、`refId` → `ref_id`、`pinAt` → `pin_at` 等
147+
- 文章详情（post/page/note）固定返回 `meta.translation.is_translated` / `source_lang` / `available_translations`，**不再** 在未翻译时省略——若你之前以这些字段是否存在做判断，可以直接删该判断
148+
149+
---
150+
151+
## 升级 Checklist（完成后逐项验证）
152+
153+
- [ ] mx-core 日志显示 v13.x.x 已启动
154+
- [ ] `curl /api/v3/aggregate` 返回正常 JSON
155+
- [ ] `/api/v2/*` 返回 404（确认旧前缀已废）
156+
- [ ] 后台登入正常、文章列表加载
157+
- [ ] 前端首页正常加载（含分页、翻译、enrichments 渲染）
158+
- [ ] 新发一篇测试文章 → 列表能见 → 删除正常
159+
160+
---
161+
162+
## 如果失败，如何回滚
163+
164+
回滚之直，因为本次升级**不动数据**。
165+
166+
```bash
167+
# Docker
168+
cd ~/mx-space/core
169+
# 编辑 docker-compose.yml 把 image 钉回上一 v12 tag
170+
docker compose pull app
171+
docker compose up -d app
172+
173+
# 源码
174+
cd ~/mx-space/core
175+
git checkout v12.x.x
176+
pnpm i && pnpm build
177+
cd apps/core
178+
pm2 restart ecosystem.config.cjs
179+
```
180+
181+
mx-admin 同步回 v7.x。前端若已升 `@mx-space/api-client@5` 须降回 v4 配合 v12 mx-core，或保 v5 但回退 mx-core 之同事亦保留 legacy adapter 工作——legacy adapter 设计可兼两侧。
182+
183+
---
184+
185+
## 常见问题
186+
187+
### 我必须立刻迁前端代码到 V3 envelope 吗？
188+
189+
**否。** `@mx-space/api-client@5` 之 legacy adapter 把 V3 还原 V1 wire 形态。升级 api-client 后，凡走 client 的代码无须改。可逐端点渐进迁。
190+
191+
### 直调 REST 的第三方脚本怎么办？
192+
193+
须更两处：
194+
1. 路由前缀 `/api/v2` → `/api/v3`
195+
2. 读响应时按 V3 envelope（`data` + `meta`）与 snake_case 字段名
196+
197+
短期可在反向代理层加 path rewrite `/api/v2/* → /api/v3/*` 缓冲，但响应字段名变更无 wire-level 兼容层，必须改代码。
198+
199+
### 数据库需要迁移吗？
200+
201+
**否。** v13 与 v12 同 schema（PostgreSQL），无 migration。
202+
203+
### mx-admin 必须升 v8 吗？
204+
205+
**强烈建议。** mx-admin v8 与 mx-core v13 之 V3 envelope 同步开发，旧版 admin 调 V3 端点会失败。
206+
207+
### 为何把 API 前缀也改了？
208+
209+
V3 是真正的 wire-level breaking change（envelope 形态、字段命名、视图模式）。换前缀使得新旧版本可在同代理后共存，并让 client 升级期间走两条路。
210+
211+
---
212+
213+
## 还需要帮助？
214+
215+
- [GitHub Issues](https://github.com/mx-space/core/issues)
216+
- [v13 Release Notes](https://github.com/mx-space/core/releases/tag/v13.0.0)

0 commit comments

Comments
 (0)