Files

T

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

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

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

2026-10-26 17:12:18 +08:00

3.5 KiB

Raw Blame History

title, description, outline

title	description	outline
部署概览	iotLCM 文档站的部署方式总览与环境要求	deep

部署概览

本手册说明 iotLCM 文档站（iotlcm-docs）的环境要求、编译方法与部署方式。文档站是纯静态站点，由 VitePress 1.6 构建，产物不含任何服务端运行时。

::: tip 一句话结论生产推荐 Docker + nginx（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 Node 构建 + 任意 Web 服务器托管静态产物。 :::

怎么选部署方式

你的情况	看哪页
生产环境，机器上不想装 Node	推荐环境部署：Docker + nginx
有现成 nginx，只需托管静态文件	静态托管部署
内网 / 无法访问公网 npm	内网与离线部署
只是改文档、本地看效果	本地开发与预览
遇到报错或白屏	常见问题

环境要求

构建环境（必需）

项	推荐	最低	说明
Node.js	22 LTS	18	VitePress 依赖的 Vite 5 要求 `^18.0.0 \|\| >=20.0.0`
包管理器	npm 10（随 Node 22）	npm 9	仓库带 `package-lock.json`，用 `npm ci` 精确安装
内存	2 GB	1 GB	构建峰值约 500 MB
磁盘	2 GB 可用	1 GB	`node_modules` 约 103 MB，产物 25 MB
网络	可访问 npm 源	—	仓库 `.npmrc` 已指向 `registry.npmmirror.com`

运行环境（只需静态托管）

构建完成后不再需要 Node。运行侧只需要一个能提供静态文件的 Web 服务器（nginx / Apache / Caddy / 对象存储均可）。

项	推荐	说明
操作系统	Linux x86_64（Debian 12 / Ubuntu 22.04+）	任意系统均可，产物与平台无关
Web 服务器	nginx 1.27+	仓库自带 `docker/nginx.conf`
容器运行时	Docker 20+ / Docker Compose v2	仅容器方式需要
资源占用	内存 32 MB、磁盘 30 MB	纯静态，压力极低

实测参考

在 Debian/Ubuntu + Node 22 + Docker 29 上实测：

操作	耗时	产物
`git clone`	约 2 秒	单 commit
`npm ci`	约 12 秒	128 个包 / 103 MB
`npm run build`	约 4 秒	25 MB / 267 个文件
`docker build`（冷，含拉镜像）	约 2 分 18 秒	镜像 120 MB
`docker build`（热，镜像已缓存）	约 10 秒	镜像 120 MB

获取代码

git clone https://git.5iot.com/iotlcm-public/iotlcm-docs.git
cd iotlcm-docs

开源仓不含 git 历史，从初始提交开始累积：

git log --oneline

环境对照表

场景	Node	Docker	访问路径	关键动作	详细
本地改文档	必需	不需要	`/docs/`	`npm run dev`	本地开发
生产（推荐）	仅构建阶段	必需	`/docs/`	`docker build` + nginx alias	Docker 部署
静态托管（子路径）	仅构建阶段	不需要	`/docs/`	产物放 `docs/` 子目录	静态托管
静态托管（根路径）	仅构建阶段	不需要	`/`	改 `base: '/'` 重新构建	静态托管
对象存储 / CDN	仅构建阶段	不需要	`/docs/`	上传 + 配 404 与默认首页	静态托管
内网离线	可在别处构建	可选	`/docs/`	只拷产物或改 FROM	内网与离线

3.5 KiB Raw Blame History Unescape Escape