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 增单端口入口段
chore: 移除一次性探测/清理工作流（Gitee 删除需 projects 权限，API 侧 403）
2026-11-02 14:57:57 +08:00 · 2026-11-02 14:25:34 +08:00 · 2026-11-02 14:24:18 +08:00 · 2026-11-02 14:23:03 +08:00 · 2026-11-02 14:22:00 +08:00 · 2026-11-02 14:20:13 +08:00
12 changed files with 292 additions and 75 deletions
@@ -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
@@ -69,6 +69,27 @@ jobs:
            echo "----- 推送尝试 $attempt/5"
            if git push --mirror "https://${DST_USER}:${DST_TOKEN}@${DST}" 2>&1; then
              echo "✅ 已同步到 Gitee"
+
+              # 推送后校验：远端 main 与 tag 集合必须与本地一致
+              # （避免“绿了但其实没推上去” —— Gitee 限流时容易发生）
+              LOCAL_MAIN=$(git rev-parse refs/heads/main 2>/dev/null || true)
+              REMOTE_MAIN=$(git ls-remote "https://${DST_USER}:${DST_TOKEN}@${DST}" refs/heads/main | awk '{print $1}')
+              LOCAL_TAGS=$(git for-each-ref --format='%(refname:short)' refs/tags | sort | tr '\n' ' ')
+              REMOTE_TAGS=$(git ls-remote --tags "https://${DST_USER}:${DST_TOKEN}@${DST}" \
+                | awk '{print $2}' | sed 's#refs/tags/##' | grep -v '\^{}$' | sort | tr '\n' ' ')
+              echo "本地 main: ${LOCAL_MAIN:-<无>}"
+              echo "远端 main: ${REMOTE_MAIN:-<无>}"
+              echo "本地 tag: ${LOCAL_TAGS:-<无>}"
+              echo "远端 tag: ${REMOTE_TAGS:-<无>}"
+              if [ -n "$LOCAL_MAIN" ] && [ "$LOCAL_MAIN" != "$REMOTE_MAIN" ]; then
+                echo "❌ 校验失败：远端 main 与本地不一致"
+                exit 1
+              fi
+              if [ "${LOCAL_TAGS% }" != "${REMOTE_TAGS% }" ]; then
+                echo "❌ 校验失败：远端 tag 与本地不一致"
+                exit 1
+              fi
+              echo "✅ 校验通过：Gitee 端 main 与 tag 均已对齐"
              exit 0
            fi
            wait_s=$((attempt * 30))
@@ -15,25 +15,26 @@ BASE_REGISTRY ?= docker.io/library

 GO_MODULES := admin-svr/server app/server bot onelink-mock openapi sms upstream-chan upstream-proxy worker-svr

-# 目录|镜像名|构建上下文|Dockerfile
+# 目录|镜像名|构建上下文|Dockerfile|固定版本（留空=跟随 VERSION）
+# 小程序线 app 固定 v1.0.2：版本号与功能一一对应，平台发新 tag 时不跟着动。
 IMAGE_MAP := \
