iotlcm/docs/docs/deploy/optional.md

title, description, outline

title	description	outline
可选服务	运营商接口挡板、飞书通知与反向代理	deep

可选服务

以下服务默认不启动，按需通过 profile 开启。

运营商接口挡板

用途

模拟中国移动 OneLink 接口。没有真实运营商环境时，靠它跑通完整链路：

admin-svr → worker-svr → upstream-chan → onelink-mock

不开挡板时，upstream-chan 会尝试连接真实运营商接口。没有凭据则批次执行、状态同步、流量查询全部失败。

启动

docker compose --profile with-mock up -d

验证：

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 配置中已预置指向：

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 通道，避免卡片误挂

docker compose --profile with-mock stop onelink-mock

飞书通知

用途

把全量同步完成、失败告警等运维事件推送到飞书群。

准备

在飞书开放平台创建自建应用，获取 appId、appSecret 与目标群的 chatId，填入 docker-compose.yml：

FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=xxxxxxxx
FEISHU_CHAT_ID=oc_xxxxxxxx

启动

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/ 后端

启动

docker compose --profile with-nginx up -d

默认监听 80，改 docker-compose.yml 的 NGINX_HTTP_PORT 可调整。

使用宿主机 nginx

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

::: warning 宿主机 nginx 无法解析容器名 需要把 upstream 里的服务名换成宿主机地址：

# 容器内写法
server admin-svr:8008;
# 宿主机写法
server 127.0.0.1:8008;

:::

启用 HTTPS

自带配置未包含证书，启用需三步：

1. 准备证书，放入 data/certs/
2. 在 server 块加入 SSL 配置：

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 跳转：

volumes:
  - ./data/certs:/etc/nginx/certs:ro

server {
    listen 80;
    server_name admin.your-domain.example.com;
    return 301 https://$host$request_uri;
}

组合启动

多个 profile 可同时启用：

docker compose --profile with-mock --profile with-nginx up -d

查看指定 profile 下的服务清单：

docker compose --profile with-mock config --services