iotlcm-public/iotlcm
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
原 /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
Download Patch File Download Diff File Expand all files Collapse all files
.vitepress/config.mts
+7 -13
View File
@@ -82,24 +82,18 @@ export default defineConfig({
collapsed: false,
items: [
{ text: '部署概览', link: '/deploy/' },
{ text: '路径前缀必读', link: '/deploy/path-prefix' },
{ text: '环境准备', link: '/deploy/prerequisites' },
{ text: '配置说明', link: '/deploy/configuration' },
{ text: '启动与验证', link: '/deploy/install' },
]
},
{
text: '部署方式',
text: '运维',
collapsed: false,
items: [
{ text: '推荐：Docker + nginx', link: '/deploy/docker-nginx' },
{ text: '静态托管部署', link: '/deploy/static-hosting' },
{ text: '内网与离线部署', link: '/deploy/offline' },
]
},
{
text: '开发与排错',
collapsed: false,
items: [
{ text: '本地开发与预览', link: '/deploy/local-dev' },
{ text: '常见问题', link: '/deploy/faq' },
{ text: '可选服务', link: '/deploy/optional' },
{ text: '升级与备份', link: '/deploy/operations' },
{ text: '故障排查', link: '/deploy/troubleshooting' },
]
},
],
docs/deploy/configuration.md
+178
View File
@@ -0,0 +1,178 @@
---
title: 配置说明
description: 部署环境变量与应用配置文件的填写方式
outline: deep
---
# 配置说明
平台配置分两层：
| 层 | 位置 | 管什么 | 是否入库 |
| --- | --- | --- | --- |
| 部署层 | `.env` | 镜像仓库、口令、端口、外部服务地址 | 否 |
| 应用层 | `config/<服务>/config.yaml` | 业务参数、连接串、功能开关 | 否 |
两者分别由 `.env.example` 与 `config.example/` 复制而来，`.gitignore` 已排除。**不要把自己的配置提交回仓库。**
## 一、环境变量
```bash
cp .env.example .env
```
### 必填项
| 变量 | 说明 |
| --- | --- |
| `REGISTRY` | 镜像仓库地址，不含协议与末尾斜杠 |
| `TAG` | 镜像标签，生产用具体版本号 |
| `MYSQL_ROOT_PASSWORD` | MySQL root 口令 |
| `MYSQL_APP_PASSWORD` | 应用账号 `u_iotlcm` 的口令 |
| `MYSQL_ADMIN_PASSWORD` | 平台 admin 账号初始口令 |
| `REDIS_PASSWORD` | Redis 口令 |
| `RABBITMQ_PASSWORD` | RabbitMQ 口令 |
| `JWT_SIGNING_KEY` | JWT 签名密钥 |
任一项未设置时 `docker compose` 会直接报错退出，不会用空值或弱口令启动。
生成强口令：
```bash
openssl rand -base64 24 # 各类密码
openssl rand -hex 32 # JWT_SIGNING_KEY
```
### 可选项
| 变量 | 不填的影响 |
| --- | --- |
| `DIAGNOSIS_INTERNAL_TOKEN` | 控制台「智能诊断」不可用 |
| `SMS_ACCESS_KEY_ID` / `SMS_ACCESS_KEY_SECRET` | 无法发送短信验证码 |
| `FEISHU_APP_ID` / `FEISHU_APP_SECRET` / `FEISHU_CHAT_ID` | 不启动 bot 即可 |
| `TDENGINE_*` | 历史流量查询不可用，主流程正常 |
### 端口
全部端口变量见 `.env.example`，均有默认值。改端口只改 `.env`。
## 二、应用配置
```bash
cp -r config.example config
```
得到 10 份：
```
config/
├── admin-svr/config.yaml
├── admin-ui/default.conf
├── app-server/config.yaml
├── bot/config.yaml
├── nginx/iotlcm.conf
├── openapi/config.yaml
├── sms/config.yaml
├── upstream-chan/config.yaml
├── upstream-proxy/config.yaml
└── worker-svr/config.yaml
```
所有配置支持 `${VAR}` 与 `${VAR:default}` 占位，由 compose 从 `.env` 注入。**口令类字段保持占位引用即可，不要写死明文。**
### 各服务配置要点
#### admin-svr（管理端后端）
| 项 | 说明 |
| --- | --- |
| `database.default.link` | 库连接串，已用 `${MYSQL_APP_PASSWORD}` 拼好 |
| `database.legacyCard.link` | 旧平台库，没有就留空 |
| `jwt.signingKey` | 保持 `${JWT_SIGNING_KEY}` |
| `warning.sms.enabled` | 不用短信改 `false` |
| `warning.wechat.*` | 不用微信订阅消息改 `false` 并留空 |
| `register.email.*` | 邮件验证码的 SMTP，不用则留空 |
| `tsdb.tdengine.dsn` | 不用时序库则留空 |
| `alipay.*` | 不用支付宝整段删除 |
| `upstream.appDiagnosisToken` | 与 proxy 的 `appDiagnosis.internalToken` 一致 |
#### openapi（对外 API）
| 项 | 说明 |
| --- | --- |
| `jwt.signingKey` | 与 admin-svr 一致 |
| `database.default.link` | 建议单独建只读账号隔离 |
#### worker-svr（异步任务）
| 项 | 说明 |
| --- | --- |
| `batch.inbound.upstreamRateLimit` | **运营商接口限流，必须按上游实际配额设置**，调太大会被限流或封禁 |
| `rabbitmq.batchExecute.maxRetries` | 批次执行失败重试次数 |
| `tsdb.tdengine.dsn` | 不用时序库则留空 |
#### upstream-chan（运营商对接）
| 项 | 说明 |
| --- | --- |
| `registry.address` | Consul 地址，默认 `consul:8500` |
| `dependencies.sim_yd_mock_v5.url` | 挡板地址，对接真实运营商时删除本段 |
| `dependencies.token_refresh.skew_seconds` | 运营商 Token 提前刷新窗口 |
运营商通道本身（AppKey、AppSecret、接口地址）不在本文件配置，而是在平台「通道管理」中录入，存数据库。
#### upstream-proxy（通道缓存转发）
| 项 | 说明 |
| --- | --- |
| `appDiagnosis.internalToken` | 与 admin-svr 的 `upstream.appDiagnosisToken` 一致 |
| `gateway.batchTimeout` | 批量转发总预算上限，**worker 侧超时必须大于此值** |
#### app-server（小程序后端）
| 项 | 说明 |
| --- | --- |
| `jwt.signingKey` | 与 admin-svr 一致 |
| `payment.wechat.*` | 不用支付把 `enabled` 改 `false` |
| `appCardRecognition.*` | 拍照识别卡号，不用改 `false` |
| `upstream.onelinkMock.*` | 挡板联调配置，切真实运营商时 `enabled: false` |
#### sms（短信服务）
| 项 | 说明 |
| --- | --- |
| `serviceType` | `1`=阿里云，`2`=腾讯云 |
| `accessKeyId` / `accessKeySecret` | 从 `.env` 注入 |
| `signName` | 短信签名，需服务商审核通过 |
#### bot（飞书通知，可选）
`feishu.appId`、`appSecret`、`chatId` 全部从 `.env` 注入。
#### admin-ui（管理端 nginx）
`default.conf` 中 `/api/` 反代到 `admin-svr:8008`，`/upload/` 指向共享上传目录。一般无需修改。
#### nginx（对外入口，可选）
`iotlcm.conf` 按域名分三组 server：`api.*` → openapi，`admin.*` → 管理端与文档站，`app.*` → 小程序端。**把示例域名替换为实际域名。**
不用自带 nginx 时，把其中 `location` 段落复制到宿主机 nginx 配置即可。
## 三、配置自检
启动前验证：
```bash
# 检查展开结果（不启动容器）
docker compose config
# 只检查必填项是否齐全
docker compose config --quiet
```
配置语法错误会导致服务启动后立即退出，用日志定位：
```bash
docker compose logs --tail=50 admin-svr
```
docs/deploy/docker-nginx.md
-159
View File
@@ -1,159 +0,0 @@
---
title: Docker + nginx 部署
description: 推荐环境部署方式：多阶段构建镜像 + nginx 托管
outline: deep
---
# 推荐环境部署：Docker + nginx
适用：生产环境、需要长期稳定运行、机器上不想装 Node。
仓库自带多阶段 `Dockerfile`：Node 阶段执行 `vitepress build`，最终镜像只含 nginx 与静态产物，**不含 Node 和 `node_modules`**。
## 构建镜像
```bash
SHA=$(git rev-parse --short HEAD)
docker build -t iotlcm-docs:$SHA .
```
用 commit sha 做标签，便于追溯与回滚；不建议只用 `latest`。
## 启动容器
```bash
docker run -d \
--name iotlcm-docs \
--restart unless-stopped \
-p 8019:80 \
iotlcm-docs:$SHA
```
## nginx 配置（关键）
`docker/nginx.conf` 用 `alias` 把 `/docs/` 前缀剥掉：
```nginx
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
# 产物按 base=/docs/ 生成，资源引用形如 /docs/assets/xxx
location /docs/ {
alias /usr/share/nginx/html/;
try_files $uri $uri.html $uri/ $uri/index.html =404;
}
# 根路径跳到文档入口，避免访问 / 时白屏
location = / {
return 302 /docs/;
}
location / {
try_files $uri $uri.html $uri/ =404;
}
}
```
`try_files` 里的 `$uri.html` 与 `$uri/index.html` 是必需的：配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀，需要服务器做内部映射。
原理说明见 [路径前缀必读](./path-prefix)。
## 部署后自检
```bash
# 1. 入口可访问（应返回 200）
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/
# 2. 根路径应 302 到 /docs/
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/
# 3. 静态资源不能 404（最容易出问题的一步）
ASSET=$(curl -s http://127.0.0.1:8019/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
curl -o /dev/null -s -w '%{http_code}\n' "http://127.0.0.1:8019$ASSET"
# 4. 抽查正文页面
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/manual/web/
```
四项都返回 `200`（第 2 项返回 `302`）才算部署成功。
## 通过外层反向代理对外
生产常见做法：容器只监听 `127.0.0.1`，由外层 nginx 转发。
```nginx
upstream iotlcm_docs {
server 127.0.0.1:8019;
}
location = /docs {
return 301 /docs/;
}
location /docs/ {
proxy_pass http://iotlcm_docs; # 末尾不要加斜杠
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
```
::: danger proxy_pass 末尾斜杠
写成 `proxy_pass http://iotlcm_docs/;`（带末尾斜杠）会把 `/docs/` 前缀剥掉，转发到容器变成 `/`，导致资源全部 404 白屏。**必须不带末尾斜杠**。
:::
## docker compose
`docker-compose.yml` 中镜像名是占位值，需替换为自己的仓库地址：
```yaml
services:
docs:
image: your-registry/iotlcm/iotlcm-docs:${TAG:-latest}
container_name: iotlcm-docs
restart: unless-stopped
ports:
- "127.0.0.1:8019:80"
networks:
- iotlcm-network
networks:
iotlcm-network:
external: true
name: iotlcm-network
```
compose 文件声明 `iotlcm-network` 为外部网络，若不存在需先创建：
```bash
docker network create iotlcm-network
```
启动：
```bash
TAG=$(git rev-parse --short HEAD) docker compose up -d
```
## 版本固定与升级
开源仓按**固定版本**发布（无 git 历史，单次初始提交）。部署时请记录并锁定 commit：
```bash
SHA=$(git rev-parse HEAD)
echo "部署基线: $SHA" >> deploy.log
docker build -t iotlcm-docs:$SHA .
```
升级文档时，从上游选定基线重新发布后，按新 sha 重建镜像并滚动替换容器：
```bash
docker rm -f iotlcm-docs
docker run -d --name iotlcm-docs --restart unless-stopped -p 8019:80 iotlcm-docs:$NEW_SHA
```
docs/deploy/faq.md
-177
View File
@@ -1,177 +0,0 @@
---
title: 常见问题
description: 部署与构建过程中的故障排查
outline: deep
---
# 常见问题
## 部署类
### 页面能打开但白屏、无样式
**原因**：`/docs/` 路径前缀未剥离，资源全部 404。
这是最常见的部署故障。`base: '/docs/'` 使 HTML 引用 `/docs/assets/*`，但产物是平铺的，服务器从根路径找 `/assets/*` 就 404。
**危险之处**：`curl /` 返回 200，看起来部署成功，实际浏览器是空白。
**处理**：见 [路径前缀必读](./path-prefix)，三种做法任选其一。
### 访问 `/` 返回 404
**原因**：`base: '/docs/'`，站点根路径不是入口。
**处理**：访问 `/docs/`。若希望 `/` 自动跳转，加：
```nginx
location = / { return 302 /docs/; }
```
### 访问 `/docs`（无末尾斜杠）404
**原因**：未配置重定向，而 VitePress 生成的目录结构需要末尾斜杠。
**处理**：
```nginx
location = /docs { return 301 /docs/; }
```
### 首页正常，点进任何内页都 404
**原因**：`cleanUrls: true` 使页面 URL 不带 `.html`，服务器缺少内部映射。
**处理**：`try_files` 补上两种映射：
```nginx
try_files $uri $uri.html $uri/ $uri/index.html =404;
```
### 反向代理后白屏
**原因**：`proxy_pass` 带了末尾斜杠，把 `/docs/` 前缀剥掉后转发成 `/`。
**处理**：去掉末尾斜杠：
```nginx
# 错误
proxy_pass http://iotlcm_docs/;
# 正确
proxy_pass http://iotlcm_docs;
```
### 图片全部 404
**原因**：图片放在 `docs/public/images/`，构建后映射到产物根的 `images/`，引用时需要用站点绝对路径（含 base）。
**处理**：正文写 `/images/xxx.png`（VitePress 会自动补 `base`）。若写相对路径 `./images/xxx.png` 会因页面层级不同而失效。
## 构建类
### `npm ci` 报 lock 文件不一致
**原因**：Node 版本过低，或 lock 与 `package.json` 不同步。
**处理**：
1. 升级到 Node 22：
```bash
node -v # 确认 >= 18，推荐 22
```
2. 若仍失败，改用 `npm install`（会更新 lock，注意提交变更）：
```bash
npm install
```
### 构建报内存不足
**原因**：构建峰值约 500 MB，容器内存限制过小时 OOM。
**处理**：给到 ≥ 1 GB：
```bash
docker run -m 1g ...
```
或临时提高 Node 堆上限：
```bash
NODE_OPTIONS=--max-old-space-size=2048 npm run build
```
### 构建成功但页面内容缺失
**原因**：`.md` 文件未保存、或文件不在 `docs/`（`srcDir`）目录下。
**处理**：确认文件路径在 `docs/` 下，且已在 `.vitepress/config.mts` 的 sidebar 注册。
### 新增页面左侧目录不显示
**原因**：只在 `docs/` 下建了文件，没在 `sidebar` 配置里注册。
**处理**：见 [本地开发与预览](./local-dev) 的「新增页面的步骤」。
### 中文搜索失效或搜不到新页面
**原因**：本地搜索索引在构建时生成，dev 模式下可能有延迟；产物未重新构建。
**处理**：重新 `npm run build`。
## 运行类
### 端口 5173 被占用
**处理**：
```bash
npx vitepress dev . --port 5174
```
或结束旧进程：
```bash
lsof -ti:5173 | xargs kill
```
### 局域网其他机器访问不了 dev 服务
**原因**：默认只监听 `127.0.0.1`。
**处理**：
```bash
npx vitepress dev . --host 0.0.0.0
```
并确认防火墙放行对应端口。
### 修改 `.md` 后页面没更新
**原因**：浏览器缓存，或 dev 进程已退出。
**处理**：硬刷新（`Ctrl+Shift+R`），确认终端里 dev 进程仍在运行。
## 快速自检清单
部署完成后依次确认：
```bash
# 1. 入口 200
curl -o /dev/null -s -w '%{http_code}\n' http://<host>/docs/
# 2. 根路径 302（若配置了重定向）
curl -o /dev/null -s -w '%{http_code}\n' http://<host>/
# 3. 静态资源 200（最关键）
ASSET=$(curl -s http://<host>/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
curl -o /dev/null -s -w '%{http_code}\n' "http://<host>$ASSET"
# 4. 内页 200
curl -o /dev/null -s -w '%{http_code}\n' http://<host>/docs/manual/web/
```
四项都正常才算部署成功。浏览器再打开一次确认没有白屏。
docs/deploy/index.md
+75 -66
View File
@@ -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`。
docs/deploy/install.md
+182
View File
@@ -0,0 +1,182 @@
---
title: 启动与验证
description: 首次启动流程、状态检查与验证清单
outline: deep
---
# 启动与验证
## 启动
```bash
# 首次部署建议前台启动，便于观察初始化过程
docker compose up
# 确认无误后转后台
docker compose up -d
```
### 首次启动发生什么
1. **MySQL 建库并导入 schema**（约 1~2 分钟）
`schema/` 下 12 个脚本按文件名顺序执行：建表 → 结构补齐 → 创建应用账号 → 重置种子账号口令 → 导入通道模板/字典/菜单等种子数据
2. MySQL 通过健康检查后，`admin-svr`、`openapi`、`worker-svr` 依次启动
3. 各服务向 Consul 注册
观察初始化进度：
```bash
docker compose logs -f mysql
```
看到 `[initdb] 应用账号 u_iotlcm 已创建` 与 `[initdb] 种子账号口令已统一重置` 表示初始化完成。
::: warning 初始化失败需清空数据卷
MySQL 只在 `data/mysql` 为空时执行 `schema/`。若中途失败，改完脚本必须清空卷才会重跑：
```bash
docker compose down
sudo rm -rf ./data/mysql
docker compose up -d
```
这会删除全部数据，仅限首次部署阶段使用。
:::
## 检查状态
```bash
docker compose ps
```
期望结果：
| 服务 | 状态 |
| --- | --- |
| iotlcm-mysql | Up (healthy) |
| iotlcm-redis | Up (healthy) |
| iotlcm-rabbitmq | Up (healthy) |
| iotlcm-consul | Up |
| iotlcm-admin-svr | Up |
| iotlcm-admin-ui | Up |
| iotlcm-openapi | Up |
| iotlcm-upstream-chan | Up |
| iotlcm-upstream-proxy | Up |
| iotlcm-worker-svr | Up |
| iotlcm-app-server | Up |
| iotlcm-app-web | Up |
| iotlcm-sms | Up (healthy) |
| iotlcm-docs | Up |
出现 `Restarting` 或 `Exited` 需查日志：
```bash
docker compose logs --tail=100 <服务名>
```
## 验证清单
按顺序逐项确认，任一步失败先解决再继续。
### 1. 数据库表数量
```bash
docker compose exec mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e \
"SELECT COUNT(*) AS tables FROM information_schema.tables WHERE table_schema=\"db_iotlcm\";"'
```
预期 `tables` = **89**。
### 2. 种子数据
```bash
docker compose exec mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm -e \
"SELECT (SELECT COUNT(*) FROM sys_menu) AS menus, (SELECT COUNT(*) FROM sys_user) AS users;"'
```
预期菜单约 **447** 条，账号 **18** 个。
### 3. 管理端后端
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8008/api.json
```
预期 `200`。
### 4. 管理端前端
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8009/
```
预期 `200`。
### 5. 对外 API
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/api.json
```
预期 `200`。
### 6. 短信服务
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:11190/healthz
```
预期 `200`。
### 7. 浏览器登录
访问 `http://<宿主机IP>:8009`：
| 项 | 值 |
| --- | --- |
| 账号 | `admin` |
| 口令 | `.env` 中的 `MYSQL_ADMIN_PASSWORD` |
能进入首页工作台、左侧菜单完整显示即部署成功。
## 首次登录后必做
1. **修改 admin 口令**：右上角个人中心 → 安全设置
2. **处理其余种子账号**：`user02`、`2admin` 等 17 个账号默认与 admin 同一口令，不使用请停用或删除
3. **确认字典与菜单加载**：进入「卡信息」页，确认筛选下拉选项不为空
## 后端自检
```bash
# admin-svr 是否连上数据库
docker compose logs admin-svr | grep -iE 'error|panic' | tail -20
# worker-svr 是否连上 RabbitMQ
docker compose logs worker-svr | tail -30
# upstream-chan 是否连上 Redis 与 Consul
docker compose logs upstream-chan | tail -30
```
正常日志不应出现 `connection refused`、`access denied`、`panic`。
## 停止与重启
```bash
docker compose stop # 停止，保留数据
docker compose restart # 重启全部
docker compose restart admin-svr # 重启单个
docker compose down # 停止并删除容器（./data 不受影响）
```
::: danger 不要执行 down -v
`-v` 会删除命名数据卷。本编排数据都在 `./data` 宿主机目录，但 `-v` 仍可能影响同项目的其他卷。停止服务用 `down` 即可。
:::
## 下一步
- 需要运营商挡板联调 → [可选服务](optional)
- 需要域名访问 → [可选服务](optional) 的反向代理章节
- 遇到报错 → [故障排查](troubleshooting)
docs/deploy/local-dev.md
-125
View File
@@ -1,125 +0,0 @@
---
title: 本地开发与预览
description: 改文档时用 dev 模式，热更新实时看效果
outline: deep
---
# 本地开发与预览
适用：修改文档内容、调整配置、本地看效果。
## 启动开发服务器
```bash
npm ci
npm run dev
```
访问 **`http://127.0.0.1:5173/docs/`**
::: warning 地址必须带 /docs/
`base: '/docs/'` 决定了 dev 服务器入口也在子路径下，直接访问 `http://127.0.0.1:5173/` 会 404。
:::
改动 `docs/` 下任意 `.md` 文件会**热更新**，无需重启。按 `Ctrl+C` 退出。
## 局域网访问
需要让同网段其他机器访问时，把监听地址改为 `0.0.0.0`：
```bash
npx vitepress dev . --host 0.0.0.0
# 然后访问 http://<本机IP>:5173/docs/
```
## 端口冲突
默认 5173，被占用时换端口：
```bash
npx vitepress dev . --port 5174
```
## 预览构建产物
`dev` 模式是源码实时编译，与最终产物有细微差异（如资源路径、代码分割）。发布前建议跑一次真实构建：
```bash
npm run build # 产物在 .vitepress/dist
npm run preview # http://127.0.0.1:4173/docs/
```
`preview` 只是本地起静态服务验证产物，**不要用于生产**。
## 目录结构
新增页面时按此结构放置：
```text
iotlcm-docs/
├── docs/ # 文档源（VitePress srcDir）
│ ├── index.md # 站点首页
│ ├── manual/ # 使用手册
│ │ ├── web/ # Web 管理端
│ │ └── mini-program/ # 小程序端
│ ├── openapi/ # OpenAPI 合同
│ ├── deploy/ # 部署手册（本手册）
│ └── public/ # 静态资源，映射到站点根路径
│ └── images/ # 文档配图
└── .vitepress/
├── config.mts # 站点配置（导航、侧边栏）
└── theme/ # 主题定制
```
## 新增页面的步骤
1. 在 `docs/` 下对应目录新建 `xxx.md`，写 frontmatter：
```markdown
---
title: 页面标题
description: 页面描述
outline: deep
---
# 页面标题
```
2. 在 `.vitepress/config.mts` 的 `sidebar` 中注册，否则左侧目录不会显示：
```ts
sidebar: {
'/deploy/': [
{
text: '部署手册',
collapsed: false,
items: [
{ text: '概览', link: '/deploy/' },
{ text: '新页面', link: '/deploy/xxx' },
]
},
],
}
```
3. 图片放 `docs/public/images/`，正文用绝对路径引用（public 目录映射到站点根）：
```markdown
![说明](/images/xxx.png)
```
## 构建产物结构
```text
.vitepress/dist/
├── index.html # 首页
├── 404.html # 404 页
├── favicon.png
├── assets/ # JS / CSS / 字体（带 hash）
├── images/ # 来自 docs/public/images
├── manual/ # 各章节
├── openapi/
└── deploy/
```
注意产物是**平铺**的，没有 `docs/` 子目录——这正是部署时需要处理路径前缀的原因，见 [路径前缀必读](./path-prefix)。
docs/deploy/offline.md
-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**。
:::
docs/deploy/operations.md
+184
View File
@@ -0,0 +1,184 @@
---
title: 升级与备份
description: 版本固定、升级回滚、数据备份与日志清理
outline: deep
---
# 升级与备份
## 版本固定
生产环境**必须固定镜像标签**，不要用 `latest`：
- `latest` 会随仓库推送变化，同一份编排在不同时间拉到的镜像不同
- 出问题无法确定运行版本
- 回滚时没有明确目标
`.env` 中指定：
```bash
TAG=1.0.3
```
记录当前部署版本：
```bash
echo "$(date '+%Y-%m-%d %H:%M') TAG=$(grep '^TAG=' .env | cut -d= -f2)" >> deploy-history.log
```
## 升级
```bash
# 1. 备份（不要跳过，见下节）
./backup.sh
# 2. 拉新镜像
vi .env # 修改 TAG
docker compose pull
# 3. 更新
docker compose up -d
# 4. 验证
docker compose ps
docker compose logs --tail=50 admin-svr
```
滚动更新单个服务减少中断：
```bash
docker compose up -d --no-deps admin-svr
```
## 回滚
```bash
vi .env # TAG 改回旧版本
docker compose pull
docker compose up -d
```
::: warning 数据库变更不能随代码回滚
若新版本含数据库结构变更，回滚代码后数据库仍是新结构。升级前确认变更可逆，或保留升级前的完整备份。
:::
## 数据库重建
`schema/` 脚本只在 `data/mysql` 为空时执行：
| 情况 | 是否需要重建 |
| --- | --- |
| 升级应用镜像 | 否 |
| 修改 `config/` | 否，重启对应服务即可 |
| 修改 `schema/` 脚本 | 是（会丢数据） |
| 首次初始化失败 | 是 |
```bash
docker compose down
sudo rm -rf ./data/mysql
docker compose up -d
```
::: danger 生产环境禁止清空 data/mysql
生产数据必须通过数据库工具单独备份与迁移，不能依赖 schema 重建。
:::
## 备份
### 备份脚本
```bash
#!/bin/bash
set -euo pipefail
cd "$(dirname "$0")"
STAMP=$(date '+%Y%m%d-%H%M%S')
DEST="./backups/${STAMP}"
mkdir -p "$DEST"
echo "[1/3] 导出数据库..."
docker compose exec -T mysql sh -c \
'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --routines --triggers --events db_iotlcm' \
| gzip > "${DEST}/db_iotlcm.sql.gz"
echo "[2/3] 备份配置..."
tar czf "${DEST}/config.tar.gz" config/ .env
echo "[3/3] 备份上传文件..."
tar czf "${DEST}/upload.tar.gz" data/upload/ 2>/dev/null || echo " 上传目录为空，跳过"
echo "完成：${DEST}"
ls -lh "$DEST"
```
```bash
chmod +x backup.sh && ./backup.sh
```
### 只备份数据库
```bash
docker compose exec -T mysql sh -c \
'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction db_iotlcm' \
| gzip > "db_iotlcm-$(date +%Y%m%d).sql.gz"
```
### 恢复
```bash
gunzip -c db_iotlcm-20260101.sql.gz | \
docker compose exec -T mysql sh -c \
'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm'
```
### 备份内容与优先级
| 内容 | 位置 | 重要性 |
| --- | --- | --- |
| 数据库 | MySQL 容器内 `db_iotlcm` | **最高**，业务数据全部在此 |
| 配置 | `config/` + `.env` | 高，丢失需重新配置 |
| 上传文件 | `data/upload/` | 中，附件与图片 |
| Redis 数据 | `data/redis/` | 低，缓存可重建 |
| RabbitMQ 队列 | `data/rabbitmq/` | 低，未消费消息会丢失 |
| 日志 | `data/logs/` | 低，排障用 |
### 备份策略
| 场景 | 频率 | 保留 |
| --- | --- | --- |
| 生产 | 每日一次 + 升级前 | 30 天 |
| 试用 | 有数据变更时 | 7 天 |
备份文件应转存到异机或对象存储，不要与数据库同盘。
## 日志清理
日志写在 `data/logs/` 下按服务分目录，应用侧已按小时轮转（`{Y-m-d-H}.log`）。清理旧日志：
```bash
# 删除 7 天前的日志
find ./data/logs -name '*.log' -mtime +7 -delete
```
建议配置 cron 定期执行：
```cron
0 3 * * * root find /path/to/iotlcm-deploy/data/logs -name '*.log' -mtime +7 -delete
```
## 监控
基础组件自带端点：
| 服务 | 端点 |
| --- | --- |
| RabbitMQ | `http://<host>:15672` 管理界面 |
| Consul | `http://<host>:8500/ui` |
| MySQL | `docker compose exec mysql mysqladmin status` |
建议告警指标：
- MySQL 连接数与磁盘使用率
- Redis 内存使用率
- RabbitMQ 队列积压（`iotlcm.batch.execute`、`iotlcm.app.business`）
- worker-svr 全量同步任务失败数
docs/deploy/optional.md
+171
View File
@@ -0,0 +1,171 @@
---
title: 可选服务
description: 运营商接口挡板、飞书通知与反向代理
outline: deep
---
# 可选服务
以下服务默认不启动，按需通过 profile 开启。
## 运营商接口挡板
### 用途
模拟中国移动 OneLink 接口。**没有真实运营商环境时，靠它跑通完整链路**：
```text
admin-svr → worker-svr → upstream-chan → onelink-mock
```
不开挡板时，`upstream-chan` 会尝试连接真实运营商接口。没有凭据则批次执行、状态同步、流量查询全部失败。
### 启动
```bash
docker compose --profile with-mock up -d
```
验证：
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api.json
```
预期 `200`。接口文档在 `http://127.0.0.1:8080/swagger`。
### 配置
挡板自身无需配置，数据存在容器内 SQLite（`./data/mock/onelink_mock.db`）。
`upstream-chan` 配置中已预置指向：
```yaml
dependencies:
sim_yd_mock_v5:
url: "http://onelink-mock:8080/v5/"
```
数据库种子脚本 `schema/08-seed-mock-channel.sql` 已插入 Mock 通道（`channel_yd_mock`）并指向该地址。
`app-server` 若使用挡板，把 `upstream.onelinkMock.enabled` 改为 `true`，`baseUrl` 填 `http://onelink-mock:8080/v5`。
### 造测试卡
挡板支持生成模拟卡片，用于验证查询、开停复机、续费流程。接口见挡板 Swagger 页面。
### 切换到真实运营商
1. 删除或注释 `upstream-chan` 配置中的 `sim_yd_mock_v5` 段
2. 在平台「通道管理」录入真实运营商通道（AppKey、AppSecret、接口地址）
3. 停用 Mock 通道，避免卡片误挂
```bash
docker compose --profile with-mock stop onelink-mock
```
## 飞书通知
### 用途
把全量同步完成、失败告警等运维事件推送到飞书群。
### 准备
在飞书开放平台创建自建应用，获取 `appId`、`appSecret` 与目标群的 `chatId`，填入 `.env`：
```bash
FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=xxxxxxxx
FEISHU_CHAT_ID=oc_xxxxxxxx
```
### 启动
```bash
docker compose --profile with-bot up -d
```
bot 读取 `worker-svr` 生成的全量同步归档（`./data/logs/worker-svr/full-sync`），该目录有数据后才会产生通知。
## 反向代理
### 用途
把分散在各端口的服务统一到域名下按路径分流。宿主机已有 nginx 或面板时不需要。
### 域名与分流
编辑 `config/nginx/iotlcm.conf`：
| 域名 | 分流到 |
| --- | --- |
| `api.your-domain.example.com` | openapi（`/openapi/v3/`、`/route/open/`） |
| `admin.your-domain.example.com` | 管理端前端 + `/docs/` 文档站 |
| `app.your-domain.example.com` | 小程序前端 + `/app/api/v1/` 后端 |
### 启动
```bash
docker compose --profile with-nginx up -d
```
默认监听 80，改 `.env` 的 `NGINX_HTTP_PORT` 可调整。
### 使用宿主机 nginx
不启动容器时，把 `config/nginx/iotlcm.conf` 中的 `upstream` 与 `location` 段落复制到宿主机 nginx 配置。
::: warning 宿主机 nginx 无法解析容器名
需要把 `upstream` 里的服务名换成宿主机地址：
```nginx
# 容器内写法
server admin-svr:8008;
# 宿主机写法
server 127.0.0.1:8008;
```
:::
### 启用 HTTPS
自带配置未包含证书，启用需三步：
1. 准备证书，放入 `data/certs/`
2. 在 server 块加入 SSL 配置：
```nginx
listen 443 ssl;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
```
3. 给 nginx 服务增加证书目录挂载，并加 80 → 443 跳转：
```yaml
volumes:
- ./data/certs:/etc/nginx/certs:ro
```
```nginx
server {
listen 80;
server_name admin.your-domain.example.com;
return 301 https://$host$request_uri;
}
```
## 组合启动
多个 profile 可同时启用：
```bash
docker compose --profile with-mock --profile with-nginx up -d
```
查看指定 profile 下的服务清单：
```bash
docker compose --profile with-mock config --services
```
docs/deploy/path-prefix.md
-96
View File
@@ -1,96 +0,0 @@
---
title: 路径前缀必读
description: base=/docs/ 导致的部署白屏问题与三种正确做法
outline: deep
---
# 路径前缀必读
这是本项目最容易出错的地方，**部署失败九成是这个原因**。部署前请务必读完本页。
## 问题成因
文档站配置里 `base: '/docs/'`（见 `.vitepress/config.mts`），因此构建产物中所有资源引用都是**绝对路径**：
```html
<link rel="stylesheet" href="/docs/assets/style.xxx.css">
<script src="/docs/assets/app.xxx.js"></script>
```
而产物目录 `.vitepress/dist` 是**平铺**的，`index.html`、`assets/` 直接在根，**没有 `docs/` 子目录**。
由此推出两条铁律：
1. **对外访问路径必须是 `/docs/`**，且服务器必须把 `/docs/` 前缀剥掉后再落到产物目录
2. 若想挂到别的前缀（如 `/manual/`），必须**先改 `base` 再重新构建**，不能只改服务器配置
::: warning 典型故障：白屏
如果配置成「从根路径直接服务产物」（`root` 指向 dist，访问 `/`），页面 HTML 会返回 200，但 `/docs/assets/*.js` 全部 404 → **浏览器白屏，没有任何报错提示**。
这种情况最坑的地方是：`curl /` 返回 200，看起来部署成功了，实际打开浏览器是空白页。
:::
## 三种正确做法
| 做法 | 适用 | 关键配置 |
| --- | --- | --- |
| nginx `alias` 剥前缀 | 容器部署（推荐） | `location /docs/ { alias /usr/share/nginx/html/; }` |
| 把产物放进 `docs/` 子目录 | 静态托管 / 对象存储 | `dist/` → `www/docs/` |
| 改 `base: '/'` 重新构建 | 独占域名根路径 | 改配置后必须重新 `npm run build` |
### 做法一：nginx alias 剥前缀
```nginx
location /docs/ {
alias /usr/share/nginx/html/;
try_files $uri $uri.html $uri/ $uri/index.html =404;
}
```
`alias` 会剥掉 `location` 的前缀，`/docs/assets/app.js` 实际读到 `/usr/share/nginx/html/assets/app.js`，正好对上平铺的产物目录。
详见 [推荐环境部署：Docker + nginx](./docker-nginx)。
### 做法二：产物放进 docs 子目录
```bash
sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
```
```nginx
root /var/www/iotlcm/www;
location /docs/ {
try_files $uri $uri.html $uri/ $uri/index.html =404;
}
```
`/docs/assets/app.js` 自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
详见 [静态托管部署](./static-hosting)。
### 做法三：改 base 重新构建
```bash
sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
npm run build
```
仅适用于文档站独占域名根路径的场景。
::: danger 不要只改服务器配置
`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。
:::
## cleanUrls 的额外要求
配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀（如 `/manual/web/` 而非 `/manual/web.html`）。
因此服务器的 `try_files` **必须**包含 `$uri.html` 与 `$uri/index.html` 映射：
```nginx
try_files $uri $uri.html $uri/ $uri/index.html =404;
```
缺了这两项的表现是：首页正常，但点进任何内页都是 404。
对象存储场景下需确认支持「无后缀映射到 `.html`」，否则要关闭 `cleanUrls` 重新构建。
docs/deploy/prerequisites.md
+110
View File
@@ -0,0 +1,110 @@
---
title: 环境准备
description: 部署 IotLCM 所需的硬件、系统、Docker 与网络条件
outline: deep
---
# 环境准备
## 硬件要求
按数据规模选择：
| 场景 | CPU | 内存 | 磁盘 | 说明 |
| --- | --- | --- | --- | --- |
| 试用 / 演示 | 2 核 | 4 GB | 40 GB | 少量卡片，建议停用定时同步任务 |
| 生产（中小规模） | 4 核 | 8 GB | 200 GB | 万级卡片，开启全量同步 |
| 生产（大规模） | 8 核+ | 16 GB+ | 500 GB+ | 十万级卡片，建议数据库独立部署 |
磁盘估算：MySQL 数据约 1~2 KB/张卡；日志随同步任务量增长，建议单独挂载并配置轮转。
生产 8 GB 场景的内存分配参考：
| 服务 | 占用 |
| --- | --- |
| MySQL | 1~2 GB |
| Redis | 200~500 MB |
| RabbitMQ | 300~500 MB |
| worker-svr | 500 MB~1 GB（与并发同步卡片数相关） |
| 其余业务服务 | 各 100~200 MB |
## 系统要求
| 项 | 要求 |
| --- | --- |
| 操作系统 | Linux x86_64（CentOS 7+ / Ubuntu 20.04+ / Debian 11+） |
| 内核 | 3.10 以上 |
| 文件系统 | ext4 / xfs |
| 时区 | 建议 `Asia/Shanghai`，与 `.env` 的 `TZ` 保持一致 |
## Docker 要求
| 组件 | 最低版本 | 说明 |
| --- | --- | --- |
| Docker Engine | 20.10 | 需支持 `healthcheck` 与 `profiles` |
| Docker Compose | v2.0（插件版） | 使用 `docker compose` 而非 `docker-compose` |
验证：
```bash
docker version
docker compose version
```
`docker compose version` 需 ≥ v2.0。若只有 `docker-compose`（v1），请升级到 Compose V2 插件。
## 镜像仓库
平台镜像由官方镜像仓库分发，需要：
1. 能访问镜像仓库地址（内网仓库需先配置网络或代理）
2. 具备拉取权限
```bash
docker login <镜像仓库地址>
```
`.env` 的 `REGISTRY` 填写仓库地址，不含 `https://` 与末尾斜杠：
```bash
REGISTRY=registry.example.com
```
基础组件从 `<REGISTRY>/library/` 拉取（mysql、redis、rabbitmq、consul、nginx），业务镜像从 `<REGISTRY>/iotlcm/` 拉取。
## 网络与防火墙
仅需对外开放反向代理端口（默认 80 / 443），其余服务端口应限制为内网访问。
```bash
# 示例：firewalld 仅放行 80/443
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload
```
::: tip 默认只监听本机
`admin-svr`、`admin-ui`、`openapi`、`app-server`、`app-web`、`docs` 默认绑定 `127.0.0.1`，只能本机访问。对外需通过反向代理，见[可选服务](optional)。
:::
## 外部依赖（可选）
| 服务 | 用途 | 不配置的影响 |
| --- | --- | --- |
| TDengine 3.x | 存流量历史数据 | 历史流量查询不可用，主流程正常 |
| 短信服务商 | 发送验证码 | 无法发送短信 |
| 微信支付 | 在线支付 | 支付功能不可用 |
| 飞书 | 运维通知 | 不启动 bot 即可 |
TDengine 需开启 WebSocket 接口（默认 6041），在 `.env` 中配置：
```bash
TDENGINE_HOST=tdengine.example.com
TDENGINE_PORT=6041
TDENGINE_USER=root
TDENGINE_PASSWORD=
TDENGINE_DAILY_DB=iotlcm_daily
TDENGINE_MONTHLY_DB=iotlcm_monthly
```
不使用时全部留空。
docs/deploy/static-hosting.md
-159
View File
@@ -1,159 +0,0 @@
---
title: 静态托管部署
description: 不使用 Docker 时，用 nginx / 对象存储 / CDN 托管静态产物
outline: deep
---
# 静态托管部署
适用：已有 nginx / Apache / Caddy，或使用对象存储 / CDN，不想引入 Docker。
核心流程只有两步：**构建产物** → **托管静态文件**。
## 编译产物
```bash
npm ci
npm run build
# 产物在 .vitepress/dist
```
本地验证构建结果（不要用于生产）：
```bash
npm run preview
# http://127.0.0.1:4173/docs/
```
## nginx：子路径挂载（推荐）
把产物放到一个 `docs` 子目录，即可与 `base` 天然对齐，**无需 alias**：
```bash
sudo mkdir -p /var/www/iotlcm/www
sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
```
```nginx
server {
listen 80;
server_name _;
root /var/www/iotlcm/www;
location /docs/ {
try_files $uri $uri.html $uri/ $uri/index.html =404;
}
location = /docs {
return 301 /docs/;
}
}
```
此处 `root` 指向父目录、产物在 `docs/` 子目录下，`/docs/assets/app.js` 会自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
## nginx：根路径独占域名
若文档站独占一个域名、需要挂在 `/`，必须**改 `base` 后重新构建**：
```bash
sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
npm run build
```
```nginx
server {
listen 80;
server_name docs.example.com;
root /var/www/iotlcm-docs;
index index.html;
location / {
try_files $uri $uri.html $uri/ =404;
}
}
```
::: danger 不要只改服务器配置
`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。详见 [路径前缀必读](./path-prefix)。
:::
## Apache
需要启用 `mod_rewrite`，用 `.htaccess` 做 cleanUrls 映射：
```apache
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /docs/
# 已存在的文件/目录直接返回
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
# 无后缀路径映射到 .html 或 index.html
RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^(.+)$ $1.html [L]
RewriteCond %{REQUEST_FILENAME}/index.html -f
RewriteRule ^(.+)$ $1/index.html [L]
</IfModule>
```
产物目录放置方式与 nginx 子路径方案一致：`/var/www/html/docs/`。
## Caddy
Caddy 配置更简洁，`try_files` 语义与 nginx 类似：
```caddyfile
example.com {
handle_path /docs/* {
root * /var/www/iotlcm-docs
try_files {path} {path}.html {path}/index.html
file_server
}
}
```
或产物放在子目录、不做前缀处理：
```caddyfile
example.com {
root * /var/www/iotlcm/www
try_files {path} {path}.html {path}/index.html
file_server
}
```
## 对象存储 / CDN
产物是纯静态文件，可直接上传到 S3 / OSS / MinIO 等：
```bash
npm run build
# 上传 .vitepress/dist 全部内容到桶内 docs/ 前缀下
```
要点：
- 上传时保持 `/docs/` 前缀（或改 `base` 后重新构建）
- 配置**默认首页**为 `docs/index.html`
- 配置 **404 页面**为 `docs/404.html`（产物已自带）
- `cleanUrls: true` 意味着页面 URL 不带 `.html`，需对象存储支持「无后缀映射到 .html」，否则需关闭 `cleanUrls` 重新构建
::: tip 关闭 cleanUrls
若对象存储不支持无后缀映射，编辑 `.vitepress/config.mts` 把 `cleanUrls: true` 改为 `false`，重新构建后页面 URL 会带 `.html` 后缀。
:::
## pnpm / yarn
仓库同时提供 `package-lock.json` 与 `pnpm-lock.yaml`。使用 pnpm：
```bash
pnpm install --frozen-lockfile
pnpm run build
```
npm 与 pnpm 二选一即可，**不要混用**（会产生不一致的 `node_modules`）。
docs/deploy/troubleshooting.md
+243
View File
@@ -0,0 +1,243 @@
---
title: 故障排查
description: 部署与运行中的常见问题及处理
outline: deep
---
# 故障排查
## 通用排查
```bash
docker compose ps # 容器状态
docker compose logs --tail=100 <服务> # 最近日志
docker compose logs -f <服务> # 跟随日志
docker compose exec <服务> sh # 进容器
```
## 启动类
### MySQL 一直不 healthy
**现象**：`iotlcm-mysql` 反复重启或一直 `starting`，其余服务不启动。
```bash
docker compose logs mysql | tail -50
```
| 日志关键词 | 原因 | 处理 |
| --- | --- | --- |
| `Access denied` | root 口令与旧数据卷不一致 | 改 `.env` 与卷内一致，或清空 `data/mysql` 重建 |
| `Can't create/write to file` | 目录权限 | `sudo chown -R 999:999 data/mysql` |
| `No space left on device` | 磁盘满 | 清理磁盘 |
| `Can't open shared library` | 架构不匹配 | 确认镜像与宿主机架构一致 |
### schema 初始化失败
```bash
docker compose logs mysql | grep -iE 'error' | head -30
```
| 原因 | 处理 |
| --- | --- |
| `MYSQL_APP_PASSWORD` 未设置，`04-users.sh` 退出 | 补上后清空 `data/mysql` 重建 |
| `MYSQL_ADMIN_PASSWORD` 未设置，`05-reset-passwords.sh` 退出 | 同上 |
| SQL 脚本语法问题 | 单独执行该脚本定位 |
::: warning 改脚本后必须清空数据卷
MySQL 只在 `data/mysql` 为空时执行 `schema/`，文件改了不会自动重跑：
```bash
docker compose down && sudo rm -rf ./data/mysql && docker compose up -d
```
:::
### 业务服务反复重启
```bash
docker compose logs --tail=80 admin-svr
```
| 报错 | 原因 | 处理 |
| --- | --- | --- |
| `possible config files "config" not found` | `config/` 不存在或挂载失败 | `cp -r config.example config`，确认 `config/admin-svr/config.yaml` 存在 |
| `dial tcp mysql:3306: connection refused` | MySQL 未就绪 | 等 MySQL healthy |
| `Access denied for user 'u_iotlcm'` | 应用账号口令与库内不一致 | 确认 `.env` 的 `MYSQL_APP_PASSWORD` 与初始化时一致 |
| `panic: unsupported provider xxx` | 通道模板与镜像版本不匹配 | 确认镜像版本与 schema 版本配套 |
## 功能类
### 登录后提示未授权 / 接口 401
**原因**：`JWT_SIGNING_KEY` 在服务间不一致。
确认 `admin-svr`、`openapi`、`app-server` 三份配置的 `jwt.signingKey` 都引用 `${JWT_SIGNING_KEY}` 且 `.env` 有值，然后重启：
```bash
docker compose restart admin-svr openapi app-server
```
### 登录成功但页面空白 / 菜单不显示
1. 浏览器 F12 看 Network 有无 4xx/5xx
2. 检查菜单数据：
```bash
docker compose exec mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm -e "SELECT COUNT(*) FROM sys_menu WHERE status=0;"'
```
菜单为 0 说明种子数据未导入，需重建库。
3. 检查角色菜单关联：
```bash
docker compose exec mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm -e "SELECT COUNT(*) FROM sys_role_menu;"'
```
### 卡信息页通道列空白 / 筛选无选项
**原因**：Mock 通道未插入。
```bash
docker compose exec mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm -e "SELECT channel_id, channel_name FROM t_sim_channels;"'
```
为空则手工执行种子脚本：
```bash
docker compose exec -T mysql sh -c \
'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm' < schema/08-seed-mock-channel.sql
```
### 批次执行一直失败
按顺序排查：
1. **挡板是否启动**（无真实运营商时）
```bash
docker compose ps | grep onelink-mock
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api.json
```
未启动则 `docker compose --profile with-mock up -d`。
2. **worker-svr 是否连上 RabbitMQ**
```bash
docker compose logs worker-svr | grep -i 'rabbit\|amqp' | tail -20
```
3. **upstream-chan 是否能连到上游**
```bash
docker compose logs upstream-chan --tail=50
```
4. **是否被运营商限流**
检查 worker-svr 日志中的 `rate limit`、`429`、`12021`。核对 `batch.inbound.upstreamRateLimit` 的 QPS 是否超过上游配额。
### 历史流量查询无数据
**原因**：TDengine 未配置或不可达。
```bash
docker compose logs worker-svr | grep -i 'tdengine\|taos' | tail -20
```
确认 `.env` 的 `TDENGINE_*` 已填，且 WebSocket 端口（默认 6041）可达。不用该功能留空即可。
### 短信发不出去
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:11190/healthz
docker compose logs sms --tail=50
```
| 报错 | 原因 |
| --- | --- |
| `InvalidAccessKeyId` | `.env` 中 AK 未填或错误 |
| `isv.SMS_SIGNATURE_ILLEGAL` | `signName` 与服务商审核签名不一致 |
| `isv.SMS_TEMPLATE_ILLEGAL` | 模板 ID 未审核通过 |
| `缺少 config.templateId` | 场景模板库未配置，调用方需自带 templateId |
### 图片上传失败 / 不显示
```bash
ls -la data/upload/
sudo chown -R 1000:1000 data/upload
docker compose restart admin-svr admin-ui
```
## 性能类
### CPU 被 worker-svr 打满
**原因**：定时任务开启全量同步，大量卡片并发查询上游。
1. 降低并发与限流：
```yaml
batch:
inbound:
upstreamConcurrency: 50 # 从 300 降低
upstreamBatchSize: 1
```
2. 演示 / 试用环境直接停用定时任务：
```bash
docker compose exec mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" db_iotlcm -e "UPDATE sys_job SET status=1;"'
```
种子数据中定时任务默认已全部停用（`status=1`）。
### 磁盘持续增长
```bash
du -sh data/* | sort -rh
```
| 目录 | 处理 |
| --- | --- |
| `data/logs` | 清理旧日志，见[升级与备份](operations) |
| `data/upload` | 检查异常大的上传文件 |
| `data/mysql` | 数据库增长正常，关注 binlog |
| `data/redis` | AOF 文件，正常 |
## 网络类
### 容器间无法互访
```bash
docker network inspect iotlcm-network
docker compose exec admin-svr sh -c 'nc -zv mysql 3306'
```
配置中应使用 `mysql:3306`、`redis:6379` 这样的服务名，不要写 `127.0.0.1`。
### 宿主机访问不了 127.0.0.1 绑定的服务
`admin-svr`、`admin-ui`、`openapi`、`app-server`、`app-web`、`docs` 默认只绑 `127.0.0.1`。对外访问需：
1. 用 `--profile with-nginx` 启动反向代理，或
2. 宿主机 nginx 转发到 `127.0.0.1:<端口>`
::: danger 不要直接把端口改成 0.0.0.0
这会把管理端、数据库等内部服务暴露到公网。
:::
## 求助时提供的信息
```bash
docker compose version
docker version --format '{{.Server.Version}}'
docker compose ps
docker compose logs --tail=200 <服务名>
df -h && free -h
```