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