-	admin-svr|iotlcm-admin-svr|admin-svr/server|build/Dockerfile \
-	admin-ui|iotlcm-admin-ui|admin-ui|vue/build/Dockerfile \
-	openapi|iotlcm-openapi|openapi|build/Dockerfile \
-	worker-svr|iotlcm-worker-svr|worker-svr|build/Dockerfile \
-	upstream-chan|iotlcm-upstream-chan|upstream-chan|build/Dockerfile \
-	upstream-proxy|iotlcm-upstream-proxy|upstream-proxy|build/Dockerfile \
-	app|iotlcm-app-server|app/server|Dockerfile \
-	app|iotlcm-app-web|app/app|Dockerfile \
-	sms|iotlcm-sms|sms|build/Dockerfile \
-	bot|iotlcm-bot|bot|Dockerfile \
-	docs|iotlcm-docs|docs|Dockerfile \
-	onelink-mock|iotlcm-onelink-mock|onelink-mock|Dockerfile
+	admin-svr|iotlcm-admin-svr|admin-svr/server|build/Dockerfile| \
+	admin-ui|iotlcm-admin-ui|admin-ui|vue/build/Dockerfile| \
+	openapi|iotlcm-openapi|openapi|build/Dockerfile| \
+	worker-svr|iotlcm-worker-svr|worker-svr|build/Dockerfile| \
+	upstream-chan|iotlcm-upstream-chan|upstream-chan|build/Dockerfile| \
+	upstream-proxy|iotlcm-upstream-proxy|upstream-proxy|build/Dockerfile| \
+	app|iotlcm-app-server|app/server|Dockerfile|v1.0.2 \
+	app|iotlcm-app-web|app/app|Dockerfile|v1.0.2 \
+	sms|iotlcm-sms|sms|build/Dockerfile| \
+	bot|iotlcm-bot|bot|Dockerfile| \
+	docs|iotlcm-docs|docs|Dockerfile| \
+	onelink-mock|iotlcm-onelink-mock|onelink-mock|Dockerfile|

 .PHONY: help build test images docs clean

 help:
-	@sed -n '2,12p' Makefile | sed 's/^# \{0,1\}//'
+	@grep -E '^#   make' Makefile | sed 's/^#   //'

 build:
 	@set -e; for m in $(GO_MODULES); do \
@@ -50,15 +51,16 @@ test:

 images:
 	@set -e; echo "镜像前缀: $(REGISTRY)   版本: $(VERSION)"; \
-	echo "$(IMAGE_MAP)" | tr ' ' '\n' | while IFS='|' read -r dir img ctx df; do \
+	echo "$(IMAGE_MAP)" | tr ' ' '\n' | while IFS='|' read -r dir img ctx df pin; do \
 		[ -z "$$dir" ] && continue; \
-		echo ""; echo "==> $$img:$$VERSION  (context=$$ctx  dockerfile=$$df)"; \
+		v="$${pin:-$(VERSION)}"; \
+		echo ""; echo "==> $$img:$$v  (context=$$ctx  dockerfile=$$df$${pin:+  [固定版本]})"; \
 		docker build -f "$$ctx/$$df" \
 			--build-arg BASE_REGISTRY="$(BASE_REGISTRY)" \
-			--build-arg BuildVersion="$(VERSION)" \
+			--build-arg BuildVersion="$$v" \
 			--build-arg CommitID="$$(git rev-parse --short=7 HEAD)" \
 			--build-arg BuildTime="$$(date -u +%FT%TZ)" \
-			-t "$(REGISTRY):$$img-$(VERSION)" "$$ctx"; \
+			-t "$(REGISTRY):$$img-$$v" "$$ctx"; \
 	done

 docs:
@@ -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,31 +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`（小程序线独立版本线） |
+
+升级时固定到具体版本，不要使用 `latest`。
+
+## 反馈
+
+问题与建议请提 Issue，或联系平台维护者。

 ## 许可

-本仓整体采用 [Apache License 2.0](LICENSE)。
-
-以下子目录基于上游 MIT 项目衍生，保留其原始许可：
+本仓整体采用 [Apache License 2.0](LICENSE)。以下子目录基于上游 MIT 项目衍生，保留其原始许可：

 | 目录 | 上游 | 许可 |
 | --- | --- | --- |
@@ -2,6 +2,9 @@

 iotLCM 物联网卡全生命周期管理平台的**小程序端 + 用户端服务**。

+> **版本线独立**：本目录对应小程序线的 **v1.0.2**，不跟随平台 tag（平台当前为 v1.0.4）。
+> 功能变更时才提升本线版本，镜像 tag 仍为 `iotlcm-app-server-<版本>` / `iotlcm-app-web-<版本>`。
+
 - `app/` —— uni-app 小程序前端（基于 [unibest](https://github.com/unibest-tech/unibest)，MIT）
 - `server/` —— 用户端 GoFrame 服务（基于 XiuAdmin 框架，Apache-2.0）

@@ -18,7 +18,7 @@ docker compose up -d
 docker compose logs -f mysql
 ```

