---
title: 部署与运维
description: 生产部署前的必改项、可选组件、离线部署与常见问题
outline: deep
---

# 部署与运维

## 一键启动

```bash
git clone https://gitee.com/snowgoat/iotlcm.git
cd iotlcm/deploy
docker compose up -d
```

部署编排与数据库初始化脚本都在仓库的 `deploy/` 目录：

```text
deploy/
├── docker-compose.yml      # 服务编排（含默认口令与端口）
├── compose.memlimit.yml    # 容器内存上限（按机器规格叠加使用）
├── config/                 # 各服务配置 + gateway / nginx 两种入口配置
├── schema/init.sql         # MySQL 初始化（95 表 + 种子数据）
├── tdengine-init/          # 时序库建库建表（首次启动自动执行）
└── data/                   # 运行数据，首次启动自动创建
```

## 可选组件

```bash
docker compose --profile with-mock up -d     # 运营商接口挡板
docker compose --profile with-bot up -d      # 飞书通知（运维自用）
docker compose --profile with-nginx up -d    # 自带反向代理（多域名入口）
docker compose --profile with-gateway up -d  # 单端口入口（默认对外 5051）
```

多个 profile 可组合。

### 单端口入口（with-gateway）

只暴露一个端口时用它。容器内监听 80，宿主机端口由 `GATEWAY_PORT` 控制（默认 5051）：

```bash
docker compose --profile with-gateway up -d
# 或换端口
GATEWAY_PORT=8088 docker compose --profile with-gateway up -d
```

| 路径 | 去向 |
| --- | --- |
| `/` | 管理端（admin-ui，内部已代理 `/api/` 到 admin-svr） |
| `/docs/` | 文档站 |
| `/openapi/` | 对外 API |
| `/route/open/` | 运营商能力代理（白名单 / 共享 Token） |

配置见 `config/gateway/nginx.conf`。小程序 / H5 端的静态资源是根路径部署的，不能挂在同一域名的子路径下，需要单独域名或端口（见 `with-nginx` 的 app 段）。

`with-bot` 是把全量同步等运维事件推送到飞书群的**内部运维工具**，不是平台功能。它需要你自己的飞书自建应用凭证（`config/bot/config.yaml` 的 `appId` / `appSecret` / `chatId`），没填就不启动。

**默认不启动，也不影响平台功能**；不需要飞书通知就完全不用管它。

## 线上暴露到公网

80 / 443 入站在多数办公宽带上被运营商封禁，可评估三种形态：

| 形态 | 适用 | 代价 |
| --- | --- | --- |
| 高位端口 NAT | 内部验收、演示 | 地址带端口，不适合对外正式发布 |
| 独立子域 + 反代 | 有公网 IP 的服务器 | 需要域名解析与证书 |
| 云主机统一入口 | 正式对外发布 | 需要域名（以及国内服务器的备案） |

## 上线前必改

| 项 | 说明 |
| --- | --- |
| 数据库口令 | MySQL 的 root 与应用账号口令 |
| Redis 口令 | 缓存层口令 |
| RabbitMQ 口令 | 队列层口令 |
| admin 口令 | 种子账号初始口令统一重置过，必须改 |
| JWT 密钥 | 管理端与用户端签发令牌用 |
| 运营商通道凭据 | 通道配置的 appKey / appSecret / 账号，按运营商要求申请 |
| 对象存储 | 图片与附件的存放位置 |

## 离线部署

目标机器不能出网时：

1. 在有网机器上拉全部镜像并导出：

```bash
docker compose pull
docker save -o iotlcm-images.tar $(docker compose config --images)
```

2. 拷贝 `iotlcm-images.tar` 与仓库的 `deploy/` 目录到目标机器；
3. `docker load -i iotlcm-images.tar` 后再 `docker compose up -d`。

## 常见问题

| 现象 | 原因与处置 |
| --- | --- |
| MySQL 初始化中途失败 | schema 只在数据卷为空时执行，改完脚本必须清空卷才会重跑：`docker compose down && sudo rm -rf ./data/mysql && docker compose up -d` |
| 访问 8019 端口白屏 | 文档站必须带 `/docs/` 路径，裸端口会白屏 |
| 偶发 502 | 容器重建后 upstream IP 变化，nginx 未重新解析；配置已带 `resolver` + `resolve`，若仍出现，重启网关容器即可 |
| 通道调用报 IP 鉴权失败 | 运营商侧需要报备出口 IP，未报备则拒绝调用 |
| 端口被占用 | 编排里业务端口默认绑 `127.0.0.1`，改端口映射即可避开冲突 |

## 监控

Consul 提供服务注册与健康探针，Prometheus 指标入口在编排内已开。日志按服务落在 `deploy/data/logs/` 下，配合 logrotate 生效。