From 77f22e717e4de23310c217e2ef3ab034c55e4f12 Mon Sep 17 00:00:00 2001 From: Innei Date: Fri, 22 May 2026 23:40:06 +0800 Subject: [PATCH] =?UTF-8?q?docs(migrate):=20add=20v12=20=E2=86=92=20v13=20?= =?UTF-8?q?upgrade=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- content/docs/migrate/index.mdx | 7 + content/docs/migrate/meta.json | 1 + content/docs/migrate/v12-to-v13.mdx | 216 ++++++++++++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 content/docs/migrate/v12-to-v13.mdx diff --git a/content/docs/migrate/index.mdx b/content/docs/migrate/index.mdx index cea51e1..0b735ac 100644 --- a/content/docs/migrate/index.mdx +++ b/content/docs/migrate/index.mdx @@ -8,6 +8,13 @@ import { Card, Cards } from 'fumadocs-ui/components/card' import { ArrowUp, Globe } from 'lucide-react' + } + href={'/docs/migrate/v12-to-v13'} + title="v12 → v13 升级" + > + V3 API 响应契约切换、api-client v5 与 mx-admin v8 同步升级 + } href={'/docs/migrate/v11-to-v12'} diff --git a/content/docs/migrate/meta.json b/content/docs/migrate/meta.json index d104150..ec68f2f 100644 --- a/content/docs/migrate/meta.json +++ b/content/docs/migrate/meta.json @@ -4,6 +4,7 @@ "root": true, "pages": [ "index", + "v12-to-v13", "v11-to-v12", "from-wordpress" ] diff --git a/content/docs/migrate/v12-to-v13.mdx b/content/docs/migrate/v12-to-v13.mdx new file mode 100644 index 0000000..92e62a8 --- /dev/null +++ b/content/docs/migrate/v12-to-v13.mdx @@ -0,0 +1,216 @@ +--- +title: v12 升级到 v13 +description: 从 v12 升级到 v13 的指南，含 V3 API 响应契约切换、api-client v5 与 mx-admin v8 同步升级 +--- + +import { Callout } from 'fumadocs-ui/components/callout' +import { Card, Cards } from 'fumadocs-ui/components/card' +import { AlertTriangle, CheckCircle, Container, Pickaxe, RotateCcw } from 'lucide-react' + + +v13 是一次 **API 契约的 breaking change**：列表与详情端点改用 V3 响应封套 `{ data, meta }`，字段命名一律 snake_case，路由前缀由 `/api/v2/*` 改为 `/api/v3/*`。前端可经 `@mx-space/api-client@5` 之 legacy adapter 渐进迁移，无须一次改尽。 + +数据层、文章/评论/图片等数据本身**不会改动**，亦无须数据库迁移。仅是接口形态变了。 + + +## 升级前必读（2 分钟） + +### 这次升级会变什么？ + +- **路由前缀**：`/api/v2/*` → `/api/v3/*` +- **响应封套**：`{ ...resource }` 直平展 → `{ data, meta }`，资源字段进 `data`，平台元数据（pagination、translation、enrichments、related、insights）进 `meta` +- **字段命名**：mixedCase / camelCase 不再混用，统一 **snake_case** +- **named views**：列表端点用 `card` 视图（精简字段），详情端点用 `detail` 视图（全字段） +- **后台 dashboard**：mx-core v13 的 dashboard 钉版从 v7.4.0 升到 **v8.0.0**，自建用户须同步部署 mx-admin v8 + +### 什么不会变？ + +- 数据库 schema、文章/评论/图片/配置等数据**完全不变** +- 登录方式、密码、API Key、Better-Auth 会话不受影响 +- WebSocket / SSE 端点形态不变 +- 文件上传、备份机制不变 + +### 我需要停站多久？ + +| 场景 | 预估时间 | +|---|---| +| Docker 拉新镜像 + dashboard 升级 | 2–5 分钟 | +| 源码部署 `pnpm i + build` | 5–10 分钟 | + +无数据迁移步骤，停站窗口比 v11→v12 短得多。 + +--- + +## 升级 Checklist + +开始前请确认： + +- [ ] 当前版本是 **v12.x**（若仍在 v11，先依 [v11→v12 指南](/docs/migrate/v11-to-v12)） +- [ ] 准备好与 mx-core v13 配套的 **mx-admin v8.0.0** 部署 +- [ ] 直调 mx-core REST 的第三方脚本/工具已盘点（小程序、外部聚合等） + +--- + +## 第一步：升级 mx-core 服务端 + +### Docker 部署 + +```bash +cd ~/mx-space/core + +# 拉取 v13 镜像 +docker compose pull app + +# 重启业务进程（PostgreSQL/Redis 保持运行） +docker compose up -d app +``` + +确认日志中出现 `Mix Space v13.x.x started`。 + +### 源码 / PM2 部署 + +```bash +cd ~/mx-space/core + +git fetch origin --tags +git checkout v13.x.x # 或 master +pnpm i +pnpm build + +cd apps/core +pm2 restart ecosystem.config.cjs +``` + +### 验证 + +向新路由前缀发一个最简单的 GET 请求： + +```bash +curl -s http://localhost:2333/api/v3/aggregate | head -c 200 +``` + +应返回形如 `{"data":{...},"meta":{...}}` 之 JSON。`/api/v2/*` 不再可用。 + +--- + +## 第二步：升级 mx-admin Dashboard + +mx-core v13 的 `dashboard.version` 字段钉版 `8.0.0`。若你使用 mx-core 自动下载的 dashboard 资源，重启后会自动拉新版；若你自部署 admin，请手动同步： + +```bash +# Docker 自动下载 dashboard（默认）— 重启已生效，无须额外步骤 +# 如显式部署 +cd ~/mx-space/mx-admin +git fetch origin --tags +git checkout v8.0.0 +pnpm i && pnpm build +# 把 apps/admin/dist 部署到原路径 +``` + +打开后台 `你的域名/proxy/qaqdmin`，确认登入正常、文章列表可见。 + +--- + +## 第三步：升级前端 / 接口消费者 + +前端调用 mx-core 的方式分两类，迁移路径不同。 + +### A 类：使用 `@mx-space/api-client`（含 Shiro / Yohaku 等官方主题） + +升级到 **v5.x**，其内置 **legacy adapter** 会把 V3 envelope 反向还原为 V1 wire 形态（camelCase、扁平 meta、`currentPage`/`totalPage` 分页键），现有调用代码**无须改动**即可工作。 + +```bash +pnpm add @mx-space/api-client@^5 +``` + +随后逐 endpoint 把读取处迁移到 V3 envelope： + +```ts +// 旧：res.pagination.total +// 新：res.meta.pagination.total + +// 旧：post.translation +// 新：post.meta.translation + +// 旧：post.enrichments +// 新：post.meta.enrichments +``` + +legacy adapter 是迁移桥梁，非终态。新代码请直读 V3 envelope。 + +### B 类：直接 HTTP / REST 调用 + +- 路由前缀全替：`/api/v2/*` → `/api/v3/*` +- 分页：读 `meta.pagination`（含 `page`、`size`、`total`、`total_pages`） +- 翻译/相关/插件元数据：读 `meta.translation` / `meta.related` / `meta.enrichments` / `meta.insights` +- 字段名一律 snake_case：`createdAt` → `created_at`、`refId` → `ref_id`、`pinAt` → `pin_at` 等 +- 文章详情（post/page/note）固定返回 `meta.translation.is_translated` / `source_lang` / `available_translations`，**不再** 在未翻译时省略——若你之前以这些字段是否存在做判断，可以直接删该判断 + +--- + +## 升级 Checklist（完成后逐项验证） + +- [ ] mx-core 日志显示 v13.x.x 已启动 +- [ ] `curl /api/v3/aggregate` 返回正常 JSON +- [ ] `/api/v2/*` 返回 404（确认旧前缀已废） +- [ ] 后台登入正常、文章列表加载 +- [ ] 前端首页正常加载（含分页、翻译、enrichments 渲染） +- [ ] 新发一篇测试文章 → 列表能见 → 删除正常 + +--- + +## 如果失败，如何回滚 + +回滚之直，因为本次升级**不动数据**。 + +```bash +# Docker +cd ~/mx-space/core +# 编辑 docker-compose.yml 把 image 钉回上一 v12 tag +docker compose pull app +docker compose up -d app + +# 源码 +cd ~/mx-space/core +git checkout v12.x.x +pnpm i && pnpm build +cd apps/core +pm2 restart ecosystem.config.cjs +``` + +mx-admin 同步回 v7.x。前端若已升 `@mx-space/api-client@5` 须降回 v4 配合 v12 mx-core，或保 v5 但回退 mx-core 之同事亦保留 legacy adapter 工作——legacy adapter 设计可兼两侧。 + +--- + +## 常见问题 + +### 我必须立刻迁前端代码到 V3 envelope 吗？ + +**否。** `@mx-space/api-client@5` 之 legacy adapter 把 V3 还原 V1 wire 形态。升级 api-client 后，凡走 client 的代码无须改。可逐端点渐进迁。 + +### 直调 REST 的第三方脚本怎么办？ + +须更两处： +1. 路由前缀 `/api/v2` → `/api/v3` +2. 读响应时按 V3 envelope（`data` + `meta`）与 snake_case 字段名 + +短期可在反向代理层加 path rewrite `/api/v2/* → /api/v3/*` 缓冲，但响应字段名变更无 wire-level 兼容层，必须改代码。 + +### 数据库需要迁移吗？ + +**否。** v13 与 v12 同 schema（PostgreSQL），无 migration。 + +### mx-admin 必须升 v8 吗？ + +**强烈建议。** mx-admin v8 与 mx-core v13 之 V3 envelope 同步开发，旧版 admin 调 V3 端点会失败。 + +### 为何把 API 前缀也改了？ + +V3 是真正的 wire-level breaking change（envelope 形态、字段命名、视图模式）。换前缀使得新旧版本可在同代理后共存，并让 client 升级期间走两条路。 + +--- + +## 还需要帮助？ + +- [GitHub Issues](https://github.com/mx-space/core/issues) +- [v13 Release Notes](https://github.com/mx-space/core/releases/tag/v13.0.0)