-启动完成后访问 `http://<宿主机IP>:8009`：
+启动完成后在本机访问 `http://127.0.0.1:8009`（编排默认把业务端口绑定在 127.0.0.1，需要局域网/公网访问见下方「重要提示」）：

 | 项 | 值 |
 | --- | --- |
@@ -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`），没填就不启动。

@@ -54,7 +74,14 @@ crpi-.../iotlcm/iotlcm:iotlcm-app-server-v1.0.2

 tag 格式统一为 **`<服务名>-<版本>`**。

-当前业务版本：大部分服务为 `v1.0.4`，`iotlcm-app-server` / `iotlcm-app-web` 为 `v1.0.2`（源仓最新 tag 就是 v1.0.2）。
+当前业务版本：
+
+| 服务 | 版本 |
+| --- | --- |
+| 除 app 线外的全部业务服务 | `v1.0.4` |
+| `iotlcm-app-server` / `iotlcm-app-web` | **`v1.0.2`**（小程序线独立版本，不跟随平台 tag） |
+
+> 版本号与功能一一对应：小程序线的功能停在 v1.0.2，因此镜像 tag 也停在 v1.0.2；平台后续发 v1.0.5 时它依然不动。

 升级时在 `docker-compose.yml` 中同步更新 tag 的版本部分，不要改用 `latest`。

@@ -122,7 +149,9 @@ TDengine 版本为 `3.3.6.13`（公开镜像可得），生产用的是 `3.4.0.9
 - **`JWT_SIGNING_KEY` 必须在 `admin-svr`、`openapi`、`app-server` 三者间完全一致**，否则令牌跨服务不通
 - **镜像标签不要用 `latest`**，生产环境请固定到具体版本
 - **改 `schema/` 下的脚本不会自动生效**，需要清空 `data/mysql` 重新初始化（会丢失全部数据）
- 默认只监听 `127.0.0.1` 的服务需通过反向代理对外
+- 业务端口默认只绑定 `127.0.0.1`（admin-ui/admin-svr/openapi/app-web/docs/sms），要从其他机器访问，二选一：
+  - 用 `--profile with-nginx` 起自带反向代理（对外 80，按域名/路径分流，配置见 `config/nginx/iotlcm.conf`）
+  - 或把 `docker-compose.yml` 里对应服务的 `127.0.0.1:xxxx` 改成 `0.0.0.0:xxxx`（需自备防火墙策略）

 ## 许可

