diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index a761e52..2a94e49 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -81,7 +81,25 @@ export default defineConfig({
           text: '部署手册',
           collapsed: false,
           items: [
-            { text: '部署手册', link: '/deploy/' },
+            { text: '部署概览', link: '/deploy/' },
+            { text: '路径前缀必读', link: '/deploy/path-prefix' },
+          ]
+        },
+        {
+          text: '部署方式',
+          collapsed: false,
+          items: [
+            { text: '推荐：Docker + nginx', link: '/deploy/docker-nginx' },
+            { text: '静态托管部署', link: '/deploy/static-hosting' },
+            { text: '内网与离线部署', link: '/deploy/offline' },
+          ]
+        },
+        {
+          text: '开发与排错',
+          collapsed: false,
+          items: [
+            { text: '本地开发与预览', link: '/deploy/local-dev' },
+            { text: '常见问题', link: '/deploy/faq' },
           ]
         },
       ],
diff --git a/docs/deploy/docker-nginx.md b/docs/deploy/docker-nginx.md
new file mode 100644
index 0000000..efa5f73
--- /dev/null
+++ b/docs/deploy/docker-nginx.md
@@ -0,0 +1,159 @@
+---
+title: Docker + nginx 部署
+description: 推荐环境部署方式：多阶段构建镜像 + nginx 托管
+outline: deep
+---
+
+# 推荐环境部署：Docker + nginx
+
+适用：生产环境、需要长期稳定运行、机器上不想装 Node。
+
+仓库自带多阶段 `Dockerfile`：Node 阶段执行 `vitepress build`，最终镜像只含 nginx 与静态产物，**不含 Node 和 `node_modules`**。
+
+## 构建镜像
+
+```bash
+SHA=$(git rev-parse --short HEAD)
+docker build -t iotlcm-docs:$SHA .
+```
+
+用 commit sha 做标签，便于追溯与回滚；不建议只用 `latest`。
+
+## 启动容器
+
+```bash
+docker run -d \
+  --name iotlcm-docs \
+  --restart unless-stopped \
+  -p 8019:80 \
+  iotlcm-docs:$SHA
+```
+
+## nginx 配置（关键）
+
+`docker/nginx.conf` 用 `alias` 把 `/docs/` 前缀剥掉：
+
+```nginx
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # 产物按 base=/docs/ 生成，资源引用形如 /docs/assets/xxx
+    location /docs/ {
+        alias /usr/share/nginx/html/;
+        try_files $uri $uri.html $uri/ $uri/index.html =404;
+    }
+
+    # 根路径跳到文档入口，避免访问 / 时白屏
+    location = / {
+        return 302 /docs/;
+    }
+
+    location / {
+        try_files $uri $uri.html $uri/ =404;
+    }
+}
+```
+
+`try_files` 里的 `$uri.html` 与 `$uri/index.html` 是必需的：配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀，需要服务器做内部映射。
+
+原理说明见 [路径前缀必读](./path-prefix)。
+
+## 部署后自检
+
+```bash
+# 1. 入口可访问（应返回 200）
+curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/
+
+# 2. 根路径应 302 到 /docs/
+curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/
+
+# 3. 静态资源不能 404（最容易出问题的一步）
+ASSET=$(curl -s http://127.0.0.1:8019/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
+curl -o /dev/null -s -w '%{http_code}\n' "http://127.0.0.1:8019$ASSET"
+
+# 4. 抽查正文页面
+curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/manual/web/
+```
+
+四项都返回 `200`（第 2 项返回 `302`）才算部署成功。
+
+## 通过外层反向代理对外
+
+生产常见做法：容器只监听 `127.0.0.1`，由外层 nginx 转发。
+
+```nginx
+upstream iotlcm_docs {
+    server 127.0.0.1:8019;
+}
+
+location = /docs {
+    return 301 /docs/;
+}
+
+location /docs/ {
+    proxy_pass http://iotlcm_docs;   # 末尾不要加斜杠
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+::: danger proxy_pass 末尾斜杠
+写成 `proxy_pass http://iotlcm_docs/;`（带末尾斜杠）会把 `/docs/` 前缀剥掉，转发到容器变成 `/`，导致资源全部 404 白屏。**必须不带末尾斜杠**。
+:::
+
+## docker compose
+
+`docker-compose.yml` 中镜像名是占位值，需替换为自己的仓库地址：
+
+```yaml
+services:
+  docs:
+    image: your-registry/iotlcm/iotlcm-docs:${TAG:-latest}
+    container_name: iotlcm-docs
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8019:80"
+    networks:
+      - iotlcm-network
+
+networks:
+  iotlcm-network:
+    external: true
+    name: iotlcm-network
+```
+
+compose 文件声明 `iotlcm-network` 为外部网络，若不存在需先创建：
+
+```bash
+docker network create iotlcm-network
+```
+
+启动：
+
+```bash
+TAG=$(git rev-parse --short HEAD) docker compose up -d
+```
+
+## 版本固定与升级
+
+开源仓按**固定版本**发布（无 git 历史，单次初始提交）。部署时请记录并锁定 commit：
+
+```bash
+SHA=$(git rev-parse HEAD)
+echo "部署基线: $SHA" >> deploy.log
+docker build -t iotlcm-docs:$SHA .
+```
+
+升级文档时，从上游选定基线重新发布后，按新 sha 重建镜像并滚动替换容器：
+
+```bash
+docker rm -f iotlcm-docs
+docker run -d --name iotlcm-docs --restart unless-stopped -p 8019:80 iotlcm-docs:$NEW_SHA
+```
diff --git a/docs/deploy/faq.md b/docs/deploy/faq.md
new file mode 100644
index 0000000..0c13102
--- /dev/null
+++ b/docs/deploy/faq.md
@@ -0,0 +1,177 @@
+---
+title: 常见问题
+description: 部署与构建过程中的故障排查
+outline: deep
+---
+
+# 常见问题
+
+## 部署类
+
+### 页面能打开但白屏、无样式
+
+**原因**：`/docs/` 路径前缀未剥离，资源全部 404。
+
+这是最常见的部署故障。`base: '/docs/'` 使 HTML 引用 `/docs/assets/*`，但产物是平铺的，服务器从根路径找 `/assets/*` 就 404。
+
+**危险之处**：`curl /` 返回 200，看起来部署成功，实际浏览器是空白。
+
+**处理**：见 [路径前缀必读](./path-prefix)，三种做法任选其一。
+
+### 访问 `/` 返回 404
+
+**原因**：`base: '/docs/'`，站点根路径不是入口。
+
+**处理**：访问 `/docs/`。若希望 `/` 自动跳转，加：
+
+```nginx
+location = / { return 302 /docs/; }
+```
+
+### 访问 `/docs`（无末尾斜杠）404
+
+**原因**：未配置重定向，而 VitePress 生成的目录结构需要末尾斜杠。
+
+**处理**：
+
+```nginx
+location = /docs { return 301 /docs/; }
+```
+
+### 首页正常，点进任何内页都 404
+
+**原因**：`cleanUrls: true` 使页面 URL 不带 `.html`，服务器缺少内部映射。
+
+**处理**：`try_files` 补上两种映射：
+
+```nginx
+try_files $uri $uri.html $uri/ $uri/index.html =404;
+```
+
+### 反向代理后白屏
+
+**原因**：`proxy_pass` 带了末尾斜杠，把 `/docs/` 前缀剥掉后转发成 `/`。
+
+**处理**：去掉末尾斜杠：
+
+```nginx
+# 错误
+proxy_pass http://iotlcm_docs/;
+# 正确
+proxy_pass http://iotlcm_docs;
+```
+
+### 图片全部 404
+
+**原因**：图片放在 `docs/public/images/`，构建后映射到产物根的 `images/`，引用时需要用站点绝对路径（含 base）。
+
+**处理**：正文写 `/images/xxx.png`（VitePress 会自动补 `base`）。若写相对路径 `./images/xxx.png` 会因页面层级不同而失效。
+
+## 构建类
+
+### `npm ci` 报 lock 文件不一致
+
+**原因**：Node 版本过低，或 lock 与 `package.json` 不同步。
+
+**处理**：
+
+1. 升级到 Node 22：
+
+   ```bash
+   node -v   # 确认 >= 18，推荐 22
+   ```
+
+2. 若仍失败，改用 `npm install`（会更新 lock，注意提交变更）：
+
+   ```bash
+   npm install
+   ```
+
+### 构建报内存不足
+
+**原因**：构建峰值约 500 MB，容器内存限制过小时 OOM。
+
+**处理**：给到 ≥ 1 GB：
+
+```bash
+docker run -m 1g ...
+```
+
+或临时提高 Node 堆上限：
+
+```bash
+NODE_OPTIONS=--max-old-space-size=2048 npm run build
+```
+
+### 构建成功但页面内容缺失
+
+**原因**：`.md` 文件未保存、或文件不在 `docs/`（`srcDir`）目录下。
+
+**处理**：确认文件路径在 `docs/` 下，且已在 `.vitepress/config.mts` 的 sidebar 注册。
+
+### 新增页面左侧目录不显示
+
+**原因**：只在 `docs/` 下建了文件，没在 `sidebar` 配置里注册。
+
+**处理**：见 [本地开发与预览](./local-dev) 的「新增页面的步骤」。
+
+### 中文搜索失效或搜不到新页面
+
+**原因**：本地搜索索引在构建时生成，dev 模式下可能有延迟；产物未重新构建。
+
+**处理**：重新 `npm run build`。
+
+## 运行类
+
+### 端口 5173 被占用
+
+**处理**：
+
+```bash
+npx vitepress dev . --port 5174
+```
+
+或结束旧进程：
+
+```bash
+lsof -ti:5173 | xargs kill
+```
+
+### 局域网其他机器访问不了 dev 服务
+
+**原因**：默认只监听 `127.0.0.1`。
+
+**处理**：
+
+```bash
+npx vitepress dev . --host 0.0.0.0
+```
+
+并确认防火墙放行对应端口。
+
+### 修改 `.md` 后页面没更新
+
+**原因**：浏览器缓存，或 dev 进程已退出。
+
+**处理**：硬刷新（`Ctrl+Shift+R`），确认终端里 dev 进程仍在运行。
+
+## 快速自检清单
+
+部署完成后依次确认：
+
+```bash
+# 1. 入口 200
+curl -o /dev/null -s -w '%{http_code}\n' http://<host>/docs/
+
+# 2. 根路径 302（若配置了重定向）
+curl -o /dev/null -s -w '%{http_code}\n' http://<host>/
+
+# 3. 静态资源 200（最关键）
+ASSET=$(curl -s http://<host>/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
+curl -o /dev/null -s -w '%{http_code}\n' "http://<host>$ASSET"
+
+# 4. 内页 200
+curl -o /dev/null -s -w '%{http_code}\n' http://<host>/docs/manual/web/
+```
+
+四项都正常才算部署成功。浏览器再打开一次确认没有白屏。
diff --git a/docs/deploy/index.md b/docs/deploy/index.md
index eb10bee..fb3539a 100644
--- a/docs/deploy/index.md
+++ b/docs/deploy/index.md
@@ -1,17 +1,27 @@
 ---
