From a6eb3ffc98498fa6dff1fdaf95216b38150c9be3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=8A=80=E5=B0=8F=E4=BA=91?= Date: Thu, 5 Nov 2026 11:52:48 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=95=99=E7=A8=8B=E4=B8=AD=E5=BF=83?= =?UTF-8?q?=E9=A1=B5=E4=B8=8E=E4=B8=89=E9=A1=B9=E7=9B=AE=E6=95=99=E7=A8=8B?= =?UTF-8?q?=E8=A7=86=E9=A2=91=E6=B8=85=E5=8D=95=EF=BC=888=20=E6=94=AF?= =?UTF-8?q?=E8=A7=86=E9=A2=91=E5=90=AB=E5=88=86=E9=95=9C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vitepress/config.mts | 16 ++++- data/projects.ts | 8 ++- pages/guide/videos.md | 61 +++++++++++++++++++ pages/projects/iotlcm/guide/tutorial.md | 68 +++++++++++++--------- pages/projects/xiu-admin/guide/tutorial.md | 55 +++++++++++++++++ pages/projects/xiu-dtu/guide/tutorial.md | 58 ++++++++++++++++++ 6 files changed, 234 insertions(+), 32 deletions(-) create mode 100644 pages/guide/videos.md create mode 100644 pages/projects/xiu-admin/guide/tutorial.md create mode 100644 pages/projects/xiu-dtu/guide/tutorial.md diff --git a/.vitepress/config.mts b/.vitepress/config.mts index ef04a7c..20d09c0 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -72,6 +72,8 @@ export default defineConfig({ { text: '界面预览', link: '/#preview' }, // activeMatch：进入任一项目详情页时「项目」保持高亮 { text: '项目', link: '/projects/', activeMatch: '^/projects/' }, + // 教程视频：站内页，含各项目的录制清单与分镜 + { text: '教程', link: '/guide/videos', activeMatch: '^/guide/videos' }, // 官方文档直接跳文档站（外站），不在本站内做锚点停留 { text: '官方文档', @@ -86,14 +88,24 @@ export default defineConfig({ { text: '项目', collapsed: false, - items: projects.map((p) => ({ text: p.name, link: p.page })), + // 每个项目带自己的子页面（快速开始 / 部署 / 教程等）， + // 子页面清单来自注册表的 sections，不在此处重复维护。 + items: projects.map((p) => ({ + text: p.name, + link: p.page, + collapsed: false, + items: p.sections.map((s) => ({ text: s.text, link: s.link })), + })), }, ], '/guide/': [ { text: '门户', collapsed: false, - items: [{ text: '门户部署', link: '/guide/portal-deploy' }], + items: [ + { text: '教程中心', link: '/guide/videos' }, + { text: '门户部署', link: '/guide/portal-deploy' }, + ], }, ], }, diff --git a/data/projects.ts b/data/projects.ts index 5727249..0083760 100644 --- a/data/projects.ts +++ b/data/projects.ts @@ -66,7 +66,9 @@ export const projects: Project[] = [ tech: ['GoFrame v2', 'Vue 3 + Vben Admin', 'MySQL', 'Redis', 'asynq', 'VitePress'], status: '已发布', page: '/projects/xiu-dtu/', - sections: [], + sections: [ + { text: '教程视频', link: '/projects/xiu-dtu/guide/tutorial' }, + ], }, { id: 'xiu-admin', @@ -79,7 +81,9 @@ export const projects: Project[] = [ tech: ['GoFrame v2', 'Vue 3 + Vben Admin', 'Ant Design Vue', 'asynq'], status: '已发布', page: '/projects/xiu-admin/', - sections: [], + sections: [ + { text: '教程视频', link: '/projects/xiu-admin/guide/tutorial' }, + ], }, ] diff --git a/pages/guide/videos.md b/pages/guide/videos.md new file mode 100644 index 0000000..39f48f1 --- /dev/null +++ b/pages/guide/videos.md @@ -0,0 +1,61 @@ +--- +title: 教程中心 +description: 开源项目门户的全部教程视频清单与录制排期 +outline: deep +--- + +# 教程中心 + +门户下的教程视频按项目组织。视频是这个门户的主交付物之一，文档只作配套与字幕说明，不能替代视频。 + +## 视频总表 + +| # | 项目 | 类型 | 标题 | 时长 | 目标观众 | +| --- | --- | --- | --- | --- | --- | +| V0 | 门户 | 导览 | 雪羊科技开源门户导览：三个项目分别适合谁 | 3 分钟 | 第一次接触本项目的开发者、技术选型者 | +| V1 | iotLCM | 部署 | iotLCM 开源版部署教程：从零到可用 | 12 ~ 15 分钟 | 具备 Linux 与 Docker 基础的实施工程师 | +| V2 | iotLCM | 使用 | iotLCM 开源版使用教程：核心功能实操 | 15 ~ 20 分钟 | 已完成部署、准备给业务方上手的管理员 | +| V3 | iotLCM | 接口 | iotLCM OpenAPI 接入实战：从申请凭证到跑通调用 | 10 ~ 12 分钟 | 要把平台接进自己系统的第三方开发者 | +| V4 | 秀杰 DTU | 部署 | 秀杰 DTU 部署教程：源码起服务到设备接入 | 12 ~ 15 分钟 | 做 DTU 设备接入的开发者 | +| V5 | 秀杰 DTU | 设备 | 秀杰 DTU 设备实操：双通道接入、指令下发与 OTA | 15 ~ 18 分钟 | 设备端与平台端联调工程师 | +| V6 | XiuAdmin | 部署 | XiuAdmin 一键部署：三个容器跑起中后台 | 8 ~ 10 分钟 | 要用这个框架搭中后台的开发者 | +| V7 | XiuAdmin | 二开 | XiuAdmin 框架上手：代码生成到业务模块落地 | 15 分钟 | 要基于框架二次开发的工程师 | + +V0 是导览，可选；其余 7 支是必录。 + +## 分项目入口 + +- [iotLCM 教程视频](/projects/iotlcm/guide/tutorial) +- [秀杰 DTU 教程视频](/projects/xiu-dtu/guide/tutorial) +- [XiuAdmin 教程视频](/projects/xiu-admin/guide/tutorial) + +## 通用录制规范 + +| 项 | 口径 | +| --- | --- | +| 录屏环境 | 干净的 Ubuntu 24.04 + Docker Compose V2，不在已有业务实例上录 | +| 画面内容 | 终端为主，浏览器演示为辅；关键步骤要有停顿与高亮 | +| 敏感信息 | 口令、令牌一律打码，示例用编排里的默认值 | +| 可复现 | 视频里出现的每条命令都必须能原样复制执行，与对应文档页严格一致 | +| 命名 | 小写连字符加版本号，如 `iotlcm-deploy-v1.mp4`，放 `website/public/videos/` | +| 字幕 | 每支视频配一份 Markdown 要点说明，随视频一起发布 | +| 发布位置 | 官网对应项目页 + 源码仓 README 顶部 + B 站 | + +## 排期建议 + +录制顺序按「依赖关系」而非项目分组：先录 V1（部署），因为 V2、V3 都以一套已起好的环境为背景；再录 V4、V5；最后 V6、V7。 + +建议批次： + +1. **第一批（3 支）**：V0、V1、V2 —— 覆盖门户与主力项目，官网可先上线 +2. **第二批（2 支）**：V3、V4 —— 补齐 iotLCM 接口面向与第二个项目 +3. **第三批（3 支）**：V5、V6、V7 —— 设备实操与框架两支 + +每批之间留一次审看：命令是否与文档一致、是否可复现、有没有打码遗漏。 + +## 验收口径 + +- 每支视频完整看一遍，步骤无断点 +- 视频里的命令在干净环境重跑能通 +- 官网对应项目页有该视频的入口，且能播放 +- 元数据齐备：标题、目标观众、时长、发布位置、关联文档与仓库路径 diff --git a/pages/projects/iotlcm/guide/tutorial.md b/pages/projects/iotlcm/guide/tutorial.md index 23c74eb..974d85c 100644 --- a/pages/projects/iotlcm/guide/tutorial.md +++ b/pages/projects/iotlcm/guide/tutorial.md @@ -1,65 +1,77 @@ --- title: 教程视频 -description: 部署与使用的录屏教程 +description: iotLCM 开源版的部署、使用与接口接入录屏教程 outline: deep --- # 教程视频 -开源版的上手路径只有两条：**把平台跑起来**（部署）与**把平台用起来**（使用）。两条路径各一支录屏视频，文字文档只作配套说明，不替代视频。 +iotLCM 分三支：怎么装起来、怎么用起来、怎么接进去。前两支面向实施与业务方，第三支面向第三方开发者。 -## 部署教程 +## V1 部署教程：从零到可用 | 项 | 内容 | | --- | --- | | 标题 | iotLCM 开源版部署教程：从零到可用 | -| 目标观众 | 第一次接触本项目、具备 Linux 与 Docker 基础的开发者与实施工程师 | +| 目标观众 | 具备 Linux 与 Docker 基础的实施工程师 | | 时长 | 12 ~ 15 分钟 | -| 发布位置 | 官网本页 + 代码仓 README 顶部 + B 站 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | | 关联文档 | [快速开始](/projects/iotlcm/guide/quickstart)、[部署与运维](/projects/iotlcm/guide/deploy) | | 关联仓库路径 | `deploy/`、`docs/` | -视频覆盖： +分镜： -1. 环境准备：Docker 与 Compose 版本检查、端口占用确认、机器规格建议 -2. 取代码：`git clone` 公开仓库，确认目录结构 -3. 启动：`docker compose up -d`，观察 MySQL 初始化日志直到种子数据导入完成 -4. 验证：登录管理端、打开文档站与 OpenAPI 文档、跑一次状态查询 -5. 收尾：改默认口令、停栈与清理数据卷 +1. **环境准备**（1.5 分钟）：Docker 与 Compose 版本检查、机器规格建议、端口占用确认 +2. **取代码**（0.5 分钟）：`git clone` 公开仓库，展示目录结构 +3. **启动**（4 分钟）：`cd deploy && docker compose up -d`，`docker compose logs -f mysql` 看初始化直到种子数据导入完成 +4. **验证**（3 分钟）：登录管理端、打开文档站 `/docs/`、打开 OpenAPI 文档、跑一次卡状态查询 +5. **收尾**（2 分钟）：改默认口令清单、`docker compose down` 与 `down -v` 的区别 +6. **踩坑预告**（1 分钟）：MySQL 初始化失败要清卷、文档站必须带 `/docs/` 路径 -## 使用教程 +## V2 使用教程：核心功能实操 | 项 | 内容 | | --- | --- | | 标题 | iotLCM 开源版使用教程：核心功能实操 | | 目标观众 | 已完成部署、准备给业务方上手的管理员与运营人员 | | 时长 | 15 ~ 20 分钟 | -| 发布位置 | 官网本页 + 代码仓 README 顶部 + B 站 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | | 关联文档 | [功能概览](/projects/iotlcm/) | | 关联仓库路径 | `admin-svr/`、`admin-ui/`、`openapi/`、`worker-svr/` | -视频覆盖： +分镜： -1. 卡信息：列表检索、按三码查卡、卡详情与用量查看 -2. 库存与划拨：入库后的代理商维度划拨 -3. 资费与业务受理：套餐配置、开通/续费/停复机、达量断网 -4. 通道与批次：通道配置查看、批量操作与异步进度 -5. 对外接口：申请 API 凭证并完成一次真实调用 -6. 账号与工单：企业用户与角色、告警工单处理 +1. **卡信息**（3 分钟）：列表检索、按 ICCID / MSISDN / IMSI 三码查卡、卡详情与用量查看 +2. **库存与划拨**（2.5 分钟）：入库后按代理商维度划拨、划拨历史 +3. **资费与业务受理**（3 分钟）：套餐与定价配置、开通 / 续费 / 停复机 / 变更套餐、达量断网阈值 +4. **通道与批次**（3.5 分钟）：通道配置查看、批量操作提交、异步进度与执行日志 +5. **账号与工单**（2.5 分钟）：企业与用户管理、角色权限、告警工单处理 +6. **智能诊断**（1.5 分钟）：结合卡状态、通道与用量出诊断结论 -## 视频文件放置约定 +## V3 OpenAPI 接入实战 -成片放在代码仓的 `website/public/videos/` 下，文件名用小写连字符加版本号（如 `deploy-tutorial-v1.mp4`），页面里以相对路径引用： +| 项 | 内容 | +| --- | --- | +| 标题 | iotLCM OpenAPI 接入实战：从申请凭证到跑通调用 | +| 目标观众 | 要把平台接进自己系统的第三方开发者 | +| 时长 | 10 ~ 12 分钟 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | +| 关联文档 | 文档站 OpenAPI 合同章节 | +| 关联仓库路径 | `openapi/`、`docs/` | -```html - -``` +分镜： -若改投 B 站等外部托管，页面保留外链入口即可，视频文件不进仓库（避免仓库体积膨胀）。 +1. **申请凭证**（2 分钟）：管理端申请 API 凭证、看凭证与权限范围 +2. **鉴权方式**（2 分钟）：JWT 令牌获取、令牌与权限的关系 +3. **第一次调用**（3 分钟）：卡信息查询接口的请求参数、响应结构、逐字段解释 +4. **错误处理**（2 分钟）：常见业务错误码与参数校验失败的处理路径 +5. **兼容接口**（1.5 分钟）：旧版兼容接口与 V3 的差异，何时该用哪套 +6. **收尾**（1 分钟）：接入自检清单 ## 录制备忘 -- 录屏环境用与观众一致的环境：干净的 Ubuntu + Docker Compose V2，不要在已有业务实例上录 -- 涉及口令的片段一律打码，示例口令用编排里的默认值 +- 录屏环境用干净 Ubuntu + Compose V2，不在已有业务实例上录 +- 涉及口令的片段一律打码，用编排里的默认值 - 步骤与[快速开始](/projects/iotlcm/guide/quickstart)严格一致，视频里出现的每条命令都必须能原样复制执行 - 每个视频产出配套字幕或要点说明（Markdown），随视频一起发布 +- 视频文件命名 `iotlcm-deploy-v1.mp4` 这类，官网用相对路径引用；改投外部托管则不进仓库 diff --git a/pages/projects/xiu-admin/guide/tutorial.md b/pages/projects/xiu-admin/guide/tutorial.md new file mode 100644 index 0000000..f0f0ede --- /dev/null +++ b/pages/projects/xiu-admin/guide/tutorial.md @@ -0,0 +1,55 @@ +--- +title: 教程视频 +description: XiuAdmin 中后台框架的一键部署与二开实操录屏教程 +outline: deep +--- + +# 教程视频 + +XiuAdmin 是开发底座而不是业务系统，两支视频分别回答「怎么跑起来」和「怎么用它写自己的业务」。 + +## V6 一键部署：三个容器跑起中后台 + +| 项 | 内容 | +| --- | --- | +| 标题 | XiuAdmin 一键部署：三个容器跑起中后台 | +| 目标观众 | 要用这个框架搭中后台的开发者 | +| 时长 | 8 ~ 10 分钟 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | +| 关联文档 | 代码仓 `deploy/README.md` | +| 关联仓库路径 | `deploy/`、`build/` | + +分镜： + +1. **三个容器是什么**（1.5 分钟）：MySQL 8.0、Redis 7.2、前后端一体应用，MySQL 与 Redis 只在内部网络可达、不映射宿主端口 +2. **一条命令启动**（3 分钟）：`cd deploy && ./run.sh`，看它自动生成 `.env`（随机数据库口令、Redis 口令、JWT 密钥，权限 600）、拉镜像、起容器、等健康检查通过 +3. **访问与改密**（1.5 分钟）：打开 `http://<服务器IP>:8199/`，初始账号 admin / 123456 登录后立即改密 +4. **常用命令**（1.5 分钟）：`status` 看状态与健康检查、`logs` 跟日志、`restart` 改 `.env` 后重建应用容器、`down` 保留数据卷、`destroy` 清数据需二次确认 +5. **手工部署路线**（1 分钟）：`cp .env.example .env` 后用 `docker compose up -d`，说明 `.env` 里各变量含义（镜像前缀、APP_TAG、APP_PORT、四个口令、JWT_SIGNING_KEY 必须够长且随机） + +## V7 框架上手：代码生成到业务模块落地 + +| 项 | 内容 | +| --- | --- | +| 标题 | XiuAdmin 框架上手：代码生成到业务模块落地 | +| 目标观众 | 要基于框架二次开发的工程师 | +| 时长 | 15 分钟 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | +| 关联文档 | 代码仓 `README.md` 的内置功能清单与目录说明 | +| 关联仓库路径 | `server/`、`vue/` | + +分镜： + +1. **框架全貌**（2 分钟）：GoFrame2 后端 + Vue3 前端（Vben Admin）+ Ant Design Vue，单仓结构（`server/`、`vue/`、`docs/`、`build/`、`deploy/`）与「前后端一体镜像」的思路 +2. **代码生成**（4 分钟）：建表 → 简单配置 → 生成 CURD / 树表 / 消息队列 / 定时任务代码，表单控件勾选即生成 +3. **生成代码怎么接进系统**（3 分钟）：生成的 API、控制器、菜单权限如何挂进路由，前端页面如何挂进菜单 +4. **多租户与数据权限**（2.5 分钟）：租户与租户套餐、角色按机构或上下级关系划数据范围 +5. **异步与通知**（2 分钟）：Asynq 消息队列怎么用、WebSocket 实时推送通知公告与私信 +6. **运维视图**（1.5 分钟）：在线用户、定时任务、服务监控、缓存监控、附件大文件分片上传 + +## 录制备忘 + +- 录屏环境用干净 Ubuntu + Docker，不要连生产或预演环境 +- 口令一律打码，`run.sh` 生成随机口令这一步可展示但值要遮住 +- 代码生成那段用一个明显的示例表（如 demo_order），避免观众误以为是框架内置表 +- 步骤与代码仓 `deploy/README.md` 严格一致，视频里的每条命令都要能原样复制执行 diff --git a/pages/projects/xiu-dtu/guide/tutorial.md b/pages/projects/xiu-dtu/guide/tutorial.md new file mode 100644 index 0000000..95a2209 --- /dev/null +++ b/pages/projects/xiu-dtu/guide/tutorial.md @@ -0,0 +1,58 @@ +--- +title: 教程视频 +description: 秀杰 DTU 管理平台的部署与设备实操录屏教程 +outline: deep +--- + +# 教程视频 + +秀杰 DTU 分两支：把服务起起来并让设备连上，然后在平台上真的操作一遍设备。 + +## V4 部署教程：源码起服务到设备接入 + +| 项 | 内容 | +| --- | --- | +| 标题 | 秀杰 DTU 部署教程：源码起服务到设备接入 | +| 目标观众 | 做 DTU 设备接入的开发者 | +| 时长 | 12 ~ 15 分钟 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | +| 关联文档 | 代码仓 `docs_ui/` 文档站（快速上手、通信协议、控制台说明） | +| 关联仓库路径 | `server/`、`vue/`、`docs_ui/`、`docker/`、`deploy/` | + +分镜： + +1. **环境准备**（1.5 分钟）：Go 1.25+、Node.js 24+ 与 pnpm 10+、MySQL 8、Redis 7 的版本检查 +2. **初始化数据库**（2 分钟）：建库 `xiujie_dtu` 并按顺序导入四个初始化 SQL（基础表、业务表、菜单、角色） +3. **配置后端**（1.5 分钟）：复制 `config_default.yaml` 为 `config.yaml`、改数据库与 Redis 连接、设置 JWT 签名密钥环境变量（长度不少于 32 位，未提供时服务拒绝签发令牌） +4. **启动后端**（2.5 分钟）：`go run main.go`，说明三个监听端口的用途：控制台 5689、设备 HTTP 5692、设备 TCP 5690 +5. **启动前端与文档站**（2 分钟）：`pnpm install && pnpm dev`（前端 5688）、`npm run docs:dev`（文档站 5687） +6. **登录与改密**（1 分钟）：初始 admin 账号登录后立即改密 +7. **Docker 部署路线**（2 分钟）：`docker/dtu_base` 初始化中间件 → `docker/dtu_iot` 部署业务服务、`make docker-build docker-push` 构建推送镜像 + +## V5 设备实操：双通道接入、指令下发与 OTA + +| 项 | 内容 | +| --- | --- | +| 标题 | 秀杰 DTU 设备实操：双通道接入、指令下发与 OTA | +| 目标观众 | 设备端与平台端联调工程师 | +| 时长 | 15 ~ 18 分钟 | +| 发布位置 | 官网本页 + 源码仓 README 顶部 + B 站 | +| 关联文档 | 代码仓文档站「通信协议」章节（HTTP API、TCP 帧、指令、属性上报、配置同步、OTA、UART 隧道） | +| 关联仓库路径 | `tools/`、`server/`、`docs_ui/` | + +分镜： + +1. **HTTP 通道联调**（3 分钟）：用 `tools/test-device-http-v4.sh` 带 DEVICE_KEY / PRODUCT_KEY / PROJECT_KEY 打一次设备注册与上报，看平台侧设备列表出现 +2. **TCP 通道联调**（3 分钟）：`tools/test-device-tcp-v4.py --heartbeat --listen-command` 建连、维持心跳、接收平台下发指令 +3. **指令下发**（2.5 分钟）：从控制台对设备下指令，两端同时看帧与日志 +4. **属性上报与配置同步**（2.5 分钟）：设备上报属性、平台侧改配置并下发，验证端到端一致性 +5. **OTA 升级**（2.5 分钟）：研发中心建固件版本、发起 OTA 升级任务、看设备侧升级结果 +6. **UART 隧道**（1.5 分钟）：透传串口数据的用法与适用场景 +7. **压测**（2 分钟）：`tools/stress-2w-devices.py --count 20000` 演示 2 万设备压测怎么发起、看指标 + +## 录制备忘 + +- 录屏环境用干净 Ubuntu，MySQL / Redis 独立装，不要连生产或预演环境 +- DEVICE_KEY / PRODUCT_KEY / PROJECT_KEY 等示例值用文档里的测试值，画面出现即可 +- 2 万设备压测那段只演示命令与指标入口，不在录屏环境真压 2 万台 +- 步骤与代码仓文档站的「快速上手」严格一致，视频里的每条命令都要能原样复制执行