@@ -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;
+}
@@ -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
@@ -5000,6 +5000,10 @@ INSERT INTO `sys_dict_data` (`dict_type`,`dict_value`,`dict_label`,`dict_sort`,`
 -- 注意 is_normal：0=正常、1=异常（见 chan 侧 model.SimChannelConfigItemCache.CanCreateInstance，
 -- 只有 *IsNormal == 0 才会创建通道实例）。写成 1 会导致「通道未实例化」。
 -- 这里的取值与内网演示环境种子不同（那边是 1），属开源版修正。
+--
+-- app_key / app_secret 是挡板（onelink-mock）的凭据，chan 侧用它们向挡板换 Token
+-- （appid=app_key，password=app_secret）。取值必须与挡板默认凭据一致，
+-- 见 onelink-mock/internal/service/store.go 的 defaultStore()。
 -- ============================================================

 INSERT INTO `t_sim_channels` (
@@ -5012,7 +5016,7 @@ INSERT INTO `t_sim_channels` (
  `card_info_count`,`stock_card_count`,`cancellation_card_count`
 ) VALUES (
  34,'sim_yd_mock_v5','channel_yd_mock','移动模拟通道','{}',0,0,
-  '中国移动00',NULL,'100059999270000006','password123',NULL,
+  '中国移动00',NULL,'demo_appid','demo_password',NULL,
  NULL,NULL,'',
  NULL,NULL,'http://onelink-mock:8080/',NULL,'000000',
  1,1,'2026-10-19 15:35:03',NULL,NOW(),
@@ -139,8 +139,8 @@ docker build --build-arg GOPROXY=https://goproxy.cn,direct -t ... .
 | admin-svr | `iotlcm-admin-svr-<TAG>` | `.../iotlcm/iotlcm:iotlcm-admin-svr-v1.0.4` |
 | admin-ui | `iotlcm-admin-ui-<TAG>` | `.../iotlcm/iotlcm:iotlcm-admin-ui-v1.0.4` |
 | openapi | `iotlcm-openapi-<TAG>` | `.../iotlcm/iotlcm:iotlcm-openapi-v1.0.4` |
-| app-server | `iotlcm-app-server-<TAG>` | `.../iotlcm/iotlcm:iotlcm-app-server-v1.0.4` |
-| app-web | `iotlcm-app-web-<TAG>` | `.../iotlcm/iotlcm:iotlcm-app-web-v1.0.4` |
+| app-server | `iotlcm-app-server-<TAG>` | `.../iotlcm/iotlcm:iotlcm-app-server-v1.0.2` |
+| app-web | `iotlcm-app-web-<TAG>` | `.../iotlcm/iotlcm:iotlcm-app-web-v1.0.2` |
 | upstream-chan | `iotlcm-upstream-chan-<TAG>` | `.../iotlcm/iotlcm:iotlcm-upstream-chan-v1.0.4` |
 | upstream-proxy | `iotlcm-upstream-proxy-<TAG>` | `.../iotlcm/iotlcm:iotlcm-upstream-proxy-v1.0.4` |
 | worker-svr | `iotlcm-worker-svr-<TAG>` | `.../iotlcm/iotlcm:iotlcm-worker-svr-v1.0.4` |
@@ -151,6 +151,11 @@ docker build --build-arg GOPROXY=https://goproxy.cn,direct -t ... .

 基础组件（`mysql`、`redis`、`rabbitmq`、`consul`、`nginx`）不需要构建，从上游同步到同一仓库即可，tag 为 `<组件>-<版本>`，见下节。

+::: tip app 线是独立版本
+`iotlcm-app-server` 与 `iotlcm-app-web` 属于**小程序线**，版本号与平台 tag 解耦：平台发 v1.0.4 时它们仍是 `v1.0.2`。
+自建镜像时按 `iotlcm-app-<x>-v1.0.2` 命名，不要跟着平台版本走。
+:::
+
 ::: warning tag 必须带上服务名
 同一个仓库里 tag 不能重复。只用版本号（如 `v1.0.4`）会让 12 个服务互相覆盖，因此 tag 固定为 `<服务名>-<版本>`。
 :::
@@ -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（本文档站） |
@@ -137,7 +137,7 @@ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:11190/healthz

 ### 7. 浏览器登录

-访问 `http://<宿主机IP>:8009`：
+访问 `http://127.0.0.1:8009`（编排默认把业务端口绑定在 `127.0.0.1`；需要从其他机器访问时，用 `--profile with-nginx` 起反向代理，或改绑定地址）：

 | 项 | 值 |
 | --- | --- |
@@ -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
Author	SHA1	Message	Date
MiFaZhan	fd42b5976e	docs: 重写 README（用户视角，含手册跳转）+ 去掉「开源版」措辞 + 单端口入口 5051 mirror-to-gitee / mirror (push) Successful in 4s Details trigger-jenkins-oss / trigger (push) Successful in 0s Details 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 增单端口入口段	2026-11-02 14:57:57 +08:00
MiFaZhan	a7c15cf891	chore: 移除一次性探测/清理工作流（Gitee 删除需 projects 权限，API 侧 403） mirror-to-gitee / mirror (push) Successful in 4s Details	2026-11-02 14:25:34 +08:00
MiFaZhan	2548976f73	chore: 探测 Gitee 删除端点（一次性） mirror-to-gitee / mirror (push) Successful in 5s Details	2026-11-02 14:24:18 +08:00
如是 & 技小云	17c839daac	fix(deploy): Mock 通道凭据对齐挡板默认值 mirror-to-gitee / mirror (push) Successful in 5s Details schema/init.sql 里 sim_yd_mock_v5 通道的 app_key/app_secret 仍是内网挡板的老值（100059999270000006 / 老口令），与开源版挡板 onelink-mock 的默认凭据（demo_appid / demo_password，见 onelink-mock/internal/service/store.go 的 defaultStore()）不一致，导致 chan 侧向挡板换 Token 失败。改为挡板当前实际默认值，并在注释里标注取值来源。	2026-11-02 14:23:03 +08:00
MiFaZhan	f76e988689	chore: 清理工作流改为 artifact 回报（Gitea 无日志读取 API） mirror-to-gitee / mirror (push) Successful in 7s Details	2026-11-02 14:22:00 +08:00
MiFaZhan	1634d27a43	chore: 一次性清理工作流（删除 Gitee 侧 12 个已并入单仓的旧仓） mirror-to-gitee / mirror (push) Successful in 5s Details 删除后会再删掉本文件。	2026-11-02 14:20:13 +08:00
MiFaZhan	42d12d905a	chore: 小程序线（app）固定 v1.0.2，不跟随平台 tag mirror-to-gitee / mirror (push) Successful in 5s Details 版本号与功能一一对应：小程序线功能停在 v1.0.2，镜像 tag 也停在 v1.0.2，平台后续发 v1.0.5 时它不动。 - deploy/docker-compose.yml：app-server / app-web 两行回退 v1.0.2 - Makefile：IMAGE_MAP 增加第 5 列「固定版本」，app 两行填 v1.0.2，本地构建与 CI 行为一致 - 根 README：新增「小程序线是独立版本线」说明 - app/README.md：标注本目录对应 v1.0.2，不跟随平台 tag - 文档：deploy/README 版本表、build-image 的 tag 表与说明、 offline / prerequisites / configuration 示例 tag 全部回退 v1.0.2 CI 侧由 Jenkins 流水线的 PIN 表（app\|v1.0.2）保证：tag 构建自动跳过 app，需要重建时单独触发 SERVICES=app VERSION=v1.0.2。	2026-11-02 14:11:13 +08:00
MiFaZhan	89a15c4fca	chore: make help 只列命令，不再多印配置行 mirror-to-gitee / mirror (push) Successful in 4s Details	2026-11-02 13:59:47 +08:00
MiFaZhan	34669c9e1f	chore: 镜像校验覆盖 tag 集合 mirror-to-gitee / mirror (push) Successful in 4s Details 推送后除比对 main 的 sha，还比对本地与 Gitee 端的 tag 集合，不一致即判失败（Gitee 限流时容易出现“推送成功但 tag 丢失”）。	2026-11-02 13:55:45 +08:00
MiFaZhan	12512b06ff	fix: 单仓后统一版本号与访问地址说明 mirror-to-gitee / mirror (push) Successful in 4s Details trigger-jenkins-oss / trigger (push) Successful in 0s Details - 编排与文档里的 app 镜像 tag 由 v1.0.2 统一为 v1.0.4（单仓一个发布版本， v1.0.4 包含 app 线，不再保留源仓的历史 tag 差异） - deploy/README.md、docs/deploy/install.md 明确业务端口默认只绑 127.0.0.1，并给出对外访问的两种做法（with-nginx profile / 改绑定） - mirror-to-gitee 增加推送后校验：远端 main 与本地不一致则判失败	2026-11-02 13:40:26 +08:00