-title: 部署手册
-description: iotLCM 文档站的推荐环境、编译方法与部署方式
+title: 部署概览
+description: iotLCM 文档站的部署方式总览与环境要求
 outline: deep
 ---
 
-# 部署手册
+# 部署概览
 
-本页说明 iotLCM 文档站（`iotlcm-docs`）的运行环境要求、编译方法与部署方式。文档站是**纯静态站点**，由 VitePress 1.6 构建，产物不含任何服务端运行时。
+本手册说明 iotLCM 文档站（`iotlcm-docs`）的环境要求、编译方法与部署方式。文档站是**纯静态站点**，由 VitePress 1.6 构建，产物不含任何服务端运行时。
 
 ::: tip 一句话结论
-生产推荐用 **Docker + nginx**（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 **Node 构建 + 任意 Web 服务器托管静态产物**。
+生产推荐 **Docker + nginx**（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 **Node 构建 + 任意 Web 服务器托管静态产物**。
 :::
 
+## 怎么选部署方式
+
+| 你的情况 | 看哪页 |
+| --- | --- |
+| 生产环境，机器上不想装 Node | [推荐环境部署：Docker + nginx](./docker-nginx) |
+| 有现成 nginx，只需托管静态文件 | [静态托管部署](./static-hosting) |
+| 内网 / 无法访问公网 npm | [内网与离线部署](./offline) |
+| 只是改文档、本地看效果 | [本地开发与预览](./local-dev) |
+| 遇到报错或白屏 | [常见问题](./faq) |
+
 ## 环境要求
 
 ### 构建环境（必需）
