docs: 部署手册拆分为多页，左侧形成三层目录

原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页：
- 概览（含选型指引与环境对照表）
- 路径前缀必读（独立成页，最高频故障）
- 推荐环境：Docker + nginx
- 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm）
- 内网与离线部署（4 种方案 + 对比表）
- 本地开发与预览（含新增页面步骤）
- 常见问题（部署/构建/运行三类 + 自检清单）

侧边栏分为三组：部署手册 / 部署方式 / 开发与排错

docs/deploy/path-prefix.md

@@ -0,0 +1,96 @@
+---
+title: 路径前缀必读
+description: base=/docs/ 导致的部署白屏问题与三种正确做法
+outline: deep
+---
+
+# 路径前缀必读
+
+这是本项目最容易出错的地方，**部署失败九成是这个原因**。部署前请务必读完本页。
+
+## 问题成因
+
+文档站配置里 `base: '/docs/'`（见 `.vitepress/config.mts`），因此构建产物中所有资源引用都是**绝对路径**：
+
+```html
+<link rel="stylesheet" href="/docs/assets/style.xxx.css">
+<script src="/docs/assets/app.xxx.js"></script>
+```
+
+而产物目录 `.vitepress/dist` 是**平铺**的，`index.html`、`assets/` 直接在根，**没有 `docs/` 子目录**。
+
+由此推出两条铁律：
+
+1. **对外访问路径必须是 `/docs/`**，且服务器必须把 `/docs/` 前缀剥掉后再落到产物目录
+2. 若想挂到别的前缀（如 `/manual/`），必须**先改 `base` 再重新构建**，不能只改服务器配置
+
+::: warning 典型故障：白屏
+如果配置成「从根路径直接服务产物」（`root` 指向 dist，访问 `/`），页面 HTML 会返回 200，但 `/docs/assets/*.js` 全部 404 → **浏览器白屏，没有任何报错提示**。
+
+这种情况最坑的地方是：`curl /` 返回 200，看起来部署成功了，实际打开浏览器是空白页。
+:::
+
+## 三种正确做法
+
+| 做法 | 适用 | 关键配置 |
+| --- | --- | --- |
+| nginx `alias` 剥前缀 | 容器部署（推荐） | `location /docs/ { alias /usr/share/nginx/html/; }` |
+| 把产物放进 `docs/` 子目录 | 静态托管 / 对象存储 | `dist/` → `www/docs/` |
+| 改 `base: '/'` 重新构建 | 独占域名根路径 | 改配置后必须重新 `npm run build` |
+
+### 做法一：nginx alias 剥前缀
+
+```nginx
+location /docs/ {
+    alias /usr/share/nginx/html/;
+    try_files $uri $uri.html $uri/ $uri/index.html =404;
+}
+```
+
+`alias` 会剥掉 `location` 的前缀，`/docs/assets/app.js` 实际读到 `/usr/share/nginx/html/assets/app.js`，正好对上平铺的产物目录。
+
+详见 [推荐环境部署：Docker + nginx](./docker-nginx)。
+
+### 做法二：产物放进 docs 子目录
+
+```bash
+sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
+```
+
+```nginx
+root /var/www/iotlcm/www;
+location /docs/ {
+    try_files $uri $uri.html $uri/ $uri/index.html =404;
+}
+```
+
+`/docs/assets/app.js` 自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
+
+详见 [静态托管部署](./static-hosting)。
+
+### 做法三：改 base 重新构建
+
+```bash
+sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
+npm run build
+```
+
+仅适用于文档站独占域名根路径的场景。
+
+::: danger 不要只改服务器配置
+`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。
+:::
+
+## cleanUrls 的额外要求
+
+配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀（如 `/manual/web/` 而非 `/manual/web.html`）。
+
+因此服务器的 `try_files` **必须**包含 `$uri.html` 与 `$uri/index.html` 映射：
+
+```nginx
+try_files $uri $uri.html $uri/ $uri/index.html =404;
+```
+
+缺了这两项的表现是：首页正常，但点进任何内页都是 404。
+
+对象存储场景下需确认支持「无后缀映射到 `.html`」，否则要关闭 `cleanUrls` 重新构建。