Files

T

- README：项目概览、快速开始、目录结构、重要提示
- 01 环境准备：硬件/系统/Docker 版本、镜像仓库、端口、防火墙、可选外部服务
- 02 配置说明：.env 必填与可选项、10 份应用配置逐项说明、启动前自检
- 03 启动与验证：首次初始化流程、状态检查、6 步验证清单、首次登录必做项
- 04 可选服务：挡板 onelink-mock、飞书 bot、自带 nginx（含 HTTPS）、组合启动
- 05 升级与备份：版本固定、升级回滚、备份脚本与恢复、日志清理、监控指标
- 06 故障排查：启动/功能/性能/网络四类共 20 个问题

2026-10-28 13:54:39 +08:00

4.0 KiB

Raw Blame History

可选服务

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

一、运营商接口挡板（onelink-mock）

用途

模拟中国移动 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 页面。

对接真实运营商

删除或注释 upstream-chan 配置里的 sim_yd_mock_v5 段
在平台「通道管理」中录入真实运营商通道（AppKey、AppSecret、接口地址）
停用 Mock 通道，避免卡片误挂到 Mock 上

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

二、飞书通知（bot）

用途

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

准备

在飞书开放平台创建自建应用，获取：

项	获取方式
`appId` / `appSecret`	应用凭证页面
`chatId`	目标群的会话 ID

填入 .env：

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）

用途

把分散在各端口的服务统一到域名下按路径分流。宿主机已有 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 端口，改 .env 的 NGINX_HTTP_PORT 可调整。

使用宿主机 nginx

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

需注意：

宿主机 nginx 无法解析 compose 内的服务名，upstream 要改为 127.0.0.1:<端口>
例如 server admin-svr:8008; → server 127.0.0.1:8008;

HTTPS

自带 nginx 配置未包含证书。启用 HTTPS 需：

准备证书文件
在 iotlcm.conf 的 server 块加入：

listen 443 ssl;
ssl_certificate     /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;

在 compose 的 nginx 服务增加证书目录挂载：

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

增加 80 → 443 跳转：

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

4.0 KiB Raw Blame History Unescape Escape