@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/zh/releases/v9.md

@@ -0,0 +1,342 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-29
+title: New Intlayer v9 - What's new?
+description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections and Variants.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - CMS SDK
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# New Intlayer v9 - What's new?
+
+Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections** and **Variants**.
+
+## Table of contents
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+Migrating to Intlayer from popular i18n libraries is now easier than ever. We have created five compat packages that expose the **exact same public APIs** as standard i18n libraries but delegate all translation work to Intlayer at runtime.
+
+### Expose Same Public API with Strict Typing
+
+By replacing imports, you get all the benefits of Intlayer (including compile-time type safety against your actual dictionaries) with minimal code changes:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/react-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+- `@intlayer/lingui`
+
+For example, simply change:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+to:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Your keys will now be **strictly typed** against your Intlayer dictionaries, offering full dot-path auto-completion in your IDE!
+
+### Bundler Alias Plugins (Vite, Next.js, Turbopack)
+
+To allow migrating without rewriting all your import statements manually, each compat adapter package includes a **custom bundler plugin** (Vite or Next.js) under the `/plugin` subpath.
+
+These plugins automatically rewrite existing imports (e.g. `react-i18next` or `next-intl`) to their `@intlayer/*` equivalents at build time.
+
+#### Next.js (Webpack / Turbopack) Example
+
+Instead of `withIntlayer`, wrap your Next.js configuration with the compat plugin:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Vite (React, Vue, Solid, Svelte) Example
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Mutualized Runtime Resolver
+
+All compat adapters now route translation resolution through a single, highly optimized runtime parser: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Resolves standard `{{var}}` (whitespace & dot-paths), ICU formatted args (`{v, number, percent}` etc.), and bare `{var}` templates.
+- **Message Node Resolver**: Resolves nested nodes: `insert()`, `plural()` (CLDR plural rules), `enu()` (enumeration), `gender()`, HTML tags, arrays, and callable function nodes.
+- **Tokenized Tag Parser**: Supports inline XML/HTML tags and numbered tags (e.g., `<1>children</1>`) to power rich-text rendering out of the box.
+
+---
+
+## Feature Spec: Collections & Variants
+
+Intlayer v9 expands beyond static key-value objects, allowing dictionaries to declare dynamic layout structures that are fully typed end-to-end.
+
+### 1. Collections
+
+Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists):
+
+```ts fileName="faq.1.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
+
+```ts fileName="faq.2.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
+} satisfies Dictionary;
+```
+
+#### Usage:
+
+```ts
+// Fetch all items as an array
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Deliver A/B tests, seasonal headers, feature flags, or custom landing pages:
+
+#### String variants (e.g. A/B testing)
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({ en: "Shop now", fr: "Acheter maintenant" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Usage:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+#### Object variants (e.g. Dynamic Records)
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  variant: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Usage:
+
+```ts
+// Fetches only the requested item dynamically (requires Suspense)
+const product = useIntlayer("product-copy", {
+  variant: { id: "prod_123", category: "books" },
+});
+```
+
+---
+
+## Dynamic Loading & Bundle Size Optimizations
+
+To keep bundles extremely small, Intlayer v9 supports dynamic lazy loading.
+
+In your configuration, set `importMode` to `'dynamic'` or `'fetch'`:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace `useIntlayer` / `getIntlayer` calls with tree-shakeable wrappers (`useDictionary` / `useDictionaryDynamic`). Only the content required for the selected collection item, variant, or locale is loaded, preventing your production bundle from containing unused translations.
+
+---
+
+## Vite Plugin: 捆绑编译器和代理
+
+`intlayer()` Vite 插件现在直接捆绑了**编译器**和**区域设置路由代理**，因此大多数项目只需在 `vite.config.ts` 中使用单个插件：
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: 当 `compiler.enabled` 被设置为 `true` 且配置了 `compiler.output` 路径时，自动激活。您不再需要单独注册 `intlayerCompiler()`。
+- **Proxy**: 根据新的 `routing.enableProxy` 选项自动激活（默认为 `true`）。它在开发、预览和生产 SSR 中连接区域设置检测 / 重定向 / 重写中间件。您不再需要单独注册 `intlayerProxy()`。
+
+### `routing.enableProxy` 选项
+
+新的 `routing.enableProxy` 选项控制是否启用区域语言路由代理。默认值为 `true`。当您想自己处理区域语言路由时，可以禁用它：
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // 默认值: true
+  },
+};
+
+export default config;
+```
+
+独立的 `intlayerCompiler()` 和 `intlayerProxy()` 插件仍然可用于高级设置。将它们与 `intlayer()` 一起注册是安全的 — 每个插件会自动去重并且仅运行一次。
+
+---
+
+## 默认禁用编译器
+
+从 Intlayer v9 开始，**编译器默认被禁用**（`compiler.enabled` 现在默认为 `false`）。要启用对 `.content.ts` 文件的构建时提取，请在配置中设置 `compiler.enabled: true`：
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // 默认值：false —— 自 v9 起启用编译器所必需
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+当编译器被禁用时，Intlayer 会跳过构建时提取步骤，并依赖您已声明的字典。仅当您希望打包器插件（`@intlayer/swc`、`@intlayer/babel` 或 `intlayer()` Vite 插件）自动提取内容时才启用它。
+
+---
+
+## React Native：单包导入
+
+在 React Native 或 Expo 应用中，您不再需要同时管理 `react-intlayer` 和 `react-native-intlayer`。`react-native-intlayer` 包现在**重新导出了完整的 `react-intlayer` API**（hooks、工具函数以及 `/format`、`/html` 和 `/markdown` 子路径），并且其 `IntlayerProvider` 会自动应用 React Native 的 polyfills。
+
+从单一的 `react-native-intlayer` 包中导入所有内容：
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> 从 `react-intlayer` 导入仍然有效，但现在推荐使用 `react-native-intlayer` 作为 React Native 的单一入口点 —— 它的 provider 提供了面向 web 的 `react-intlayer` provider 所不包含的 polyfills。
+
+---
+
+## CMS SDK：将 Intlayer 用作无头内容数据库
+
+Intlayer v9 在 `@intlayer/api` 中提供了一个简洁、自动鉴权的 SDK，用于以编程方式与 CMS 交互——获取项目、获取字典，以及从你自己的服务器、脚本或 CI 推送或更新它们。鉴权（OAuth2 `client_credentials`）会自动处理并刷新。
+
+SDK 拆分为**两个独立的导入**，因此你的打包产物只包含你实际使用的领域：
+
+1. `createIntlayerCMS` —— 一个轻量的**鉴权器**，持有凭据和受管理的令牌（不打包任何领域客户端）。
+2. `dictionaryEndpoint`、`projectEndpoint`、… —— 按领域划分的**端点绑定器**，各自从其独立子路径导入。
+
+```ts fileName="cms.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+// 配置是可选的：凭据会回退到 INTLAYER_CLIENT_ID /
+// INTLAYER_CLIENT_SECRET（由 `@intlayer/config/built` 解析）。
+const cms = createIntlayerCMS();
+
+// 读取
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+
+// 写入 —— 像数据库一样使用 CMS
+await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
+```
+
+> 安全：CMS 凭据授予对内容的写入权限。务必只在**服务端**创建鉴权器——切勿将 `clientId` / `clientSecret` 发送到浏览器。
+
+---
+
+## Migration notes from v8
+
+If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
+
+- **默认禁用编译器**：`compiler.enabled` 现在默认为 `false`。如果您依赖对 `.content.ts` 文件的构建时提取，请在 `intlayer.config.ts` 中设置 `compiler.enabled: true`。
+- **Locales & Dialects**: If using external i18n dependencies, add their respective compat adapter plugins in your configuration or bundler setup to automatically rewrite imports.
+- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+
+---
+
+## Useful links
+
+- [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [CMS SDK - 通过 @intlayer/api 进行编程访问](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)

package/docs/zh/roadmap.md

@@ -29,6 +29,12 @@ Intlayer 是一个内容管理和国际化解决方案，旨在简化您在应
 
 ---
 
+## 目录
+
+<TOC/>
+
+---
+
 ## 当前功能
 
 ### 1. 内容声明

package/docs/zh/self_hosting.md

@@ -0,0 +1,349 @@
+---
+createdAt: 2026-06-30
+updatedAt: 2026-06-30
+title: 自托管 Intlayer
+description: 通过一条命令在您自己的基础设施上运行完整的 Intlayer 实例。无需 Intlayer Cloud 账户。
+keywords:
+  - 自托管
+  - Docker
+  - Docker Compose
+  - Intlayer
+  - CMS
+  - 安装
+  - 基础设施
+slugs:
+  - doc
+  - self-hosting
+author: aymericzip
+---
+
+# 自托管 Intlayer
+
+Intlayer 可以完全在您自己的基础设施上运行——无需 Intlayer Cloud 账户。只需一条命令即可启动一个生产就绪的堆栈：
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+安装程序会下载 `docker-compose.yml` 和 `.env` 文件，自动生成所需的密钥，并使用 `docker compose up -d` 启动所有容器。
+
+## 目录
+
+<TOC/>
+
+---
+
+## 架构
+
+```
+                ┌─────────────────────────────┐
+ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
+                └─────────────────────────────┘   │ VITE_BACKEND_URL
+                ┌─────────────────────────────┐   │
+                │  backend (Fastify/Bun)  :3100│ ◀─┘
+                └──────────────┬──────────────┘
+          ┌──────────┬─────────┼──────────┬───────────┐
+          ▼          ▼         ▼          ▼           ▼
+     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium
+     (1-node RS)             (S3 API)     (SMTP)        (in-image)
+                             minio:9001   mailpit:8025
+                             (console)    (web UI)
+```
+
+Chromium（用于 Puppeteer 屏幕截图生成）捆绑在后端镜像中——无需单独的容器。
+
+---
+
+## 先决条件
+
+- **Docker** ≥ 24 和 **Docker Compose** ≥ v2。如果其中任何一个缺失，安装程序将打印安装链接并退出。
+- 主机上端口 `3000`、`3100`、`8025`、`9000` 和 `9001` 可用。
+- Linux 或 macOS 主机（或 Windows 上的 WSL2）。
+
+---
+
+## 快速开始
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+安装程序执行以下操作：
+
+1. 检查 `docker` 和 `docker compose` 是否存在。
+2. 将 `docker-compose.yml` 和 `.env.example` 下载到 `./intlayer/` 目录中。
+3. 如果不存在 `.env` 文件，则复制示例文件并使用 `openssl rand` 为 `BETTER_AUTH_SECRET`、`S3_ACCESS_KEY_ID` 和 `S3_SECRET_ACCESS_KEY` 生成随机密钥。
+4. 运行 `docker compose pull` + `docker compose up -d`。
+5. 打印 URL：仪表盘 `:3000`、API `:3100`、电子邮件 UI `:8025`、MinIO 控制台 `:9001`。
+
+堆栈启动后，打开 **http://localhost:3000** 并创建您的第一个账户。
+
+---
+
+## 服务
+
+| 服务        | 镜像                              | 主机端口                       | 用途                               |
+| ----------- | --------------------------------- | ------------------------------ | ---------------------------------- |
+| **app**     | 从 `apps/app/Dockerfile` 构建     | `3000`                         | TanStack Start 仪表盘 (CMS UI)     |
+| **backend** | 从 `apps/backend/Dockerfile` 构建 | `3100`                         | Fastify REST API (`/health` 端点)  |
+| **mongo**   | `mongo:7`                         | 内部                           | 单节点副本集 (`rs0`)               |
+| **redis**   | `redis:7-alpine`                  | 内部                           | 任务队列 (BullMQ) 和缓存 (ioredis) |
+| **minio**   | `minio/minio`                     | `9000` (S3), `9001` (控制台)   | 用于头像和截图的 S3 兼容对象存储   |
+| **mailpit** | `axllent/mailpit`                 | `1025` (SMTP), `8025` (Web UI) | 本地事务性电子邮件接收器           |
+
+默认情况下，内部端口（mongo、redis）不会暴露给主机。
+
+> MinIO 端口 `9000` 必须可从浏览器访问，因为上传的资产（头像、截图）直接从 `S3_PUBLIC_URL=http://localhost:9000/intlayer` 加载。
+
+---
+
+## 环境变量
+
+安装程序会生成一个即用型 `.env` 文件。下表描述了每个变量。
+
+### 必需（自动生成或提示）
+
+| 变量                   | 示例                                            | 描述                             |
+| ---------------------- | ----------------------------------------------- | -------------------------------- |
+| `NODE_ENV`             | `production`                                    | 运行时环境                       |
+| `PORT`                 | `3100`                                          | 后端监听端口                     |
+| `BACKEND_URL`          | `http://localhost:3100`                         | 后端 API 的公共 URL              |
+| `APP_URL`              | `http://localhost:3000`                         | 仪表盘的公共 URL                 |
+| `DOMAIN`               | `localhost`                                     | Cookie 域                        |
+| `MONGODB_URI`          | `mongodb://mongo:27017/intlayer?replicaSet=rs0` | 完整的 MongoDB 连接 URI          |
+| `REDIS_URL`            | `redis://redis:6379`                            | Redis 连接 URL                   |
+| `BETTER_AUTH_SECRET`   | _(已生成)_                                      | 用于会话签名的 32 字节密钥       |
+| `MAIL_PROVIDER`        | `smtp`                                          | 邮件传输方式：`smtp` 或 `resend` |
+| `MAIL_SMTP_HOST`       | `mailpit`                                       | SMTP 主机名 (Mailpit 容器名称)   |
+| `MAIL_SMTP_PORT`       | `1025`                                          | SMTP 端口                        |
+| `MAIL_FROM`            | `Intlayer <no-reply@localhost>`                 | 发件人地址                       |
+| `S3_ENDPOINT`          | `http://minio:9000`                             | S3 兼容端点                      |
+| `S3_PUBLIC_URL`        | `http://localhost:9000/intlayer`                | 用于浏览器资产加载的公共 URL     |
+| `S3_BUCKET_NAME`       | `intlayer`                                      | 存储桶名称                       |
+| `S3_ACCESS_KEY_ID`     | _(已生成)_                                      | MinIO 访问密钥                   |
+| `S3_SECRET_ACCESS_KEY` | _(已生成)_                                      | MinIO 秘密密钥                   |
+| `VITE_BACKEND_URL`     | `http://localhost:3100`                         | 构建时嵌入到仪表盘中的后端 URL   |
+| `VITE_DOMAIN`          | `localhost`                                     | 构建时嵌入到仪表盘中的域         |
+
+### 可选（缺少时功能会优雅降级）
+
+| 变量                                                     | 功能                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------ |
+| `OPENAI_API_KEY`                                         | AI 辅助翻译和内容审计                                  |
+| `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_*` | 账单和订阅管理                                         |
+| `RESEND_API_KEY`                                         | 通过 Resend 发送事务性电子邮件（设置后会覆盖 Mailpit） |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`               | GitHub OAuth 登录                                      |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`               | Google OAuth 登录                                      |
+| `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`               | GitLab OAuth 登录                                      |
+| `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`         | Microsoft OAuth 登录                                   |
+| `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`           | LinkedIn OAuth 登录                                    |
+| `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`         | Atlassian OAuth 登录                                   |
+
+---
+
+## 连接您的 Intlayer 项目
+
+堆栈运行后，将您的项目指向自托管的后端和仪表盘，而不是 `intlayer.org`。
+
+### 项目配置
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * 自托管 CMS 仪表盘的 URL。
+     * 默认值: https://app.intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000
+
+    /**
+     * 自托管后端 API 的 URL。
+     * 默认值: https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
+  },
+};
+
+export default config;
+```
+
+在您项目的 `.env` 中设置环境变量：
+
+```sh
+INTLAYER_CMS_URL=http://localhost:3000
+INTLAYER_BACKEND_URL=http://localhost:3100
+INTLAYER_CLIENT_ID=<your-client-id>
+INTLAYER_CLIENT_SECRET=<your-client-secret>
+```
+
+在您的自托管仪表盘中，通过 `http://localhost:3000/projects` 下的 **项目 → 访问密钥** 创建访问凭据。
+
+### `@intlayer/api` SDK
+
+以编程方式使用 `@intlayer/api` SDK 时，明确传递 `backendURL`：
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
+  },
+});
+
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+```
+
+---
+
+## 升级
+
+在现有部署上重新运行安装程序会执行滚动升级：
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+这会拉取最新镜像并使用 `docker compose pull && docker compose up -d` 重启容器。现有卷（`mongo-data`、`redis-data`、`minio-data`）会保留——不会丢失数据。
+
+要在 `./intlayer/` 目录中手动升级：
+
+```sh
+docker compose pull
+docker compose up -d
+```
+
+---
+
+## 备份与恢复
+
+所有持久化数据都存储在三个命名 Docker 卷中。
+
+### 备份
+
+```sh
+docker run --rm \
+  -v intlayer_mongo-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/mongo-data.tar.gz /data
+
+docker run --rm \
+  -v intlayer_redis-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/redis-data.tar.gz /data
+
+docker run --rm \
+  -v intlayer_minio-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/minio-data.tar.gz /data
+```
+
+### 恢复
+
+```sh
+docker run --rm \
+  -v intlayer_mongo-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar xzf /backup/mongo-data.tar.gz -C /
+
+# 对 redis-data 和 minio-data 重复此操作
+```
+
+---
+
+## 使用反向代理 (Nginx / Caddy)
+
+对于生产部署，请在应用和后端容器前放置一个反向代理，而不是直接暴露它们。
+
+### Nginx 示例
+
+```nginx
+server {
+    listen 80;
+    server_name cms.example.com;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+
+server {
+    listen 80;
+    server_name api.example.com;
+
+    location / {
+        proxy_pass http://localhost:3100;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+更新以下 `.env` 变量以匹配您的公共域名：
+
+```sh
+BACKEND_URL=https://api.example.com
+APP_URL=https://cms.example.com
+DOMAIN=example.com
+VITE_BACKEND_URL=https://api.example.com
+VITE_DOMAIN=example.com
+```
+
+> `VITE_*` 变量在构建时被嵌入到仪表盘镜像中。如果在镜像构建后更改它们，您需要重建 `app` 镜像 (`docker compose build app`) 或使用运行时配置注入。
+
+---
+
+## 故障排除
+
+### 后端首次启动时崩溃循环
+
+MongoDB 和 Redis 必须在后端启动前保持健康。compose 文件使用带有 `condition: service_healthy` 的 `depends_on`。如果您看到后端重复重启，请检查 `mongo` 和 `redis` 的健康检查是否通过：
+
+```sh
+docker compose ps
+docker compose logs mongo
+docker compose logs redis
+```
+
+### 仪表盘无法连接到 API
+
+验证 `VITE_BACKEND_URL` 是否与后端可以从**浏览器**（而非 Docker 网络）访问的 URL 匹配。如果您更改了后端端口或添加了反向代理，请重建仪表盘镜像：
+
+```sh
+docker compose build app
+docker compose up -d app
+```
+
+### 电子邮件未发送
+
+默认情况下，所有出站电子邮件都会被 Mailpit 捕获。打开 `http://localhost:8025` 查看已发送的消息。要发送真实电子邮件，请在 `.env` 中设置 `MAIL_PROVIDER=resend` 和 `RESEND_API_KEY=<your-key>`，然后重启后端：
+
+```sh
+docker compose restart backend
+```
+
+### MinIO 存储桶缺失
+
+如果 `minio-init` 一次性服务未运行（或在 MinIO 准备好之前运行），请手动创建存储桶：
+
+```sh
+docker compose run --rm minio-init
+```
+
+---
+
+## 有用链接
+
+- [Intlayer CMS 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)
+- [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)