feat: 开源项目门户站首版（iotLCM / 秀杰 DTU / XiuAdmin 三项目，注册表驱动）

2026-11-04 11:08:47 +08:00
commit fe63dacae2
27 changed files with 3786 additions and 0 deletions
@@ -0,0 +1,111 @@
+---
+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 生效。