MiFaZhan
f7cab5ad5c
mirror-to-gitee / mirror (push) Successful in 14s
把原来 12 个独立仓合并为单仓多服务结构，各仓完整提交历史通过
read-tree 并入保留（137 个提交，blame 可追溯）。
目录：
admin-svr/ admin-ui/ app/{server,app}/ openapi/ worker-svr/
upstream-chan/ upstream-proxy/ sms/ bot/ docs/ onelink-mock/ deploy/
同时：
- 新增根 README（目录说明、快速开始、源码构建、镜像发布、许可）
- 新增根 Makefile（make build / test / images / docs）
- 新增根 .gitattributes / .gitignore，删掉 12 份重复的 Apache LICENSE
（admin-ui/ 与 app/app/ 的 MIT 上游许可保留）
- 各服务的 .gitea/workflows 收敛到仓根：trigger-jenkins.yml（tag 构建全部
服务）+ mirror-to-gitee.yml（自动建 Gitee 仓后镜像）
- 文档内跨仓绝对链接改为仓内相对路径；部署/构建文档改为单仓路径
90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# iotlcm-docs
|
||
|
||
iotLCM 物联网卡全生命周期管理平台的**使用手册与 OpenAPI 合同**。
|
||
|
||
- **使用手册**：Web 管理端（企业客户视角）与小程序端的操作说明，含截图
|
||
- **OpenAPI 合同**：V3 接口、旧版兼容接口、运营商能力代理（白名单转发 / 共享 Token）的鉴权方式、请求参数与响应结构
|
||
|
||
## 技术栈
|
||
|
||
VitePress 1.6 + Vue 3，产物为纯静态站点。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
iotlcm-docs/
|
||
├── docs/ # 文档源（VitePress srcDir）
|
||
│ ├── index.md # 文档首页
|
||
│ ├── manual/ # 使用手册
|
||
│ │ ├── web/ # Web 管理端
|
||
│ │ └── mini-program/ # 小程序端
|
||
│ ├── openapi/ # OpenAPI 合同
|
||
│ │ ├── v3/ # V3 接口
|
||
│ │ ├── legacy/ # 旧版兼容接口
|
||
│ │ └── operator/ # 运营商能力代理
|
||
│ └── public/ # 静态资源（favicon、截图）
|
||
├── .vitepress/ # VitePress 配置与主题定制
|
||
├── docker/ # nginx 配置
|
||
├── Dockerfile
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
npm ci
|
||
npm run dev # http://127.0.0.1:5173/docs/
|
||
```
|
||
|
||
> 入口地址带 `/docs/`：配置里 `base: '/docs/'`，直接访问根路径会 404。
|
||
|
||
构建与预览：
|
||
|
||
```bash
|
||
npm run build # 产物在 .vitepress/dist
|
||
npm run preview
|
||
```
|
||
|
||
站点部署在子路径 `/docs/`（见 `.vitepress/config.mts` 的 `base`）。本地开发时根路径会自动重定向 favicon。
|
||
|
||
## 部署
|
||
|
||
**完整部署手册见文档站：[部署手册](./docs/deploy/index.md)**，包含推荐环境、编译方法、nginx / 对象存储 / 离线环境部署方式与常见问题。
|
||
|
||
最短路径（容器，推荐）：
|
||
|
||
```bash
|
||
docker build -t iotlcm-docs:$(git rev-parse --short HEAD) .
|
||
docker run -d --name iotlcm-docs -p 8019:80 iotlcm-docs:latest
|
||
# 访问 http://127.0.0.1:8019/docs/
|
||
```
|
||
|
||
多阶段构建：Node 阶段执行 `vitepress build`，最终镜像只含 nginx 与静态产物。
|
||
|
||
> ⚠️ **路径前缀**：`base: '/docs/'` 使资源引用为绝对路径 `/docs/assets/*`，而 dist 是平铺的。`docker/nginx.conf` 已用 `alias` 剥掉前缀，**不要**改成从根路径直接服务产物，否则白屏。
|
||
|
||
`docker-compose.yml` 里的镜像名需替换成你自己的镜像仓库地址；对外署时请用不可变标签（commit sha）而不是 `latest`。
|
||
|
||
## 文档里的占位符
|
||
|
||
文档中的服务地址、凭据等均为占位示例：
|
||
|
||
| 占位 | 含义 |
|
||
| --- | --- |
|
||
| `iotlcm.example.com` | Web 管理端地址 |
|
||
| `api.iotlcm.example.com` | OpenAPI 服务地址 |
|
||
| `YOUR_APP_ID` / `YOUR_APP_SECRET` | 平台分配的应用凭据 |
|
||
| `YOUR_ACCESS_TOKEN` / `YOUR_TRANSID` | 调用方凭据与流水号 |
|
||
| `141****5152` | 示例手机号 |
|
||
|
||
替换成你自己的环境即可。
|
||
|
||
## 相关项目
|
||
|
||
- [`openapi/`](../openapi) —— OpenAPI 服务实现
|
||
- [`admin-svr/`](../admin-svr) —— Web 管理端后端
|
||
|
||
## License
|
||
|
||
[Apache License 2.0](./LICENSE)
|