From fd42b5976eb1a598a2fe8b5c7a29459c4768fdf5 Mon Sep 17 00:00:00 2001 From: MiFaZhan Date: Mon, 2 Nov 2026 14:57:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=EF=BC=88?= =?UTF-8?q?=E7=94=A8=E6=88=B7=E8=A7=86=E8=A7=92=EF=BC=8C=E5=90=AB=E6=89=8B?= =?UTF-8?q?=E5=86=8C=E8=B7=B3=E8=BD=AC=EF=BC=89+=20=E5=8E=BB=E6=8E=89?= =?UTF-8?q?=E3=80=8C=E5=BC=80=E6=BA=90=E7=89=88=E3=80=8D=E6=8E=AA=E8=BE=9E?= =?UTF-8?q?=20+=20=E5=8D=95=E7=AB=AF=E5=8F=A3=E5=85=A5=E5=8F=A3=205051?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 增单端口入口段 --- .gitea/workflows/mirror-to-gitee.yml | 2 +- README.md | 110 ++++++++++++++++----------- deploy/README.md | 28 ++++++- deploy/config/gateway/nginx.conf | 67 ++++++++++++++++ deploy/docker-compose.yml | 21 ++++- docs/docs/deploy/index.md | 17 +++-- docs/docs/deploy/optional.md | 32 +++++++- 7 files changed, 220 insertions(+), 57 deletions(-) create mode 100644 deploy/config/gateway/nginx.conf diff --git a/.gitea/workflows/mirror-to-gitee.yml b/.gitea/workflows/mirror-to-gitee.yml index f077aaa..a5b3880 100644 --- a/.gitea/workflows/mirror-to-gitee.yml +++ b/.gitea/workflows/mirror-to-gitee.yml @@ -47,7 +47,7 @@ jobs: curl -sS -X POST \ "https://gitee.com/api/v5/enterprises/${DST_OWNER}/repos?access_token=${DST_TOKEN}" \ -H 'Content-Type: application/json' \ - -d "{\"name\":\"${REPO_NAME}\",\"auto_init\":false,\"description\":\"iotLCM 物联网卡全生命周期管理平台（开源版）\"}" \ + -d "{\"name\":\"${REPO_NAME}\",\"auto_init\":false,\"description\":\"iotLCM 物联网卡全生命周期管理平台\"}" \ -o /tmp/repo-create.json -w '建仓 HTTP %{http_code}\n' || true head -c 300 /tmp/repo-create.json 2>/dev/null; echo else diff --git a/README.md b/README.md index b0a179a..e1be137 100644 --- a/README.md +++ b/README.md @@ -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 项目衍生，保留其原始许可： | 目录 | 上游 | 许可 | | --- | --- | --- | diff --git a/deploy/README.md b/deploy/README.md index 69a5170..aea74df 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -30,12 +30,32 @@ docker compose logs -f mysql ## 可选服务 ```bash -docker compose --profile with-mock up -d # 运营商接口挡板 -docker compose --profile with-bot up -d # 飞书通知（运维自用） -docker compose --profile with-nginx up -d # 自带反向代理 +docker compose --profile with-gateway up -d # 单端口入口（默认对外 5051） +docker compose --profile with-mock up -d # 运营商接口挡板 +docker compose --profile with-bot up -d # 飞书通知（运维自用） +docker compose --profile with-nginx up -d # 多域名反向代理（对外 80） ``` -多个 profile 可组合：`--profile with-mock --profile with-nginx up -d` +多个 profile 可组合：`--profile with-gateway --profile with-mock up -d` + +### 单端口入口（with-gateway） + +只暴露一个端口时用它。容器内监听 80，宿主机端口由 `GATEWAY_PORT` 控制（默认 **5051**）： + +```bash +docker compose --profile with-gateway up -d +# 或换端口 +GATEWAY_PORT=8088 docker compose --profile with-gateway up -d +``` + +| 路径 | 去向 | +| --- | --- | +| `/` | 管理端（admin-ui，内部已代理 `/api/` 到 admin-svr） | +| `/docs/` | 文档站 | +| `/openapi/` | 对外 API | +| `/route/open/` | 运营商能力代理（白名单 / 共享 Token） | + +配置见 `config/gateway/nginx.conf`。小程序 / H5 端的静态资源是根路径部署的，不能挂在同一域名的子路径下，需要单独域名或端口（见 `with-nginx` 的 app 段）。 `with-bot` 是把全量同步等运维事件推送到飞书群的**内部运维工具**，不是平台功能。它需要你自己的飞书自建应用凭证（`config/bot/config.yaml` 的 `appId` / `appSecret` / `chatId`），没填就不启动。 diff --git a/deploy/config/gateway/nginx.conf b/deploy/config/gateway/nginx.conf new file mode 100644 index 0000000..e004e73 --- /dev/null +++ b/deploy/config/gateway/nginx.conf @@ -0,0 +1,67 @@ +# 单端口入口（默认对外 5051） +# +# 用途：把管理端、文档站、OpenAPI 收在一个端口下，便于在外部网关 / DNS +# 只暴露一个地址。编排里由 gateway 服务（profile: with-gateway）加载本文件， +# 容器内监听 80，宿主机发布端口用 GATEWAY_PORT 控制（默认 5051）。 +# +# docker compose --profile with-gateway up -d +# GATEWAY_PORT=8088 docker compose --profile with-gateway up -d +# +# 路由： +# / -> 管理端（admin-ui，内部已代理 /api/ 到 admin-svr） +# /docs/ -> 文档站（docs） +# /openapi/ -> 对外 API（openapi） +# /route/open/ -> 运营商能力代理（openapi） +# +# 小程序 / H5 端的静态资源是根路径部署的，不能挂在同一域名的子路径下， +# 需要单独域名或单独端口（见 config/nginx/iotlcm.conf 的 app 段）。 + +upstream gw_admin_ui { server admin-ui:80; } +upstream gw_openapi { server openapi:8000; } +upstream gw_docs { server docs:80; } + +server { + listen 80; + + charset utf-8; + client_max_body_size 200m; + + access_log /var/log/nginx/access_gateway.log; + error_log /var/log/nginx/error_gateway.log; + + 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; + proxy_read_timeout 120s; + proxy_send_timeout 120s; + + # ---------- 文档站 ---------- + location = /docs { + return 301 /docs/; + } + + location ^~ /docs/ { + proxy_pass http://gw_docs; + } + + # ---------- 对外 API：版本化接口 ---------- + location ^~ /openapi/ { + proxy_pass http://gw_openapi; + } + + # ---------- 对外 API：运营商能力代理（白名单 / 共享 Token）---------- + location ^~ /route/open/ { + proxy_pass http://gw_openapi; + } + + # ---------- 管理端（含 /api/ 与 /upload/，由 admin-ui 自行转发）---------- + location / { + proxy_pass http://gw_admin_ui; + } + + gzip on; + gzip_min_length 1k; + gzip_types text/plain text/css application/json application/javascript application/xml image/svg+xml; +} diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml index 9d8d6cb..309cb98 100644 --- a/deploy/docker-compose.yml +++ b/deploy/docker-compose.yml @@ -410,7 +410,7 @@ services: container_name: iotlcm-nginx restart: always ports: - - "80:80" + - "${NGINX_HTTP_PORT:-80}:80" volumes: - ./config/nginx:/etc/nginx/conf.d:ro - ./data/logs/nginx:/var/log/nginx @@ -425,6 +425,25 @@ services: profiles: - with-nginx + # 单端口入口：管理端 + 文档站 + OpenAPI 收在一个端口（默认 5051）对外 + gateway: + image: 'crpi-qflrqrxoohlkkvgc.cn-chengdu.personal.cr.aliyuncs.com/iotlcm/iotlcm:nginx-1.30' + container_name: iotlcm-gateway + restart: always + ports: + - "${GATEWAY_PORT:-5051}:80" + volumes: + - ./config/gateway:/etc/nginx/conf.d:ro + - ./data/logs/gateway:/var/log/nginx + networks: + - iotlcm-network + depends_on: + - admin-ui + - openapi + - docs + profiles: + - with-gateway + networks: iotlcm-network: driver: bridge diff --git a/docs/docs/deploy/index.md b/docs/docs/deploy/index.md index b6df808..22d3e80 100644 --- a/docs/docs/deploy/index.md +++ b/docs/docs/deploy/index.md @@ -16,18 +16,23 @@ cd iotlcm/deploy ```text deploy/ ├── docker-compose.yml # 服务编排（含默认口令与端口） -├── config/ # 各服务配置，10 份，已带可用默认值 -└── schema/ # 数据库初始化脚本，13 个，首次启动自动执行 +├── config/ # 各服务配置 + gateway / nginx 两种入口配置 +├── schema/init.sql # MySQL 初始化（单文件，95 表 + 种子数据） +├── tdengine-init/ # 时序库建库建表（首次启动自动执行） +└── data/ # 运行数据，首次启动自动创建 ``` ## 部署内容 | 类别 | 服务 | | --- | --- | -| 基础组件 | MySQL、Redis、RabbitMQ、Consul | -| 管理端 | admin-svr（后端）、admin-ui（前端） | -| 对外接口 | openapi | -| 小程序 / H5 | app-server（后端）、app-web（前端） | +| 基础组件 | MySQL、Redis、RabbitMQ、Consul、TDengine（流量历史） | +| 管理端 | admin-svr（后端 8008）、admin-ui（前端 8009） | +| 对外接口 | openapi（8000） | +| 小程序 / H5 | app-server（8010）、app-web（8018） | +| 通道 | upstream-chan（8110 / 8310）、upstream-proxy（8510） | +| 异步与配套 | worker-svr、sms（11190）、docs（8019） | +| 可选 | onelink-mock（接口挡板）、bot（飞书通知）、nginx（多域名入口）、gateway（单端口入口 5051） | | 运营商对接 | upstream-chan（协议适配）、upstream-proxy（缓存转发） | | 异步任务 | worker-svr（批次执行、全量同步） | | 配套 | sms（短信）、docs（本文档站） | diff --git a/docs/docs/deploy/optional.md b/docs/docs/deploy/optional.md index 50feff2..89878b4 100644 --- a/docs/docs/deploy/optional.md +++ b/docs/docs/deploy/optional.md @@ -88,6 +88,36 @@ 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`。 + +::: tip 小程序 / H5 端不在单端口内 +`app-web` 的静态资源是根路径部署的，挂到子路径会白屏。小程序端需要单独域名或端口，用下面的反向代理方式。 +::: + ## 反向代理 ### 用途 @@ -110,7 +140,7 @@ bot 读取 `worker-svr` 生成的全量同步归档（`./data/logs/worker-svr/fu docker compose --profile with-nginx up -d ``` -默认监听 80，改 `docker-compose.yml` 的 `NGINX_HTTP_PORT` 可调整。 +默认监听 80，对外端口由 `NGINX_HTTP_PORT` 控制：`NGINX_HTTP_PORT=8080 docker compose --profile with-nginx up -d`。 ### 使用宿主机 nginx