Dai0814
22a177c569
原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页： - 概览（含选型指引与环境对照表） - 路径前缀必读（独立成页，最高频故障） - 推荐环境：Docker + nginx - 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm） - 内网与离线部署（4 种方案 + 对比表） - 本地开发与预览（含新增页面步骤） - 常见问题（部署/构建/运行三类 + 自检清单） 侧边栏分为三组：部署手册 / 部署方式 / 开发与排错
83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
---
|
||
title: 部署概览
|
||
description: iotLCM 文档站的部署方式总览与环境要求
|
||
outline: deep
|
||
---
|
||
|
||
# 部署概览
|
||
|
||
本手册说明 iotLCM 文档站（`iotlcm-docs`）的环境要求、编译方法与部署方式。文档站是**纯静态站点**，由 VitePress 1.6 构建，产物不含任何服务端运行时。
|
||
|
||
::: tip 一句话结论
|
||
生产推荐 **Docker + nginx**（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 **Node 构建 + 任意 Web 服务器托管静态产物**。
|
||
:::
|
||
|
||
## 怎么选部署方式
|
||
|
||
| 你的情况 | 看哪页 |
|
||
| --- | --- |
|
||
| 生产环境，机器上不想装 Node | [推荐环境部署：Docker + nginx](./docker-nginx) |
|
||
| 有现成 nginx，只需托管静态文件 | [静态托管部署](./static-hosting) |
|
||
| 内网 / 无法访问公网 npm | [内网与离线部署](./offline) |
|
||
| 只是改文档、本地看效果 | [本地开发与预览](./local-dev) |
|
||
| 遇到报错或白屏 | [常见问题](./faq) |
|
||
|
||
## 环境要求
|
||
|
||
### 构建环境（必需）
|
||
|
||
| 项 | 推荐 | 最低 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| 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 |
|
||
|
||
## 获取代码
|
||
|
||
```bash
|
||
git clone https://git.5iot.com/iotlcm-public/iotlcm-docs.git
|
||
cd iotlcm-docs
|
||
```
|
||
|
||
开源仓**不含 git 历史**，从初始提交开始累积：
|
||
|
||
```bash
|
||
git log --oneline
|
||
```
|
||
|
||
## 环境对照表
|
||
|
||
| 场景 | 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) |
|