@@ -35,7 +45,9 @@ outline: deep
 | 容器运行时 | Docker 20+ / Docker Compose v2 | 仅容器方式需要 |
 | 资源占用 | 内存 32 MB、磁盘 30 MB | 纯静态，压力极低 |
 
-### 实测参考（Debian/Ubuntu + Node 22 + Docker 29）
+### 实测参考
+
+在 Debian/Ubuntu + Node 22 + Docker 29 上实测：
 
 | 操作 | 耗时 | 产物 |
 | --- | --- | --- |
@@ -52,392 +64,19 @@ git clone https://git.5iot.com/iotlcm-public/iotlcm-docs.git
 cd iotlcm-docs
 ```
 
-开源仓**不含 git 历史**，只有一个初始提交，这是预期行为：
+开源仓**不含 git 历史**，从初始提交开始累积：
 
 ```bash
 git log --oneline
-# 92f239f chore: 初始开源发布
 ```
 
-## ⚠️ 部署前必读：路径前缀
-
-这是本项目最容易出错的地方，**部署失败九成是这个原因**。
-
-文档站配置里 `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 → **浏览器白屏，没有任何报错提示**。
-:::
-
-三种正确做法，任选其一：
-
-| 做法 | 适用 | 关键配置 |
-| --- | --- | --- |
-| nginx `alias` 剥前缀 | 容器部署（推荐） | `location /docs/ { alias /usr/share/nginx/html/; }` |
-| 把产物放进 `docs/` 子目录 | 静态托管 / 对象存储 | `dist/` → `www/docs/` |
-| 改 `base: '/'` 重新构建 | 独占域名根路径 | 改配置后必须重新 `npm run build` |
-
----
-
-## 推荐环境部署：Docker + nginx
-
-适用：生产环境、需要长期稳定运行、机器上不想装 Node。
-
-仓库自带多阶段 `Dockerfile`：Node 阶段执行 `vitepress build`，最终镜像只含 nginx 与静态产物，**不含 Node 和 `node_modules`**。
-
-### 构建镜像
-
-```bash
-SHA=$(git rev-parse --short HEAD)
-docker build -t iotlcm-docs:$SHA .
-```
-
-用 commit sha 做标签，便于追溯与回滚；不建议只用 `latest`。
-
-### 启动容器
-
-```bash
-docker run -d \
-  --name iotlcm-docs \
-  --restart unless-stopped \
-  -p 8019:80 \
-  iotlcm-docs:$SHA
-```
-
-### nginx 配置（关键）
-
-`docker/nginx.conf` 用 `alias` 把 `/docs/` 前缀剥掉：
-
-```nginx
-server {
-    listen 80;
-    server_name _;
-
-    root /usr/share/nginx/html;
-    index index.html;
-
-    # 产物按 base=/docs/ 生成，资源引用形如 /docs/assets/xxx
-    location /docs/ {
-        alias /usr/share/nginx/html/;
-        try_files $uri $uri.html $uri/ $uri/index.html =404;
-    }
-
-    # 根路径跳到文档入口，避免访问 / 时白屏
-    location = / {
-        return 302 /docs/;
-    }
-
-    location / {
-        try_files $uri $uri.html $uri/ =404;
-    }
-}
-```
-
-`try_files` 里的 `$uri.html` 与 `$uri/index.html` 是必需的：配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀，需要服务器做内部映射。
-
-### 部署后自检
-
-```bash
-# 1. 入口可访问（应返回 200）
-curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/
-
-# 2. 根路径应 302 到 /docs/
-curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/
-
-# 3. 静态资源不能 404（最容易出问题的一步）
-ASSET=$(curl -s http://127.0.0.1:8019/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
-curl -o /dev/null -s -w '%{http_code}\n' "http://127.0.0.1:8019$ASSET"
-
-# 4. 抽查正文页面
-curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/manual/web/
-```
-
-四项都返回 `200`（第 2 项返回 `302`）才算部署成功。
-
-### 通过外层反向代理对外
-
-生产常见做法：容器只监听 `127.0.0.1`，由外层 nginx 转发。
-
-```nginx
-upstream iotlcm_docs {
-    server 127.0.0.1:8019;
-}
-
-location = /docs {
-    return 301 /docs/;
-}
-
-location /docs/ {
-    proxy_pass http://iotlcm_docs;   # 末尾不要加斜杠
-    proxy_http_version 1.1;
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-}
-```
-
-::: danger proxy_pass 末尾斜杠
-写成 `proxy_pass http://iotlcm_docs/;`（带末尾斜杠）会把 `/docs/` 前缀剥掉，转发到容器变成 `/`，导致资源全部 404 白屏。**必须不带末尾斜杠**。
-:::
-
-### docker compose
-
-`docker-compose.yml` 中镜像名是占位值，需替换为自己的仓库地址：
-
-```yaml
-services:
-  docs:
-    image: your-registry/iotlcm/iotlcm-docs:${TAG:-latest}
-    container_name: iotlcm-docs
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:8019:80"
-    networks:
-      - iotlcm-network
-
-networks:
-  iotlcm-network:
-    external: true
-    name: iotlcm-network
-```
-
-compose 文件声明 `iotlcm-network` 为外部网络，若不存在需先创建：
-
-```bash
-docker network create iotlcm-network
-```
-
-启动：
-
-```bash
-TAG=$(git rev-parse --short HEAD) docker compose up -d
-```
-
----
-
-## 其他环境
-
-### 方式一：本地开发与预览（改文档时用）
-
-```bash
-npm ci
-npm run dev
-```
-
-访问 **`http://127.0.0.1:5173/docs/`**。
-
-::: warning 地址必须带 /docs/
-`base: '/docs/'` 决定了 dev 服务器入口也在子路径下，直接访问 `http://127.0.0.1:5173/` 会 404。
-:::
-
-改动 `docs/` 下任意 `.md` 文件会热更新，无需重启。
-
-需要让局域网内其他机器访问时，把监听地址改为 `0.0.0.0`：
-
-```bash
-npx vitepress dev . --host 0.0.0.0
-# 然后访问 http://<本机IP>:5173/docs/
-```
-
-端口被占用时换端口：
-
-```bash
-npx vitepress dev . --port 5174
-```
-
-### 方式二：构建静态产物 + 任意 Web 服务器
-
-这是**不使用 Docker** 时最通用的做法。
-
-#### 编译
-
-```bash
-npm ci
-npm run build
-# 产物在 .vitepress/dist
-```
-
-本地验证构建结果（不要用于生产）：
-
-```bash
-npm run preview
-# http://127.0.0.1:4173/docs/
-```
-
-#### 部署到 nginx（子路径挂载，推荐）
-
-把产物放到一个 `docs` 子目录，即可与 `base` 天然对齐，**无需 alias**：
-
-```bash
-sudo mkdir -p /var/www/iotlcm/www
-sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
-```
-
-```nginx
-server {
-    listen 80;
-    server_name _;
-    root /var/www/iotlcm/www;
-
-    location /docs/ {
-        try_files $uri $uri.html $uri/ $uri/index.html =404;
-    }
-
-    location = /docs {
-        return 301 /docs/;
-    }
-}
-```
-
-此处 `root` 指向父目录、产物在 `docs/` 子目录下，`/docs/assets/app.js` 会自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
-
-#### 部署到 nginx（根路径独占域名）
-
-若文档站独占一个域名、需要挂在 `/`，必须**改 `base` 后重新构建**：
-
-```bash
-sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
-npm run build
-```
-
-```nginx
-server {
-    listen 80;
-    server_name docs.example.com;
-    root /var/www/iotlcm-docs;
-    index index.html;
-
-    location / {
-        try_files $uri $uri.html $uri/ =404;
-    }
-}
-```
-
-::: danger 不要只改服务器配置
-`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。
-:::
-
-#### 部署到对象存储 / CDN
-
-产物是纯静态文件，可直接上传到 S3 / OSS / MinIO 等：
-
-```bash
-npm run build
-# 上传 .vitepress/dist 全部内容到桶内 docs/ 前缀下
-```
-
-要点：
-
-- 上传时保持 `/docs/` 前缀（或改 `base` 后重新构建）
-- 配置**默认首页**为 `docs/index.html`
-- 配置 **404 页面**为 `docs/404.html`（产物已自带）
-- `cleanUrls: true` 意味着页面 URL 不带 `.html`，需对象存储支持「无后缀映射到 .html」，否则需关闭 `cleanUrls` 重新构建
-
-### 方式三：内网 / 离线环境
-
-机器无法访问公网 npm 源时：
-
-**方案 A：使用内网镜像源**
-
-```bash
-npm ci --registry=https://your-internal-registry/
-```
-
-**方案 B：在有网机器构建后只拷产物**
-
-产物是纯静态文件，**不需要在目标机器上装 Node**：
-
-```bash
-# 有网机器
-npm ci && npm run build
-tar czf iotlcm-docs-dist.tar.gz -C .vitepress/dist .
-
-# 目标机器
-tar xzf iotlcm-docs-dist.tar.gz -C /var/www/iotlcm/www/docs
-```
-
-**方案 C：内网构建镜像**
-
-`Dockerfile` 里基础镜像来自 Docker Hub（`node:22-alpine`、`nginx:1.27-alpine`），内网环境需先同步到内部镜像仓库，然后修改 `Dockerfile` 的 `FROM`：
-
-```dockerfile
-FROM your-registry/library/node:22-alpine AS builder
-# ...
-FROM your-registry/library/nginx:1.27-alpine
-```
-
-::: tip 已内置国内 apk 源
-`Dockerfile` 的 builder 阶段已把 Alpine 源换成 `mirrors.aliyun.com`，无需额外处理。
-:::
-
-### 方式四：pnpm / yarn
-
-仓库同时提供 `package-lock.json` 与 `pnpm-lock.yaml`。使用 pnpm：
-
-```bash
-pnpm install --frozen-lockfile
-pnpm run build
-```
-
-npm 与 pnpm 二选一即可，**不要混用**（会产生不一致的 `node_modules`）。
-
----
-
 ## 环境对照表
 
-| 场景 | Node | Docker | 访问路径 | 关键动作 |
-| --- | --- | --- | --- | --- |
-| 本地改文档 | 必需 | 不需要 | `/docs/` | `npm run dev` |
-| 生产（推荐） | 仅构建阶段 | 必需 | `/docs/` | `docker build` + nginx alias |
-| 静态托管（子路径） | 仅构建阶段 | 不需要 | `/docs/` | 产物放 `docs/` 子目录 |
-| 静态托管（根路径） | 仅构建阶段 | 不需要 | `/` | 改 `base: '/'` 重新构建 |
-| 对象存储 / CDN | 仅构建阶段 | 不需要 | `/docs/` | 上传 + 配 404 与默认首页 |
-| 内网离线 | 可在别处构建 | 可选 | `/docs/` | 只拷产物或改 FROM |
-
-## 常见问题
-
-| 现象 | 原因 | 处理 |
-| --- | --- | --- |
-| 页面白屏、无样式 | `/docs/` 前缀未剥离，资源 404 | 用 `alias`，或产物放 `docs/` 子目录 |
-| 访问 `/` 404 | `base: '/docs/'` | 访问 `/docs/`；容器版已自动 302 |
-| 访问 `/docs`（无末尾斜杠）404 | 未配置重定向 | 加 `location = /docs { return 301 /docs/; }` |
-| 正文页 404、首页正常 | 缺 `$uri.html` 映射 | `try_files` 补 `$uri.html $uri/index.html` |
-| `npm ci` 报 lock 不一致 | Node 版本过低 | 升级到 Node 22 |
-| 构建报内存不足 | 容器内存限制过小 | 给到 ≥ 1 GB |
-| 端口 5173 被占用 | 已有 dev 进程在跑 | `--port 5174` 或结束旧进程 |
-| 反向代理后白屏 | `proxy_pass` 带了末尾斜杠 | 去掉末尾斜杠 |
-
-## 版本固定
-
-开源仓按**固定版本**发布（无 git 历史，单次初始提交）。部署时请记录并锁定 commit：
-
-```bash
-SHA=$(git rev-parse HEAD)
-echo "部署基线: $SHA" >> deploy.log
-docker build -t iotlcm-docs:$SHA .
-```
-
-升级文档时，从上游选定基线重新发布后，按新 sha 重建镜像并滚动替换容器：
-
-```bash
-docker rm -f iotlcm-docs
-docker run -d --name iotlcm-docs --restart unless-stopped -p 8019:80 iotlcm-docs:$NEW_SHA
-```
-
-## 相关文档
-
-- [使用手册](/manual/) —— Web 管理端与小程序端操作说明
-- [OpenAPI 接口文档](/openapi/) —— V3 接口鉴权与调用说明
+| 场景 | Node | Docker | 访问路径 | 关键动作 | 详细 |
+| --- | --- | --- | --- | --- | --- |
+| 本地改文档 | 必需 | 不需要 | `/docs/` | `npm run dev` | [本地开发](./local-dev) |
+| 生产（推荐） | 仅构建阶段 | 必需 | `/docs/` | `docker build` + nginx alias | [Docker 部署](./docker-nginx) |
+| 静态托管（子路径） | 仅构建阶段 | 不需要 | `/docs/` | 产物放 `docs/` 子目录 | [静态托管](./static-hosting) |
+| 静态托管（根路径） | 仅构建阶段 | 不需要 | `/` | 改 `base: '/'` 重新构建 | [静态托管](./static-hosting) |
+| 对象存储 / CDN | 仅构建阶段 | 不需要 | `/docs/` | 上传 + 配 404 与默认首页 | [静态托管](./static-hosting) |
+| 内网离线 | 可在别处构建 | 可选 | `/docs/` | 只拷产物或改 FROM | [内网与离线](./offline) |
diff --git a/docs/deploy/local-dev.md b/docs/deploy/local-dev.md
new file mode 100644
index 0000000..99b015f
--- /dev/null
+++ b/docs/deploy/local-dev.md
@@ -0,0 +1,125 @@
+---
+title: 本地开发与预览
+description: 改文档时用 dev 模式，热更新实时看效果
+outline: deep
+---
+
+# 本地开发与预览
+
+适用：修改文档内容、调整配置、本地看效果。
+
+## 启动开发服务器
+
+```bash
+npm ci
+npm run dev
+```
+
+访问 **`http://127.0.0.1:5173/docs/`**
+
+::: warning 地址必须带 /docs/
+`base: '/docs/'` 决定了 dev 服务器入口也在子路径下，直接访问 `http://127.0.0.1:5173/` 会 404。
+:::
+
+改动 `docs/` 下任意 `.md` 文件会**热更新**，无需重启。按 `Ctrl+C` 退出。
+
+## 局域网访问
+
+需要让同网段其他机器访问时，把监听地址改为 `0.0.0.0`：
+
+```bash
+npx vitepress dev . --host 0.0.0.0
+# 然后访问 http://<本机IP>:5173/docs/
+```
+
+## 端口冲突
+
+默认 5173，被占用时换端口：
+
+```bash
+npx vitepress dev . --port 5174
+```
+
+## 预览构建产物
+
+`dev` 模式是源码实时编译，与最终产物有细微差异（如资源路径、代码分割）。发布前建议跑一次真实构建：
+
+```bash
+npm run build     # 产物在 .vitepress/dist
+npm run preview   # http://127.0.0.1:4173/docs/
+```
+
+`preview` 只是本地起静态服务验证产物，**不要用于生产**。
+
+## 目录结构
+
+新增页面时按此结构放置：
+
+```text
+iotlcm-docs/
+├── docs/                  # 文档源（VitePress srcDir）
+│   ├── index.md           # 站点首页
+│   ├── manual/            # 使用手册
+│   │   ├── web/           # Web 管理端
+│   │   └── mini-program/  # 小程序端
+│   ├── openapi/           # OpenAPI 合同
+│   ├── deploy/            # 部署手册（本手册）
+│   └── public/            # 静态资源，映射到站点根路径
+│       └── images/        # 文档配图
+└── .vitepress/
+    ├── config.mts         # 站点配置（导航、侧边栏）
+    └── theme/             # 主题定制
+```
+
+## 新增页面的步骤
+
+1. 在 `docs/` 下对应目录新建 `xxx.md`，写 frontmatter：
+
+   ```markdown
+   ---
+   title: 页面标题
+   description: 页面描述
+   outline: deep
+   ---
+
+   # 页面标题
+   ```
+
+2. 在 `.vitepress/config.mts` 的 `sidebar` 中注册，否则左侧目录不会显示：
+
+   ```ts
+   sidebar: {
+     '/deploy/': [
+       {
+         text: '部署手册',
+         collapsed: false,
+         items: [
+           { text: '概览', link: '/deploy/' },
+           { text: '新页面', link: '/deploy/xxx' },
+         ]
+       },
+     ],
+   }
+   ```
+
+3. 图片放 `docs/public/images/`，正文用绝对路径引用（public 目录映射到站点根）：
+
+   ```markdown
+   ![说明](/images/xxx.png)
+   ```
+
+## 构建产物结构
+
+```text
+.vitepress/dist/
+├── index.html          # 首页
+├── 404.html            # 404 页
+├── favicon.png
+├── assets/             # JS / CSS / 字体（带 hash）
+├── images/             # 来自 docs/public/images
+├── manual/             # 各章节
+├── openapi/
+└── deploy/
+```
+
+注意产物是**平铺**的，没有 `docs/` 子目录——这正是部署时需要处理路径前缀的原因，见 [路径前缀必读](./path-prefix)。
diff --git a/docs/deploy/offline.md b/docs/deploy/offline.md
new file mode 100644
index 0000000..b01f7cf
--- /dev/null
+++ b/docs/deploy/offline.md
@@ -0,0 +1,98 @@
+---
+title: 内网与离线部署
+description: 无法访问公网 npm 时的构建与部署方案
+outline: deep
+---
+
+# 内网与离线部署
+
+适用：目标机器无法访问公网 npm 源或 Docker Hub。
+
+## 方案 A：使用内网镜像源
+
+机器能访问内网 npm 仓库时，直接指定 registry：
+
+```bash
+npm ci --registry=https://your-internal-registry/
+```
+
+长期使用可写入 `~/.npmrc`：
+
+```bash
+npm config set registry https://your-internal-registry/
+```
+
+## 方案 B：有网机器构建，只拷产物（最简单）
+
+产物是纯静态文件，**目标机器不需要装 Node**：
+
+```bash
+# 有网机器
+npm ci && npm run build
+tar czf iotlcm-docs-dist.tar.gz -C .vitepress/dist .
+
+# 目标机器
+tar xzf iotlcm-docs-dist.tar.gz -C /var/www/iotlcm/www/docs
+```
+
+注意 `docs` 子目录与 `base: '/docs/'` 的对应关系，详见 [静态托管部署](./static-hosting)。
+
+## 方案 C：内网构建镜像
+
+`Dockerfile` 里基础镜像来自 Docker Hub（`node:22-alpine`、`nginx:1.27-alpine`），内网环境需先同步到内部镜像仓库，然后修改 `Dockerfile` 的 `FROM`：
+
+```dockerfile
+FROM your-registry/library/node:22-alpine AS builder
+# ... 中间不变
+FROM your-registry/library/nginx:1.27-alpine
+```
+
+同步镜像：
+
+```bash
+# 在有外网的机器上
+docker pull node:22-alpine
+docker tag node:22-alpine your-registry/library/node:22-alpine
+docker push your-registry/library/node:22-alpine
+
+docker pull nginx:1.27-alpine
+docker tag nginx:1.27-alpine your-registry/library/nginx:1.27-alpine
+docker push your-registry/library/nginx:1.27-alpine
+```
+
+::: tip 已内置国内 apk 源
+`Dockerfile` 的 builder 阶段已把 Alpine 源换成 `mirrors.aliyun.com`，无需额外处理。
+:::
+
+## 方案 D：离线安装依赖
+
+既不能访问公网 npm、也没有内网 registry 时，可在有网机器打包 `node_modules`：
+
+```bash
+# 有网机器（与目标机器同架构、同 Node 大版本）
+npm ci
+tar czf iotlcm-docs-full.tar.gz \
+  --exclude=.git --exclude=.vitepress/cache --exclude=.vitepress/dist .
+
+# 目标机器
+tar xzf iotlcm-docs-full.tar.gz -C /opt/iotlcm-docs
+cd /opt/iotlcm-docs
+npm run build
+```
+
+::: warning 架构与版本必须一致
+`node_modules` 里可能含平台相关的二进制依赖，跨架构（如 x86 → ARM）或跨 Node 大版本会失败。跨架构场景请用方案 B 直接拷产物。
+:::
+
+## 方案对比
+
+| 方案 | 需要外网 | 目标机器需 Node | 适用场景 |
+| --- | --- | --- | --- |
+| A 内网 registry | 否（有内网源） | 是 | 有内网 npm 仓库 |
+| B 只拷产物 | 仅在构建机 | **否** | 最通用，推荐 |
+| C 内网镜像 | 仅在同步镜像时 | 否（用 Docker） | 容器化生产环境 |
+| D 打包 node_modules | 仅在构建机 | 是 | 需在目标机器改文档后构建 |
+
+::: tip 推荐优先级
+优先选 **B（只拷产物）**——最简单，目标机器零依赖。需要容器化则选 **C**。
+:::
diff --git a/docs/deploy/path-prefix.md b/docs/deploy/path-prefix.md
new file mode 100644
index 0000000..03c4a92
--- /dev/null
+++ b/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` 重新构建。
diff --git a/docs/deploy/static-hosting.md b/docs/deploy/static-hosting.md
new file mode 100644
index 0000000..a52fb1d
--- /dev/null
+++ b/docs/deploy/static-hosting.md
@@ -0,0 +1,159 @@
+---
+title: 静态托管部署
+description: 不使用 Docker 时，用 nginx / 对象存储 / CDN 托管静态产物
+outline: deep
+---
+
+# 静态托管部署
+
+适用：已有 nginx / Apache / Caddy，或使用对象存储 / CDN，不想引入 Docker。
+
+核心流程只有两步：**构建产物** → **托管静态文件**。
+
+## 编译产物
+
+```bash
+npm ci
+npm run build
+# 产物在 .vitepress/dist
+```
+
+本地验证构建结果（不要用于生产）：
+
+```bash
+npm run preview
+# http://127.0.0.1:4173/docs/
+```
+
+## nginx：子路径挂载（推荐）
+
+把产物放到一个 `docs` 子目录，即可与 `base` 天然对齐，**无需 alias**：
+
+```bash
+sudo mkdir -p /var/www/iotlcm/www
+sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
+```
+
+```nginx
+server {
+    listen 80;
+    server_name _;
+    root /var/www/iotlcm/www;
+
+    location /docs/ {
+        try_files $uri $uri.html $uri/ $uri/index.html =404;
+    }
+
+    location = /docs {
+        return 301 /docs/;
+    }
+}
+```
+
+此处 `root` 指向父目录、产物在 `docs/` 子目录下，`/docs/assets/app.js` 会自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
+
+## nginx：根路径独占域名
+
+若文档站独占一个域名、需要挂在 `/`，必须**改 `base` 后重新构建**：
+
+```bash
+sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
+npm run build
+```
+
+```nginx
+server {
+    listen 80;
+    server_name docs.example.com;
+    root /var/www/iotlcm-docs;
+    index index.html;
+
+    location / {
+        try_files $uri $uri.html $uri/ =404;
+    }
+}
+```
+
+::: danger 不要只改服务器配置
+`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。详见 [路径前缀必读](./path-prefix)。
+:::
+
+## Apache
+
+需要启用 `mod_rewrite`，用 `.htaccess` 做 cleanUrls 映射：
+
+```apache
+<IfModule mod_rewrite.c>
+    RewriteEngine On
+    RewriteBase /docs/
+
+    # 已存在的文件/目录直接返回
+    RewriteCond %{REQUEST_FILENAME} -f [OR]
+    RewriteCond %{REQUEST_FILENAME} -d
+    RewriteRule ^ - [L]
+
+    # 无后缀路径映射到 .html 或 index.html
+    RewriteCond %{REQUEST_FILENAME}.html -f
+    RewriteRule ^(.+)$ $1.html [L]
+
+    RewriteCond %{REQUEST_FILENAME}/index.html -f
+    RewriteRule ^(.+)$ $1/index.html [L]
+</IfModule>
+```
+
+产物目录放置方式与 nginx 子路径方案一致：`/var/www/html/docs/`。
+
+## Caddy
+
+Caddy 配置更简洁，`try_files` 语义与 nginx 类似：
+
+```caddyfile
+example.com {
+    handle_path /docs/* {
+        root * /var/www/iotlcm-docs
+        try_files {path} {path}.html {path}/index.html
+        file_server
+    }
+}
+```
+
+或产物放在子目录、不做前缀处理：
+
+```caddyfile
+example.com {
+    root * /var/www/iotlcm/www
+    try_files {path} {path}.html {path}/index.html
+    file_server
+}
+```
+
+## 对象存储 / CDN
+
+产物是纯静态文件，可直接上传到 S3 / OSS / MinIO 等：
+
+```bash
+npm run build
+# 上传 .vitepress/dist 全部内容到桶内 docs/ 前缀下
+```
+
+要点：
+
+- 上传时保持 `/docs/` 前缀（或改 `base` 后重新构建）
+- 配置**默认首页**为 `docs/index.html`
+- 配置 **404 页面**为 `docs/404.html`（产物已自带）
+- `cleanUrls: true` 意味着页面 URL 不带 `.html`，需对象存储支持「无后缀映射到 .html」，否则需关闭 `cleanUrls` 重新构建
+
+::: tip 关闭 cleanUrls
+若对象存储不支持无后缀映射，编辑 `.vitepress/config.mts` 把 `cleanUrls: true` 改为 `false`，重新构建后页面 URL 会带 `.html` 后缀。
+:::
+
+## pnpm / yarn
+
+仓库同时提供 `package-lock.json` 与 `pnpm-lock.yaml`。使用 pnpm：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+```
+
+npm 与 pnpm 二选一即可，**不要混用**（会产生不一致的 `node_modules`）。