iotLCM

Appearance

可选服务 ​

以下服务默认不启动，按需通过 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，填入 docker-compose.yml：

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），该目录有数据后才会产生通知。

单端口入口 ​

用途 ​

只对外暴露一个端口（默认 5051），把管理端、文档站、OpenAPI 收在一起。适合外面还有一层网关 / DNS， 或者只想开放一个端口的环境。

路由 ​

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

启动 ​

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

配置见 config/gateway/nginx.conf。

小程序 / H5 端不在单端口内

app-web 的静态资源是根路径部署的，挂到子路径会白屏。小程序端需要单独域名或端口，用下面的反向代理方式。

反向代理 ​

用途 ​

把分散在各端口的服务统一到域名下按路径分流。宿主机已有 nginx 或面板时不需要。

域名与分流 ​

编辑 config/nginx/iotlcm.conf：

域名分流到
api.your-domain.example.comopenapi（/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，对外端口由 NGINX_HTTP_PORT 控制：NGINX_HTTP_PORT=8080 docker compose --profile with-nginx up -d。

使用宿主机 nginx ​

不启动容器时，把 config/nginx/iotlcm.conf 中的 upstream 与 location 段落复制到宿主机 nginx 配置。

宿主机 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;
  1. 给 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

iotLCM 文档中心