release v25.24.0

.github/workflows/deploy-to-gh-pages.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Setup Node env
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'pnpm'
 
       - name: Install Dependencies

.github/workflows/pr-check.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Setup Node env
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'pnpm'
 
       - name: Install Dependencies

.github/workflows/shared-oss-deploy.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Setup Node env
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'pnpm'
 
       - name: Install Dependencies

docs/device/2-create-device.md

@@ -4,29 +4,27 @@ sidebar_position: 2
 
 # 添加设备
 
-## 权限说明
-
 :::info
 🤖 权限：仅**组织成员**及以上权限可以添加设备
 :::
 
 当组织引入新设备，并期望在平台中创建一台与线下真实设备相对应的设备，可前往组织设备页面进行添加。
 
-## 添加方式概述
-
-平台提供以下 3 种添加新设备到组织的方式：
+平台提供以下 3 种设备添加方式：
 
 | 添加方式             | 适用场景                                   |
 | -------------------- | ------------------------------------------ |
-| 在设备端执行命令添加 | 少量设备逐一准入与平台通信                 |
-| 使用离线安装包添加   | 设备出厂批量准入与平台通信                 |
-| 填写信息添加         | 快速创建仅用于数据流转的设备，不与平台通信 |
+| 在设备端执行命令添加 | 少量设备逐一安装
+| 使用离线安装包添加   | 设备出厂批量安装
+| 填写信息添加         | 快速创建仅用于数据管理的设备，不与平台通信 |
 
 ## 在设备端执行命令添加 {#add-device-from-device}
 
 ### 适用情况与入口
 
-此方式适用于少量设备逐次接入平台。用户需手动通过 SSH 登录设备执行命令。入口位于「组织管理」页面的「设备」分页，点击【添加设备】按钮，进入添加设备弹窗
+此方式适用于少量设备逐次接入平台。用户需在真实设备上打开终端，执行相应的注册命令。
+
+入口位于「组织管理」页面的「设备」分页，点击【添加设备】按钮，进入添加设备弹窗
 
 ![添加设备入口](./img/4-3-add-device-button.png)
 
@@ -36,102 +34,119 @@ sidebar_position: 2
 
 1. 当前仅支持 Linux 设备，涵盖 arm64 和 x86_64 架构；
 
-2. 暂不支持 Windows 设备，如有 Windows 设备接入需求，请联系刻行团队。
+2. 暂不支持 Windows 设备，如有 Windows 设备接入需求，请联系我们。
 
 ### 设备 ID 配置
 
