---
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**。
:::