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
+75
-66
@@ -1,82 +1,91 @@
|
||||
---
|
||||
title: 部署概览
|
||||
description: iotLCM 文档站的部署方式总览与环境要求
|
||||
description: IotLCM 平台的部署方式、构成与前置条件
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 部署概览
|
||||
|
||||
本手册说明 iotLCM 文档站（`iotlcm-docs`）的环境要求、编译方法与部署方式。文档站是**纯静态站点**，由 VitePress 1.6 构建，产物不含任何服务端运行时。
|
||||
IotLCM 平台通过 Docker Compose 在单机上部署。部署编排与数据库初始化脚本在独立仓库：
|
||||
|
||||
::: tip 一句话结论
|
||||
生产推荐 **Docker + nginx**（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 **Node 构建 + 任意 Web 服务器托管静态产物**。
|
||||
```bash
|
||||
git clone https://git.5iot.com/iotlcm-public/iotlcm-deploy.git
|
||||
cd iotlcm-deploy
|
||||
```
|
||||
|
||||
```text
|
||||
iotlcm-deploy/
|
||||
├── docker-compose.yml # 服务编排
|
||||
├── .env.example # 环境变量模板
|
||||
├── config.example/ # 应用配置模板（10 份）
|
||||
└── schema/ # 数据库初始化脚本（12 个）
|
||||
```
|
||||
|
||||
## 部署内容
|
||||
|
||||
| 类别 | 服务 |
|
||||
| --- | --- |
|
||||
| 基础组件 | MySQL、Redis、RabbitMQ、Consul |
|
||||
| 管理端 | admin-svr（后端）、admin-ui（前端） |
|
||||
| 对外接口 | openapi |
|
||||
| 小程序 / H5 | app-server（后端）、app-web（前端） |
|
||||
| 运营商对接 | upstream-chan（协议适配）、upstream-proxy（缓存转发） |
|
||||
| 异步任务 | worker-svr（批次执行、全量同步） |
|
||||
| 配套 | sms（短信）、docs（本文档站） |
|
||||
| 可选 | onelink-mock（运营商接口挡板）、bot（飞书通知）、nginx（反向代理） |
|
||||
|
||||
## 部署流程
|
||||
|
||||
```bash
|
||||
cp .env.example .env # 1. 环境变量
|
||||
cp -r config.example config # 2. 应用配置
|
||||
docker compose up -d # 3. 启动
|
||||
```
|
||||
|
||||
首次启动自动建库并导入 schema，约 1~2 分钟。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 内容 |
|
||||
| --- | --- |
|
||||
| [环境准备](prerequisites) | 硬件、系统、Docker 版本、端口规划 |
|
||||
| [配置说明](configuration) | `.env` 与 `config/` 各项含义 |
|
||||
| [启动与验证](install) | 启动流程、验证清单、首次登录 |
|
||||
| [可选服务](optional) | 接口挡板、飞书通知、反向代理 |
|
||||
| [升级与备份](operations) | 版本固定、升级回滚、数据备份 |
|
||||
| [故障排查](troubleshooting) | 常见问题与处理 |
|
||||
|
||||
## 关键约束
|
||||
|
||||
::: warning JWT 密钥必须三处一致
|
||||
`admin-svr`、`openapi`、`app-server` 共用同一个 `JWT_SIGNING_KEY`。不一致的表现是能登录管理端，但调用外部 API 或小程序端提示未授权。
|
||||
|
||||
更换该值会使已签发的全部登录态与接口令牌立即失效，需在维护窗口操作。
|
||||
:::
|
||||
|
||||
## 怎么选部署方式
|
||||
::: tip 镜像标签不要用 latest
|
||||
生产环境必须把 `TAG` 固定到具体版本号。`latest` 会随仓库推送变化，同一份编排在不同时间拉到的镜像不同，出问题无法定位，也无法明确回滚。
|
||||
:::
|
||||
|
||||
| 你的情况 | 看哪页 |
|
||||
| --- | --- |
|
||||
| 生产环境，机器上不想装 Node | [推荐环境部署：Docker + nginx](./docker-nginx) |
|
||||
| 有现成 nginx，只需托管静态文件 | [静态托管部署](./static-hosting) |
|
||||
| 内网 / 无法访问公网 npm | [内网与离线部署](./offline) |
|
||||
| 只是改文档、本地看效果 | [本地开发与预览](./local-dev) |
|
||||
| 遇到报错或白屏 | [常见问题](./faq) |
|
||||
::: danger 修改 schema 脚本不会自动生效
|
||||
数据库初始化只在 `data/mysql` 为空时执行。改了 `schema/` 下的脚本必须清空数据卷才会重跑，而清空会丢失全部数据。生产环境禁止这样操作。
|
||||
:::
|
||||
|
||||
## 环境要求
|
||||
## 服务端口
|
||||
|
||||
### 构建环境（必需）
|
||||
默认端口规划：
|
||||
|
||||
| 项 | 推荐 | 最低 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 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 | 纯静态，压力极低 |
|
||||
| 8000 | openapi | 经反向代理 |
|
||||
| 8008 | admin-svr | 经反向代理 |
|
||||
| 8009 | admin-ui | 经反向代理 |
|
||||
| 8010 | app-server | 经反向代理 |
|
||||
| 8018 | app-web | 经反向代理 |
|
||||
| 8019 | docs | 经反向代理 |
|
||||
| 3306 / 6379 / 5672 / 8500 | MySQL / Redis / RabbitMQ / Consul | 仅内网 |
|
||||
| 8110 / 8310 / 8510 | upstream-chan / upstream-proxy | 仅内网 |
|
||||
| 11190 / 11200 | sms | 仅内网 |
|
||||
| 8080 | onelink-mock | 仅联调 |
|
||||
|
||||
### 实测参考
|
||||
|
||||
在 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) |
|
||||
端口冲突时修改 `.env` 中对应变量，不要直接改 `docker-compose.yml`。
|
||||
|
||||
Reference in New Issue
Block a user