-1. 可填写存放设备唯一标识码（如 ID 或 SN）的位置，支持 txt、json、yaml 文本文件类型。
-
-   - 若为 txt 文件，系统读取整个文件内容。
-
-   - 若为 json、yaml 文件，需在下方输入框填写 ID 号的变量值（如文件中含 `id:123`，则在此处填写 `id`）。
-
-2. 组织管理员可在「组织设备 - 编辑数采规则」中预设 ID 统一存放地址配置，实现弹窗自动填充，且支持二次更改。
+设备 ID 是设备在平台中的唯一标识，注册后不可修改。设备 ID 的生成方式如下：
+- 从设备端获取设备的唯一标识码（推荐使用设备 SN）
+- 由系统自动生成随机 ID
+
+1. **从设备端获取 ID**：从设备端指定文件中获取 ID，支持 txt、json、yaml 文本文件类型。
+   - txt 文件
+      - 系统会读取文件的全部内容作为设备 ID
+      - 只需填写该文件在设备上的完整路径
+   - json、yaml 文件
+      - 系统会读取文件中指定的字段作为设备 ID
+      - 除文件路径外，还需在下方输入框填写字段标识名。（如文件内容为 `id:123`，在此处填写 `id`，则会将 `123` 作为设备 ID）。
+   - ID 设置
+      - 为提高效率，组织管理员可在「组织设备 - 设备配置」中设置统一的设备 ID 文件路径
+      - 设置后，添加设备时将自动填充该路径，用户仍可根据实际情况修改。详见[设备配置](./4-device-collector.md#存储设置mod)
 
    ![从设备端获取 ID 位置](./img/4-3-add-device-id-01.png)
 
-   1. 若选择系统生成 ID，平台将生成默认 ID 号，安装后不可修改。
+2. **系统生成 ID**：平台生成默认 ID 号
 
    ![系统生成 ID](./img/4-3-add-device-id-02.png)
 
 ### 安装客户端选择
 
 1. **数据采集（coScout）客户端**
 
-   安装后设备可依据项目规则或采集任务采集数据，安装前需管理员配置数采监听目录等信息，详情参考编辑数采规则文档。
+   安装后设备可依据项目规则或采集任务采集数据，使用前需配置数采监听目录等信息，详情参考[设备配置文档](./4-device-collector.md#存储设置mod)。
 
 2. **远程控制（coLink）客户端**
 
-   安装后可实现网页 SSH、结合 [coBridge](https://github.com/coscene-io/coBridge) 实时可视化设备，功能详情参阅远程控制设备[文档](https://docs.coscene.cn/docs/device/device-remote-control)；
+   安装后可实现网页 SSH、结合 [coBridge](https://github.com/coscene-io/coBridge) 实时可视化设备，功能详情参阅[远程连接设备文档](./5-device-remote-control.md)；
 
 3. **初始化客户端配置**
 
-   若设备更换上位机或 ID 后需重新安装注册，勾选【初始化客户端配置】；仅升级客户端版本则取消勾选，更多使用方法参阅换机、升级、卸载流程指南
+   - 设备重新安装时：
+     - 更换上位机或修改设备 ID：请勾选【初始化客户端配置】
+     - 仅升级客户端版本：无需勾选【初始化客户端配置】
+   - 详细操作步骤请参阅[换机、升级、卸载流程指南](./7-change-device-guide.md)
 
    ![安装客户端选择](./img/4-3-install-coscout-colink.png)
 
 ### 执行安装命令
+> 注意：
+> 设备端执行命令添加时，若以 root 用户执行命令，或在命令前加 `sudo`，会将 coScout 安装在 root 下；若直接使用当前用户执行命令，会将 coScout 安装在当前用户下。
 
 1. 完成设备 ID 及安装客户端选项配置后，系统生成安装命令。用户复制命令至设备端 shell 终端执行。
 
    ![系统生成安装命令](./img/4-3-install-cmd.png)
 
-2. 设备端出现 `Installation completed successfully 🎉` 提示即安装成功。受设备性能影响，安装完成后设备列表页显示可能存在延迟，此时设备已完成注册，后续操作参考设备准入部分
+2. 设备端出现 `Installation completed successfully 🎉` 提示即安装成功(受设备性能影响，安装完成后设备列表页显示可能存在延迟)。此时设备已完成注册，后续操作参考[设备启用文档](./3-manage-device.md#enable-device)。
 
    ![设备端安装成功](./img/4-3-install-successfully.png)
 
-   ![管理员到平台中准入设备](./img/4-3-access-device.png)
+   ![管理员到平台中启用设备](./img/4-3-access-device.png)
 
 ## 使用离线安装包添加
 
 ### 适用情况与相关设置
 
-1. 此方式是相当于把数据采集、远程控制的安装包打包到设备软件版本更新包里，并且在安装包启动脚本里可以预先写好要执行的脚本赋权命令和安装命令，适合大规模的准入，比如设备出厂设置就自带了这两个客户端；
+1. 使用离线安装包添加设备：将数据采集和远程控制功能相关的安装包集成到设备的软件更新包中：
+   - 适用于设备出厂批量部署场景
+   - 可实现设备开箱即用，无需单独安装客户端
 
-2. 此添加方式中的「设备系统」、「设备 ID 配置」、「安装客户端选择」与在设备端执行命令添加的方式相同，可参考对应部分教程。以下重点介绍安装方式区别
+2. 配置说明：
+   - 基础配置项（设备系统、设备 ID 配置、安装客户端选择）与「在设备端执行命令添加」方式相同，请参考上述章节了解详情
+   - 下文将重点说明离线安装包特有的安装步骤
 
 ### 安装步骤
 
-1. 假设用户位于 `/root` 目录下（切换目录时需注意更改路径），下载安装脚本 **coscene.sh**、离线二进制文件压缩包 **cos_binaries.tar.gz** 至设备端，存放位置分别为 `/root/coscene.sh`, `/root/cos_binaries.tar.gz`。
+1. 下载安装脚本 **install.sh**、安装包 **cos_binaries.tar.gz**，将其存放于至设备端。
+
    ![下载离线安装包](./img/4-3-download-offline-package.png)
 
-2. 在 root 目录下，给安装脚本赋予执行权限：
+2. 打开设备终端，在对应目录下，给安装脚本赋予执行权限：
 
    ```plain text
-   chmod +x /root/coscene.sh
+   chmod +x install.sh
    ```
 
-3. 执行安装命令（以 `cos_binaries.tar.gz` 位于 `/root/cos_binaries.tar.gz` 为例）：
+3. 在设备终端，执行安装命令：
 
    ```plain text
-   ./coscene.sh --server_url=*** --project_slug=*** --virmesh_endpoint=*** --use_local=/root/cos_binaries.tar.gz
+   ./install.sh --use_local=./cos_binaries.tar.gz --mod="default" --org_slug="***" --server_url="***" --coLink_endpoint="***" --coLink_network="***" --sn_file="***" --sn_field="***" --remove_config
    ```
 
-   其中，参数 `--server_url` ，`--project_slug` ，`--virmesh_endpoint` 请参考网页端添加设备弹窗中的安装命令生成结果替换 `***`，参数 `--use_local` 为离线二进制文件压缩包路径，修改目录位置时需同步修改该参数。
+   其中，参数 `--use_local` 为离线安装包在设备上的路径，需根据实际情况进行修改。
 
    ![使用离线安装包添加](./img/4-3-offline-install-package.png)
 
 ## 填写信息添加
 
 ### 适用情况
 
-此方式平台数据库创建虚拟设备字段，不与真实设备对应。
+创建虚拟设备字段，仅用于数据管理，不与真实设备对应。
 
 ### 操作步骤
 
 1. 在「添加设备」弹框输入设备 ID 及其他信息（设备 ID 不可重复），点击【添加】即可创建设备。
 
-2. 若组织管理员设置自定义字段，用户需按页面提示填写完整必填项（如示例中的门店、机型）
+2. 若组织管理员设置了设备自定义字段，用户需按页面提示填写必填项（如示例中的门店、机型）
 
-![使用离线安装包添加](./img/4-3-input-information.png)
+![填写信息添加](./img/4-3-input-information.png)
 
 ## 后续操作
-- [设备准入](./3-manage-device.md#设备准入)
-- [将设备添加到项目](./3-manage-device.md#分配设备到项目)
-   - [手动采集数据](../use-case/1-common-task.md)
-   - [根据错误码自动采集数据](../use-case/data-diagnosis/2-get-started.md)
+- [启用设备](./3-manage-device.md#enable-device)
+- [将设备添加到项目](./3-manage-device.md#assign-devices-to-projects)
+  - [手动采集数据](../use-case/1-common-task.md)
+  - [根据错误码自动采集数据](../use-case/data-diagnosis/2-get-started.md)
 - [远程连接设备](./5-device-remote-control.md)
-   - 实时可视化
-   - 网页 SSH
-   - 远程下发命令
-   - 端口映射
+  - 实时可视化
+  - 网页 SSH
+  - 远程下发命令
+  - 端口映射

docs/device/3-manage-device.md

@@ -4,25 +4,23 @@ sidebar_position: 3
 
 # 管理设备
 
-## 设备管理基础
-
-设备在组织层面进行统一管理，只有组织成员及以上权限的用户可进行相关操作。在「组织管理 - 设备」页面能够查看现有的设备列表。
+设备在组织层面进行统一管理，在「组织管理 - 设备」页面可查看组织内的全部设备。
 
 ## 设备信息筛选与表格设置
 
 :::info
-🤖 权限：所有**组织用户**均可查看过滤设备信息
+🤖 权限：所有**组织内的用户**均可查看过滤设备信息
 :::
 
 ### 过滤设备信息
 
-系统默认支持对「设备 ID」、「准入状态」、「在线状态」这 3 个字段进行筛选，在「更多」选项中，还能选择设备的自定义字段进行过滤操作，以满足用户更个性化的信息查找需求。
+系统默认支持对「设备 ID」、「客户端状态」、「在线状态」这 3 个字段进行筛选，在「更多」选项中，还能选择设备的自定义字段进行过滤操作，以满足用户更个性化的信息查找需求。
 
 ![组织设备过滤](./img/4-3-device-filter.png)
 
 ### 表格设置
 
-当设备字段较多时，可利用表格右上角的设置按钮，按照个人偏好对表格显示字段进行排序、隐藏等操作，方便用户聚焦关键信息。同时，也可通过【恢复默认】将表格恢复到初始显示状态
+当设备字段较多时，可通过表格右上角的【设置】按钮，按照个人偏好对表格显示字段进行排序、隐藏等操作。同时，也可通过【恢复默认】将表格恢复到初始状态
 
 ![表格显示设置](./img/4-3-device-table-setting.png)
 
@@ -32,15 +30,19 @@ sidebar_position: 3
 🤖 权限：仅**组织管理员**拥有设定设备自定义字段的权限
 :::
 
-- **入口：**通过「组织管理 - 设置 - 设备字段配置 - 编辑配置」路径进入设置页面，管理员可依据实际需求添加相关设备字段。保存设置后，设备信息展示中会相应出现这些自定义字段。
+1. 在「组织管理 - 设置 - 自定义字段」页面，定义组织全局字段
+
+        ![组织自定义字段](./img/4-3-org-fields.png)
+
+2. 在「设备字段配置」页面，选择设备需要使用的字段
 
-- **注意事项：**若管理员删除某一设备自定义字段，该字段的所有数据将一并删除且无法恢复，因此操作时务必谨慎。
+        ![设置设备自定义字段](./img/4-3-setting-device-fields.png)
 
-![设置设备自定义字段](./img/4-3-setting-device-fields.png)
+3. 添加完成后，在创建与查看设备时，会相应出现这些自定义字段
 
-![设备自定义字段弹窗](./img/4-3-fields-popup.png)
+    ![带有自定义字段的设备表格](./img/4-3-device-table-fields.png)
 
-![带有自定义字段的设备表格](./img/4-3-device-table-fields.png)
+- **注意事项：** 若删除某一设备自定义字段，该字段的所有数据将一并删除且无法恢复，请谨慎操作。
 
 ## 设备信息编辑
 
@@ -57,12 +59,12 @@ sidebar_position: 3
 ## 设备与项目关联操作
 
 :::info
-🤖 权限：**组织成员及以上角色**可以分配设备到某个项目中
+🤖 权限：**组织管理员**可以分配设备到某个项目中
 :::
 
-### 分配设备到项目
+### 分配设备到项目 {#assign-devices-to-projects}
 
-设备添加到项目后，若安装了数据采集客户端，客户端将拉取项目中已开启的规则进行自动监听与诊断，也可在项目中创建采集任务采集数据。
+设备添加到项目后，若安装了数据采集客户端，客户端将拉取项目中已启用的规则进行自动监听与诊断，也可在项目中创建采集任务采集数据。
 
 在设备列表选定设备后点击【添加关联项目】按钮；
 
@@ -74,35 +76,37 @@ sidebar_position: 3
 
 ### 从项目移除设备
 
-若项目不再需要某设备，可在项目中将其【从本项目移除】。移除后设备仍保留在组织项目中，但项目不再接收该设备采集的数据，后续若有需要仍可再次添加该设备到本项目进行数据采集。
+若项目不再需要某设备，可在项目中将其【从本项目移除】。移除后设备仍保留在组织中，但项目不再接收该设备采集的数据，后续若有需要仍可再次添加该设备到项目中。
 
 ![移除项目设备](./img/4-3-delete-project-device.png)
 
-## 设备准入
+## 启用设备 {#enable-device}
 
 :::info
-🤖 权限：**仅组织管理员**可进行设备准入操作
+🤖 权限：**仅组织管理员**可进行设备启用操作
 :::
 
-完成添加设备后，设备列表会出现【准入】的操作按钮，在设备详情页还可单独准入「数据采集」和「远程控制」模块。
+完成添加设备后，设备列表会出现【启用客户端】的操作按钮。
 
-![准入设备](./img/4-3-access-device-2.png)
+![启用设备](./img/4-3-access-device.png)
 
-「数据采集」准入后，机器端程序将按规则采集数据并自动上传至对应项目；
+启用客户端后，若「数据采集」在线，机器端程序将按规则采集数据并自动上传至对应项目；若「远程控制」在线，用户可对机器进行 SSH 连接、结合 [coBridge](https://github.com/coscene-io/coBridge) 实时可视化设备
 
-「远程控制」准入后，用户可通过刻行平台对机器进行 SSH 连接、实时可视化等操作。
+### 查看客户端信息
 
-### 查看数采客户端日志
+在设备端执行以下命令，可查看客户端的版本、日志信息。
 
-在设备端执行以下命令，可查看数据采集客户端的日志信息，方便用户了解数据采集过程中的情况。
-
-```go
-journalctl --user-unit=cos -f -n 50
-```
+| 名称 | 查看版本 | 查看日志 |
+| ---- | -------- | -------- |
+| 数据采集（coScout）v1.1.2 及以上 | `~/.local/bin/cos --version` | `tail -f ~/.local/state/cos/logs/cos.log` |
+| 数据采集（coScout）v1.1.2 以下 | `~/.local/bin/cos --version` | `journalctl -fu cos` |
+| 远程控制（coLink） | `colink --version` | `journalctl -fu colink` |
 
 ### 卸载数据采集、远程控制客户端
 
-在设备端中，执行以下命令可卸载数据采集、远程控制客户端，执行过程中需观察输出直至卸载流程完成
+在设备端中，执行以下命令可卸载数据采集、远程控制客户端，执行过程中需观察输出直至卸载流程完成。
+
+注意：若数采客户端安装在 root 用户下，卸载时需切换为 root 用户。
 
 ```yaml
 /bin/bash -c "$(curl -fsSL https://download.coscene.cn/coscout/uninstall.sh)"
@@ -113,18 +117,16 @@ journalctl --user-unit=cos -f -n 50
 ## 删除设备
 
 :::info
-🤖 权限：当设备**已准入时，只有组织管理员**可删除；若设备**无准入信息，组织成员及以上角色**均可删除
+🤖 权限：若设备**为填写信息添加的设备，组织成员及以上角色**均可删除；其余设备仅组织管理员可删除
 :::
 
 在设备列表选择要删除的设备并点击【删除设备】，经二次确认后即可删除。当删除设备之后
 
-1. 已准入设备将取消准入，无法自动上传数据
-
-2. 组织中将清除该设备及来自设备端的请求
-
-3. 记录中将无法添加该设备
-
-4. 记录中将无法查看该设备的详细信息
+1. 组织中将清除该设备及来自设备端的请求
+2. 记录中将无法添加该设备
+3. 记录中将无法查看该设备的详细信息
+4. 项目中无法添加该设备
+5. 已添加该设备的项目，在项目设备中将同步被删除
 
 ![删除设备](./img/4-3-device-delete.png)