Files

T

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

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

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

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

2.9 KiB

Raw Blame History

title, description, outline

title	description	outline
内网与离线部署	无法访问公网 npm 时的构建与部署方案	deep

内网与离线部署

适用：目标机器无法访问公网 npm 源或 Docker Hub。

方案 A：使用内网镜像源

机器能访问内网 npm 仓库时，直接指定 registry：

npm ci --registry=https://your-internal-registry/

长期使用可写入 ~/.npmrc：

npm config set registry https://your-internal-registry/

方案 B：有网机器构建，只拷产物（最简单）

产物是纯静态文件，目标机器不需要装 Node：

# 有网机器
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/' 的对应关系，详见静态托管部署。

方案 C：内网构建镜像

Dockerfile 里基础镜像来自 Docker Hub（node:22-alpine、nginx:1.27-alpine），内网环境需先同步到内部镜像仓库，然后修改 Dockerfile 的 FROM：

FROM your-registry/library/node:22-alpine AS builder
# ... 中间不变
FROM your-registry/library/nginx:1.27-alpine

同步镜像：

# 在有外网的机器上
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：

# 有网机器（与目标机器同架构、同 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。 :::

2.9 KiB Raw Blame History Unescape Escape