docs: 部署手册改为平台部署,替换原文档站自身部署说明

原 /deploy/ 内容是文档站自身(VitePress/Node/nginx)的部署说明,
与用户所需的「IotLCM 平台部署手册」不符。

改为基于 iotlcm-public/iotlcm-deploy 部署仓的平台部署手册:
- 部署概览:部署构成、三步流程、端口规划、关键约束
- 环境准备:硬件分档、系统与 Docker 版本、镜像仓库、防火墙、可选外部依赖
- 配置说明:.env 必填 8 项与可选 4 项、10 份应用配置逐项说明
- 启动与验证:首次初始化流程、7 步验证清单、首次登录必做项
- 可选服务:运营商挡板 onelink-mock、飞书 bot、反向代理(含 HTTPS)
- 升级与备份:版本固定、升级回滚、备份与恢复、日志清理、监控指标
- 故障排查:启动/功能/性能/网络四类共 20 个问题

删除原 6 页(docker-nginx / path-prefix / static-hosting / local-dev /
offline / faq),侧边栏同步改为「部署手册 + 运维」两组。
This commit is contained in:
Dai0814
2026-10-28 14:00:58 +08:00
parent 22a177c569
commit e43640d0fe
14 changed files with 1150 additions and 893 deletions
-98
View File
@@ -1,98 +0,0 @@
---
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**。
:::