docs: 重写 README（用户视角，含手册跳转）+ 去掉「开源版」措辞 + 单端口入口 5051
README - 标题去掉「（开源版）」：对使用者就是 iotLCM - 新增「文档」表：使用手册（Web 端 / 小程序端）、部署手册、OpenAPI 合同、 共享 Token 接口，全部指向仓内 docs/ 路径；并给出部署后的文档站地址 - 补功能概览、服务构成（带镜像 tag）、从源码构建、版本与镜像、许可 去措辞 - Gitee 建仓描述同步去掉「（开源版）」 单端口入口（新增，对外默认 5051） - deploy/config/gateway/nginx.conf：/ → 管理端、/docs/ → 文档站、 /openapi/ 与 /route/open/ → openapi - compose 增加 gateway 服务（profile with-gateway），端口由 GATEWAY_PORT 控制 实测：/ 200、/docs/ 200（含静态资源）、/api/agent/dept/list 200、 /api/system/auth/login 返回后端真实 JSON - nginx profile 的 80 端口改为可配 NGINX_HTTP_PORT（文档早有提及但 compose 写死） - 部署手册概览页修正过期内容（schema 单文件、服务清单补全）、optional 增单端口入口段
This commit is contained in:
MiFaZhan
@@ -1,51 +1,76 @@
|
||||
# iotLCM —— 物联网卡全生命周期管理平台（开源版）
|
||||
# iotLCM 物联网卡全生命周期管理平台
|
||||
|
||||
一站式物联网 SIM 卡管理平台：卡片从运营商渠道入库 → 划拨给代理商 → 激活 / 续费 / 停机 → 流量与状态同步 → 销户。对接中国移动 OneLink、中国电信 5G CMP、中国联通 10646 等运营商接口，并通过共享 Token 模式接入多家三方渠道商。
|
||||
iotLCM 面向物联网 SIM 卡的全生命周期管理：卡片从运营商渠道入库 → 划拨给代理商 → 激活 / 续费 / 停机 → 流量与状态同步 → 销户。
|
||||
|
||||
**单仓多服务**：平台全部后端服务、前端应用、文档站与部署编排都在本仓，一次 clone 即可获得完整源码。
|
||||
平台对接**中国移动 OneLink**、**中国电信 5G CMP**、**中国联通 10646** 等运营商接口，支持以共享 Token 模式接入三方渠道商，并提供对外的 OpenAPI 服务。
|
||||
|
||||
## 目录
|
||||
## 文档
|
||||
|
||||
| 目录 | 说明 | 镜像 |
|
||||
| 手册 | 内容 | 入口 |
|
||||
| --- | --- | --- |
|
||||
| `admin-svr/` | 管理端后端（GoFrame）：卡信息、通信管理、资费、告警工单、统计、账号治理 | `iotlcm-admin-svr` |
|
||||
| `admin-ui/` | 管理端前端（Vue 3 + Vben Admin） | `iotlcm-admin-ui` |
|
||||
| `openapi/` | 对外 API 网关：V3 接口、旧版兼容、运营商能力代理 | `iotlcm-openapi` |
|
||||
| `worker-svr/` | 异步执行：RabbitMQ 消费者、全量同步、批量任务 | `iotlcm-worker-svr` |
|
||||
| `upstream-chan/` | 运营商 / 三方渠道对接层（OneLink、CMP、10646、共享 Token） | `iotlcm-upstream-chan` |
|
||||
| `upstream-proxy/` | 通道缓存转发层（挡在 chan 前面的本地缓存） | `iotlcm-upstream-proxy` |
|
||||
| `app/server/` | 用户端服务（GoFrame） | `iotlcm-app-server` |
|
||||
| `app/app/` | 用户端前端（uni-app，基于 unibest，MIT） | `iotlcm-app-web` |
|
||||
| `sms/` | 短信 HTTP / gRPC 服务（阿里云、腾讯云） | `iotlcm-sms` |
|
||||
| `bot/` | 飞书通知机器人（运维自用，可选） | `iotlcm-bot` |
|
||||
| `docs/` | 文档站（VitePress）：使用手册 + OpenAPI 合同 + 部署手册 | `iotlcm-docs` |
|
||||
| `onelink-mock/` | OneLink 接口挡板（联调 / 演示，可选） | `iotlcm-onelink-mock` |
|
||||
| `deploy/` | Docker Compose 编排与数据库初始化 | 参考 `deploy/README.md` |
|
||||
| **使用手册 · Web 管理端** | 查卡、智能诊断、业务受理、套餐与定价、库存出入库、通道管理、企业用户与角色、工单、API 凭证、常见问题 | [`docs/docs/manual/web/`](docs/docs/manual/web/index.md) |
|
||||
| **使用手册 · 小程序端** | 首页公开查卡、卡片排查、客户管理与划拨、工单、批次执行日志、消息与个人中心 | [`docs/docs/manual/mini-program/`](docs/docs/manual/mini-program/index.md) |
|
||||
| **部署手册** | 推荐环境、一键部署、配置说明、离线部署、拆分部署、自建镜像、运维与排错 | [`docs/docs/deploy/`](docs/docs/deploy/index.md) |
|
||||
| **OpenAPI 合同** | 鉴权、V3 接口、旧版兼容接口、运营商能力代理 | [`docs/docs/openapi/`](docs/docs/openapi/index.md) |
|
||||
| **共享 Token 接口** | 共享 Token 获取与白名单转发 | [`docs/docs/openapi/operator/`](docs/docs/openapi/operator/index.md) |
|
||||
|
||||
每个子目录都有自己的 `README.md`，说明该服务的职责、配置项与本地运行方式。
|
||||
平台跑起来后，文档站随平台一起提供：`http://<平台地址>:8019/docs/`。
|
||||
|
||||
## 快速开始（只跑起来）
|
||||
## 快速开始
|
||||
|
||||
不需要编译，直接用预构建镜像拉起整栈：
|
||||
需要 Docker 20.10+ 与 Docker Compose v2，单机 4 核 / 8 GB 起。预构建镜像已就绪，不需要编译：
|
||||
|
||||
```bash
|
||||
git clone <本仓库地址> iotlcm
|
||||
git clone <仓库地址> iotlcm
|
||||
cd iotlcm/deploy
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
首次启动自动完成 MySQL 建库建表（95 张）、种子数据导入、时序库建表，实测 30 秒 ~ 1 分钟。
|
||||
首次启动自动完成建库建表、种子数据导入与时序库建表，约 1 分钟。启动完成后访问 `http://127.0.0.1:8009`。
|
||||
|
||||
默认账号 `admin`，口令见 `deploy/README.md`（**正式使用前必须修改**）。详细的端口、配置项、可选服务（挡板 / 飞书通知 / 反向代理）、离线部署与排错，见 `deploy/README.md` 与文档站 `docs/deploy/`。
|
||||
默认账号口令、端口清单、可选服务（接口挡板 / 飞书通知 / 反向代理）、修改口令与上线检查，见 [`deploy/README.md`](deploy/README.md) 与[部署手册](docs/docs/deploy/index.md)。
|
||||
|
||||
> 对外端口默认只监听 `127.0.0.1`，需要局域网或公网访问时，用 `deploy/` 里的 nginx 编排改绑定地址，或并入宿主机已有的反向代理。
|
||||
> 业务端口默认只绑定 `127.0.0.1`。需要局域网或公网访问时，用 `--profile with-nginx` 起反向代理，或改用 `--profile with-gateway` 的单端口入口（默认 5051）。
|
||||
|
||||
## 功能概览
|
||||
|
||||
| 域 | 能力 |
|
||||
| --- | --- |
|
||||
| 卡资产 | 卡信息、批量导入、入库 / 库存 / 出库、批量开停复机、续费、变更套餐、达量断网 |
|
||||
| 通信管理 | 通道与接入模板、运营商能力对接、共享 Token 接入三方渠道、通道缓存转发 |
|
||||
| 资费 | 套餐与流量池、定价、生效与到期策略 |
|
||||
| 代理商 | 代理商与分佣、划拨与回收 |
|
||||
| 数据同步 | 流量 / 状态 / IMEI 全量同步与增量对齐、历史账期时序数据 |
|
||||
| OpenAPI | V3 接口、旧版兼容接口、运营商能力代理（白名单转发 / 共享 Token） |
|
||||
| 运营 | 工单、预警、执行日志、审计、智能诊断 |
|
||||
| 端 | Web 管理端、小程序 / H5 用户端 |
|
||||
|
||||
## 服务构成
|
||||
|
||||
| 目录 | 说明 | 镜像 tag |
|
||||
| --- | --- | --- |
|
||||
| `admin-svr/` | 管理端后端（GoFrame） | `iotlcm-admin-svr` |
|
||||
| `admin-ui/` | 管理端前端（Vue 3 + Vben Admin） | `iotlcm-admin-ui` |
|
||||
| `openapi/` | 对外 API 网关 | `iotlcm-openapi` |
|
||||
| `worker-svr/` | 异步执行（RabbitMQ 消费者、全量同步、批量任务） | `iotlcm-worker-svr` |
|
||||
| `upstream-chan/` | 运营商 / 三方渠道对接层 | `iotlcm-upstream-chan` |
|
||||
| `upstream-proxy/` | 通道缓存转发层 | `iotlcm-upstream-proxy` |
|
||||
| `app/server/` | 用户端服务（GoFrame） | `iotlcm-app-server` |
|
||||
| `app/app/` | 用户端前端（uni-app，基于 unibest） | `iotlcm-app-web` |
|
||||
| `sms/` | 短信服务（HTTP / gRPC，阿里云 / 腾讯云） | `iotlcm-sms` |
|
||||
| `bot/` | 飞书通知机器人（运维自用，可选） | `iotlcm-bot` |
|
||||
| `docs/` | 文档站（VitePress）与 OpenAPI 合同 | `iotlcm-docs` |
|
||||
| `onelink-mock/` | OneLink 接口挡板（联调 / 演示，可选） | `iotlcm-onelink-mock` |
|
||||
| `deploy/` | Docker Compose 编排、数据库初始化、反向代理 / 单端口网关配置 | — |
|
||||
|
||||
各服务职责、配置项与本地运行方式见各自目录下的 `README.md`。
|
||||
|
||||
## 从源码构建
|
||||
|
||||
每个 Go 服务是独立模块（各自带 `go.mod`），在对应目录内构建：
|
||||
每个 Go 服务是独立模块，在对应目录内构建：
|
||||
|
||||
```bash
|
||||
cd worker-svr && go build -o out/ . # 其它 Go 服务同理
|
||||
cd worker-svr && go build -o out/ . # 其余 Go 服务同理
|
||||
```
|
||||
|
||||
前端：
|
||||
@@ -56,41 +81,38 @@ cd app/app && pnpm install && pnpm build
|
||||
cd docs && npm ci && npm run build
|
||||
```
|
||||
|
||||
或一键编译检查全部 Go 模块：
|
||||
一键编译全部 Go 服务 / 本地构建全部镜像：
|
||||
|
||||
```bash
|
||||
make build # 所有 Go 服务编译
|
||||
make images # 本地构建全部镜像
|
||||
make build # 编译检查
|
||||
make images # 构建镜像（REGISTRY / VERSION 可覆盖）
|
||||
```
|
||||
|
||||
构建镜像所需的 Dockerfile 位置与构建上下文，见 `docs/docs/deploy/build-image.md`。
|
||||
各服务的 Dockerfile 位置与构建上下文见[自建镜像](docs/docs/deploy/build-image.md)。
|
||||
|
||||
## 发布与镜像
|
||||
## 版本与镜像
|
||||
|
||||
所有镜像发布到**同一个镜像仓库**，用 tag 区分服务与版本：
|
||||
镜像统一发布在同一个仓库，用 tag 区分服务与版本：
|
||||
|
||||
```text
|
||||
<镜像仓库>/iotlcm/iotlcm:iotlcm-worker-svr-v1.0.4
|
||||
└─ 仓库 ┘ └─ 服务名 ─┘└版本┘
|
||||
```
|
||||
|
||||
打 `v*` tag 会经由内网 CI 构建镜像并推送，见 `.gitea/workflows/`。
|
||||
| 服务 | 当前版本 |
|
||||
| --- | --- |
|
||||
| 除小程序线外 | `v1.0.4` |
|
||||
| `iotlcm-app-server` / `iotlcm-app-web` | `v1.0.2`（小程序线独立版本线） |
|
||||
|
||||
**小程序线（`app/`）是独立版本线**，不跟随平台 tag：
|
||||
升级时固定到具体版本，不要使用 `latest`。
|
||||
|
||||
| 服务 | 当前版本 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 其余业务服务 | `v1.0.4` | 跟随平台 tag |
|
||||
| `iotlcm-app-server` / `iotlcm-app-web` | **`v1.0.2`** | 直连版本号与功能一一对应，功能未变就不动版本 |
|
||||
## 反馈
|
||||
|
||||
CI 里用一张 `PIN` 表维护这条规则（`app|v1.0.2`）：平台发新 tag 时自动跳过 app，需要重建小程序线时单独触发
|
||||
`SERVICES=app VERSION=v1.0.2`。
|
||||
问题与建议请提 Issue，或联系平台维护者。
|
||||
|
||||
## 许可
|
||||
|
||||
本仓整体采用 [Apache License 2.0](LICENSE)。
|
||||
|
||||
以下子目录基于上游 MIT 项目衍生，保留其原始许可：
|
||||
本仓整体采用 [Apache License 2.0](LICENSE)。以下子目录基于上游 MIT 项目衍生，保留其原始许可：
|
||||
|
||||
| 目录 | 上游 | 许可 |
|
||||
| --- | --- | --- |
|
||||
|
||||
Reference in New Issue
Block a user