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

原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页： - 概览（含选型指引与环境对照表） - 路径前缀必读（独立成页，最高频故障） - 推荐环境：Docker + nginx - 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm） - 内网与离线部署（4 种方案 + 对比表） - 本地开发与预览（含新增页面步骤） - 常见问题（部署/构建/运行三类 + 自检清单）侧边栏分为三组：部署手册 / 部署方式 / 开发与排错
2026-10-26 17:12:18 +08:00
parent 07ddaa9968
commit 22a177c569
8 changed files with 860 additions and 389 deletions
@@ -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`）。