---
url: /wiki/pi-client-skill-guide.md
---
# Pi-fit 客户端安装与 Skill 使用说明

本文档用于指导用户从发布页下载并安装 Pi 客户端，完成登录、激活、工作区设置，以及 Skill 的安装和使用。按照以下步骤操作，即可完成基础环境准备并开始使用技能对话。

***

## 1. 下载客户端

进入发布页后，找到对应系统版本的安装包并点击下载。

> 建议：
>
> * Windows 用户下载 `.exe` 安装包。
>
> * 下载完成后，如浏览器提示“可能不安全”，请确认来源为官方发布页后再继续。
>
> * 若下载速度较慢，可尝试刷新页面或更换网络环境。

下载地址：
![](/static-file/3926015e-be11-4a07-a422-01d3166a6a94/b4c57781-bcb2-477a-a85a-8453398bd552.png)

***

## 2. 安装 Pi 客户端

下载完成后，找到安装包文件，双击运行安装程序。
![](/static-file/55dba88a-45ec-4779-b163-2f3ba17e15de/a2e6edf8-38f0-4e50-8514-f9cd76507e7d.png)

进入安装界面后，根据提示继续操作。通常保持默认安装路径即可，如需安装到指定目录，也可以自行选择。

![](/static-file/6b99c607-af95-4a30-9534-4b44333b3675/3efd9f0e-9889-40ad-a1b1-ac5f8e8cd099.png)

安装完成后，点击 **完成** 退出安装向导。

![](/static-file/800197ed-5ca2-4d53-912a-a25b1c1f6b72/f49d939c-c83f-4400-abc6-4499ca578f28.png)

> 安装提示：
>
> * 如果系统弹出安全确认窗口，请选择允许或继续运行。
>
> * 如果安装失败，请先关闭正在运行的 Pi 客户端后重试。
>
> * 建议安装完成后从桌面快捷方式或开始菜单启动程序。

***

## 3. 登录与激活

启动 Pi 客户端后，会进入登录页面。
![](/static-file/dbe52909-32ae-47ec-a454-0627b9624b44/354bb3c6-d00c-41bb-89d0-cf2560a5561e.png)

根据页面提示完成登录操作。
![](/static-file/ead46a50-929f-4807-b7cd-2261c3232c89/49839a6e-324a-4e51-9d98-68e59d69aeb9.png)

首次使用时可能需要完成账号激活。按照提示等待管理员分配角色后继续。

![](/static-file/c3feb14e-9751-4c45-89bc-0bcd7c7a07ae/d909d51e-7e73-4c1d-973b-3a0cc3d2db8a.png)

激活完成后，点击 **钉钉登录**，登录成功后会进入 Pi 首页。
![](/static-file/0bd5bc7b-1135-4cc9-a828-e13908cec608/b36d0bcf-56e2-4157-aa58-25fe13ba0823.png)

> 登录说明：
>
> * 请确保钉钉账号已具备使用权限。
>
> * 如果扫码或跳转登录失败，请检查网络连接，并重新打开客户端尝试。
>
> * 如提示账号未授权，请联系管理员开通权限。

***

## 4. 打开工作区

进入首页后，需要打开一个工作区。工作区用于存储项目文件、生成文件以及 Skill 运行过程中产生的相关内容。

点击 **打开工作区**，选择一个本地文件夹作为工作目录。
![](/static-file/2a082052-1d58-4cc9-996f-488776b30d80/a65c22be-328f-45ec-918d-40301da84244.png)

选择完成后，客户端会加载该目录。工作区打开成功后，即可进入正常使用状态。

打开完成后：

正常使用状态：

![](/static-file/9a0a64ca-6e0f-4f09-8d34-4cfb901c3f4c/7f08ecba-dc56-42c5-9502-6f1edadcfc12.png)

> 工作区建议：
>
> * 建议为每个项目单独创建一个文件夹，便于管理生成内容。
>
> * 文件夹路径尽量不要包含特殊字符，避免部分工具读取失败。
>
> * 如果是团队协作项目，可选择共享盘或项目统一目录。

***

## 5. 安装 Skill

Skill 是 Pi 中的技能扩展，可用于执行特定任务或增强对话能力。进入客户端后，找到 Skill 安装入口。

点击安装 Skill：
![](/static-file/7fcee3cb-4bfd-47b3-b36d-916d4446b0f4/ac9eface-ac0a-4ed8-b993-1bcea0ac8159.png)

根据提示选择需要安装的 Skill，并确认安装。

![](/static-file/65bfea9b-89a7-4822-abab-0f2ea49dc885/e4839dfe-72d9-487b-a5b4-8c346df9710a.png)

安装完成后，Skill 会出现在可用技能列表中。

> 注意事项：
>
> * 安装 Skill 前请确认当前网络正常。
>
> * 如果安装后没有显示，可尝试重启 Pi 客户端。
>
> * 如果 Skill 依赖特定文件或环境，请先根据对应说明完成准备工作。

***

## 6. 使用 Skill

在对话输入框中输入 `/`，系统会弹出可用技能列表。

使用 Skill：输入 `/` 选择技能。
![](/static-file/e1e73442-00bb-4140-9481-595290e08de4/e217bdfc-35a3-4b46-977d-40f4b339bf22.png)

选择目标 Skill 后，输入你的需求或任务描述，即可开始对话。

开始对话：
![](/static-file/94483dd5-c18a-483c-96a8-1b5705bcf9c0/ea0a7228-eb99-435a-996b-994024cde660.png)
![](/static-file/fa7015f7-6530-4aed-928e-8b1ebcaa8c97/6cff2963-9856-433c-b68d-ec1d45bff26e.png)

> 使用建议：
>
> * 描述任务时尽量明确目标、输入内容和期望输出。
>
> * 如果任务涉及文件，请先确认文件已放在当前工作区中。
>
> * 如需修改生成结果，可以继续在对话中说明修改要求。

***

## 7. 常见问题

### 7.1 安装包无法运行怎么办？

可以尝试以下方法：

1. 确认安装包是否下载完整。

2. 右键安装包，选择“以管理员身份运行”。

3. 检查杀毒软件或系统安全策略是否拦截。

4. 删除安装包后重新下载。

### 7.2 登录失败怎么办？

可以检查：

1. 当前网络是否正常。

2. 钉钉账号是否已开通权限。

3. 客户端版本是否为最新版本。

4. 退出客户端后重新打开再尝试登录。

### 7.3 Skill 安装成功但无法使用怎么办？

可以尝试：

1. 重启 Pi 客户端。

2. 确认当前已打开工作区。

3. 在输入框输入 `/` 查看技能是否出现在列表中。

4. 如仍无法使用，请联系管理员检查 Skill 配置。

### 7.4 工作区应该选择哪里？

建议选择一个专门用于当前项目的文件夹，例如：

D:\PiWorkspace\项目名称

这样可以避免多个项目文件混在一起，也方便后续查找和备份。

***

## 8. 快速流程总结

1. 打开发布页，下载客户端安装包。

2. 双击安装包，完成安装。

3. 启动 Pi 客户端，登录并完成账号激活。

4. 点击钉钉登录进入首页。

5. 打开工作区，用于存储项目文件和生成内容。

6. 安装所需 Skill。

7. 在输入框输入 `/`，选择 Skill 并开始对话。

完成以上步骤后，即可正常使用 Pi 客户端和 Skill 功能。

---

---
url: /wiki/pi-skillhub-publish.md
---
# SkillHub 发布 Skill 操作说明

本文档用于说明如何将已经制作完成的 Pi Skill 打包为 ZIP 文件，并发布到 SkillHub 平台，供其他用户下载、安装和使用。

***

## 1. 发布前准备（可跳过，使用Pi直接检查）

在发布 Skill 之前，需要先确认 Skill 文件夹已经整理完成。

一个标准 Skill 通常包含：

skill-name\
├── SKILL.md\
├── docs\
│   └── 相关说明文档.md\
├── templates\
│   └── 模板文件.md\
└── scripts\
   └── 可选脚本文件

其中必须包含：

| 文件/目录 | 是否必需 | 说明 |
| --- | --- | --- |
| `SKILL.md` | 必需 | Skill 主说明文件 |
| `docs` | 可选 | 存放知识库、操作手册、FAQ 等资料 |
| `templates` | 可选 | 存放输出模板 |
| `scripts` | 可选 | 存放辅助脚本 |

发布前重点检查：

1. `SKILL.md` 是否存在。

2. `SKILL.md` 顶部是否包含 `name` 和 `description`。

3. Skill 文件夹名称是否与 `name` 保持一致。

4. 是否删除了无关临时文件。

5. 是否确认没有包含敏感信息，例如数据库密码、服务器私钥、Token 等。

6. 是否已在本地 Pi 中测试可以正常识别和使用。

***

## 2. SKILL.md 基础要求（可跳过，使用Pi直接检查）

`SKILL.md` 文件顶部需要包含 frontmatter，例如：

\---\
name: my-demo-skill\
description: 当用户需要整理项目资料、生成说明文档、汇总文件内容或按照固定流程输出结果时使用本技能。\
\---\
​\
\# My Demo Skill\
​\
\## 使用场景\
​\
当用户提出资料整理、文档生成、流程说明、表格汇总等需求时，使用本技能。\
​\
\## 操作规则\
​\
1\. 先读取当前工作区相关文件。\
2\. 根据用户需求整理内容。\
3\. 输出结构清晰的 Markdown 文档。\
4\. 如果信息不足，先向用户确认。

字段说明：

| 字段 | 说明 |
| --- | --- |
| `name` | Skill 名称，建议与文件夹名称一致 |
| `description` | Skill 描述，用于告诉 Pi 什么时候使用该技能 |

> `description` 必须写清楚适用场景，否则用户安装后 Pi 可能无法准确识别或调用该 Skill。

***

## 3. 打包 Skill，可以直接使唤Pi打包Skill，并打包成zip

发布前需要将整个 Skill 文件夹压缩为 ZIP 文件。

![](/static-file/46de0450-3076-4d4e-9f7f-12b008d64682/fd5719ae-4744-4bb0-be31-c13664943880.png)

### 3.1 正确打包方式

假设 Skill 文件夹名称为：

my-demo-skill

压缩后应得到：

my-demo-skill.zip

ZIP 内部结构应为：

my-demo-skill.zip\
└── my-demo-skill\
   ├── SKILL.md\
   ├── docs\
   └── templates

### 3.2 不推荐的打包方式

不要只压缩 `SKILL.md` 文件：

my-demo-skill.zip\
└── SKILL.md

不推荐原因：缺少外层 Skill 文件夹，用户解压后容易放错目录，也不利于多个 Skill 管理。

***

## 4. 登录 SkillHub

打开浏览器，访问发布地址：

https://skillhub.singzer.cn/

进入首页后，可以看到 SkillHub 管理页面。

首页界面如下：

![](/static-file/cbfe8c2d-ee88-4505-82a4-8357593e07a2/48feb5ec-c6d9-4d57-8bc4-c913ef47034e.png)
点击右上角登录
![](/static-file/0eb37cdb-faec-4bba-9303-56167f592163/533d1e1f-eb96-4eb2-9eff-17f516ff27c6.png)
登录成功后进入管理首页。

***

## 5. 进入发布页面

在 SkillHub 首页或管理页面中，找到发布入口，进入 Skill 发布页面。

发布页面如下：

![](/static-file/d801ce35-99d5-4189-abd9-27a2163261c2/d858deff-4ab5-4a8f-b9b5-754e4d68f151.png)

发布 Skill 的核心操作是：

> 将 Skill 打包成 ZIP 文件，然后上传发布。

***

## 6. 上传并发布 Skill

在发布页面中，按照页面提示填写或选择相关内容。

一般需要操作以下内容：

1. 点击上传按钮。

2. 选择本地已经压缩好的 `.zip` 文件。

3. 确认 Skill 名称、描述或版本信息。

4. 点击确认发布。
   ![](/static-file/cbf986ba-9470-428b-8910-5c02f1d60a8e/2ce2289c-3922-4dee-88c9-0613fba6e1ea.png)

5. 等待管理员审核完成即可。
   ![](/static-file/eba2f160-91dd-4973-8bd5-29d1489ec75a/b8784d1b-7a16-4bd7-a1b0-3f61da8dba2a.png)

***

## 7. 发布成功后的检查

可在“我的技能”页面中查看已发布的技能
![](/static-file/ee2fdfb5-24d5-4834-a893-0b12b5ae4abf/f5ec8e73-147a-4fb9-89bf-d68d5f458b7d.png)
打开PI客户端，点击“刷新SkillHub”按钮，能够看到新发布的Skill，点击安装，安装成功后，就可以正常测试使用。
![](/static-file/5f54790c-47c7-4c4e-8829-495b5b6ab6e7/a814c598-c254-4982-a792-070fcd7bf0a5.png)

***

### 7.1 上传失败怎么办？

可以检查：

1. 网络是否正常。

2. ZIP 文件是否过大。

3. ZIP 文件是否损坏。

4. 文件名是否包含特殊字符。

5. 是否已经登录过期，重新登录后再试。

### 7.2 发布后用户看不到 Skill 怎么办？

可能原因：

1. 用户没有下载最新版。

2. 用户解压后目录结构不正确。

3. 用户没有把 Skill 放到正确目录。

4. 用户没有重启 Pi。

5. `SKILL.md` 中 `description` 为空或格式错误。

### 7.3 Skill 无法正常触发怎么办？

检查 `description` 是否写得过于简单。

建议将：

description: 文档技能

改为：

description: 当用户需要根据项目资料生成操作说明、安装文档、使用手册、验收报告或维护记录时使用本技能。

### 7.4 更新 Skill 应该怎么发布？

建议：

1. 修改 Skill 文件。

2. 更新版本号。

3. 重新压缩 ZIP。

4. 在 SkillHub 上传新版本。

5. 在更新说明中写清楚修改内容。

***

## 8. 推荐发布说明模板

每次发布时，可以附带以下说明：

\# my-demo-skill 发布说明\
​\
\## 版本\
​\
v1.0.0\
​\
\## 功能简介\
​\
本 Skill 用于整理项目资料，并根据固定模板生成 Markdown 操作说明文档。\
​\
\## 安装方法\
​\
1\. 下载 \`my-demo-skill.zip\`。\
2\. 解压得到 \`my-demo-skill\` 文件夹。\
3\. 将文件夹复制到：\
​\
  C:\Users\admin\\.pi\agent\skills\
​\
4\. 重启 Pi。\
5\. 在输入框输入 \`/\`，选择 \`my-demo-skill\` 使用。\
​\
\## 更新说明\
​\
\- 首次发布。\
​\
\## 注意事项\
​\
\- 请勿删除 Skill 文件夹内的 \`docs\` 和 \`templates\` 目录。\
\- 请确认 Pi 已打开正确工作区。

***

## 9. 快速流程总结

1. 准备 Skill 文件夹。

2. 确认 `SKILL.md` 内容完整。

3. 将整个 Skill 文件夹压缩为 ZIP。

4. 打开 SkillHub：`https://skillhub.singzer.cn/`。

5. 使用账号 `admin` 登录。

6. 进入发布页面。

7. 上传 ZIP 文件。

8. 填写名称、描述、版本和更新说明。

9. 点击发布。

10. 发布成功后下载测试。

11. 将下载和安装说明发给用户。

完成以上步骤后，Skill 即可通过 SkillHub 发布并分发给用户使用。

---

---
url: /wiki/pi-introduction.md
---
# 介绍

> 该页面暂无正文内容。

---

---
url: /wiki/wiki-placeholder.md
---
# 1

> 该页面暂无正文内容。

---

---
url: /wiki/developer-docs.md
---

# 研发文档

研发文档用于沉淀研发侧稳定资料，优先放产品线、架构、调试、开发流程和参考文档。

## 目录

## 维护口径

| 类型 | 放置位置 |
| --- | --- |
| 基础概念、网络原理、虚拟化入门 | 概念入门 |
| 产品能力、业务边界、系统架构 | 产品线 |
| 远程访问、现场联调、网络配置、虚拟机、容器 | 开发调试 |
| 生产环境、部署维护、巡检排障 | 运维文档 |
| 协议文件、PDF、外部资料沉淀 | 参考文档 |
| 临时项目问题 | 先记录到对应产品线，稳定后再整理 |

---

---
url: /wiki/concepts-basics.md
---

# 概念入门

概念入门用于解释研发、交付和现场排障中反复出现的基础概念。先理解这些概念，再看产品线、开发调试和运维文档，会更容易判断问题属于软件、系统还是网络。

## 分类

## 阅读建议

| 如果你想理解 | 先看 |
| --- | --- |
| 程序为什么打不开、服务为什么没启动、日志应该看哪里 | 软件运行原理 |
| 为什么同一个软件在不同系统上表现不同、信创适配为什么复杂 | 操作系统与处理器架构 |
| 为什么现场设备连不上、端口不通、远程桌面打不开 | 网络和常见协议 |

## 维护口径

* 每个概念优先解释“它是什么、现场为什么会遇到、排查时看哪里”。
* 内容变多以后再继续拆小节，不先按术语堆目录。
* 与具体产品强相关的内容放到产品线，概念页只保留通用解释。

---

---
url: /wiki/concepts-basics/software-runtime.md
---

# 软件运行原理

软件运行原理解释一个基础问题：软件是什么，为什么能在电脑、服务器、工控机、浏览器或容器里跑起来。

软件不是“屏幕上的按钮”。按钮、窗口、网页和服务端接口只是表现形式。真正运行起来的，是 CPU 能执行的机器指令、操作系统能加载的程序、运行时能解释的脚本、浏览器能解析的资源，以及它们依赖的配置、权限、文件、网络和外部服务。

## 概览

排查“软件不能运行”时，先把问题拆成几个层次：

| 层次 | 关键问题 | 常见现象 |
| --- | --- | --- |
| 文件形态 | 它是二进制、脚本、网页资源还是容器镜像？ | 找不到程序、格式不对、双击没反应 |
| 安装包 | 它是系统安装包、语言依赖包还是容器镜像？ | 安装失败、依赖缺失、架构不匹配 |
| 系统与架构 | 当前系统和 CPU 能不能运行它？ | `Exec format error`、安装包不兼容 |
| 加载与依赖 | 运行时、动态库、外部服务是否齐全？ | 缺库、版本不兼容、接口报错 |
| 启动方式 | 谁启动它，以什么参数和目录启动？ | 手动正常，服务失败 |
| 权限 | 运行用户能不能读取、执行、写入资源？ | `Permission denied`、拒绝访问 |
| 配置 | 程序实际读到什么配置？ | 端口错、连错数据库、生产/测试环境混用 |
| 观测 | 日志、退出码、端口、网络请求说明了什么？ | 页面报错但后端日志才有真正原因 |

本文按参考手册方式组织。读者不需要一次读完，可以按问题跳到对应章节。

## 软件形态

### 二进制可执行文件

二进制可执行文件已经被编译成特定系统和处理器架构能加载的机器代码。

| 平台 | 常见形态 | 关注点 |
| --- | --- | --- |
| Windows | `.exe`、`.dll` | 系统版本、VC 运行库、管理员权限、杀毒软件拦截 |
| Linux | 常见无扩展名、`.so` | 架构、可执行权限、动态库、运行用户 |
| macOS | `.app`、Mach-O 二进制、`.dylib` | 签名、公证、权限、架构 |

同一份源码可能构建出多个产物。例如 Windows x86\_64、Linux x86\_64、Linux ARM64、LoongArch 产物不能随便混用。

### 脚本和运行时

脚本文件本身通常不是直接给 CPU 执行，而是交给解释器或运行时读取。

| 类型 | 例子 | 运行方式 |
| --- | --- | --- |
| Shell 脚本 | `.sh` | `bash script.sh` 或 `./script.sh` |
| Python | `.py` | `python app.py` |
| Node.js | `.js`、`.mjs` | `node app.js` |
| PowerShell | `.ps1` | `pwsh script.ps1` 或 Windows PowerShell |
| 批处理 | `.bat`、`.cmd` | `cmd.exe` 执行 |

脚本运行失败时，要同时检查脚本内容、解释器版本、依赖包、当前目录、环境变量和权限。

### 字节码和虚拟机

有些语言先生成中间产物，再由虚拟机或运行时执行。

| 技术 | 常见产物 | 关注点 |
| --- | --- | --- |
| Java | `.class`、`.jar` | JDK/JRE 版本、启动参数、内存限制 |
| .NET | `.dll`、`.exe` | .NET Runtime 版本、系统兼容性 |
| WebAssembly | `.wasm` | 运行宿主、浏览器或边缘运行时支持 |

### 网页资源和客户端壳

Web 前端由浏览器加载 HTML、CSS、JavaScript、图片和字体。Electron、Tauri 等桌面客户端常把网页资源和本地能力打包在一起。

| 形态 | 关注点 |
| --- | --- |
| 浏览器页面 | 资源路径、接口地址、缓存、证书、跨域 |
| Electron 客户端 | 打包资源、自动更新、本地缓存、系统依赖 |
| Tauri 客户端 | WebView、系统权限、本地后端能力 |

页面打不开不一定是“前端坏了”。要区分静态资源 404、接口 404、接口 500、证书失败、浏览器缓存和网络不通。

### 容器镜像

容器镜像打包了文件系统、程序、依赖和启动命令。它不是一个完整虚拟机，通常共享宿主机内核。

| 内容 | 例子 |
| --- | --- |
| 文件系统 | `/app`、`/usr/lib`、配置模板 |
| 程序 | API 服务、数据库、任务进程 |
| 依赖 | 动态库、运行时、字体、证书 |
| 启动命令 | `CMD`、`ENTRYPOINT` |

容器启动失败时，除了看应用日志，还要看镜像架构、环境变量、挂载目录权限、端口映射和网络。

## 包、安装包和包管理器

“包”是软件分发的基本单位。一个包通常不只是一个可执行文件，而是一组文件和元数据。

| 内容 | 说明 |
| --- | --- |
| 程序文件 | 可执行文件、动态库、脚本、静态资源 |
| 元数据 | 名称、版本、架构、依赖、维护者、描述 |
| 安装脚本 | 安装前后执行的动作，例如创建用户、注册服务、刷新缓存 |
| 签名 / 校验 | 验证包来源和完整性 |
| 卸载信息 | 记录哪些文件由这个包安装，便于升级和卸载 |

包管理器负责安装、升级、卸载、查询软件包，并处理依赖关系。软件仓库是包管理器下载软件包的来源。

### 系统安装包

| 平台 / 发行版 | 常见格式 | 常见包管理器 | 关注点 |
| --- | --- | --- | --- |
| Windows | `.exe`、`.msi`、`.msix` | Windows Installer、winget、Chocolatey、Scoop | 管理员权限、UAC、安装路径、VC 运行库、静默安装参数 |
| macOS | `.app`、`.dmg`、`.pkg` | Installer、Homebrew | 签名、公证、Gatekeeper、Intel / Apple Silicon 架构 |
| Debian 系 Linux | `.deb` | `apt`、`dpkg` | 依赖包、软件源、系统版本、CPU 架构 |
| Red Hat 系 Linux | `.rpm` | `dnf`、`yum`、`rpm` | 依赖包、仓库、SELinux、系统库版本 |
| Arch 系 Linux | `.pkg.tar.zst` | `pacman` | 滚动更新、依赖版本、AUR 风险 |
| Alpine Linux | `.apk` | `apk` | musl libc、轻量容器、glibc 兼容问题 |
| Android | `.apk`、`.aab` | 系统安装器、应用商店、MDM | ABI、签名、系统权限、厂商定制 |
| 容器 | OCI image、Docker image | Docker、Podman、containerd | 镜像架构、基础镜像、入口命令、挂载权限 |

不要只看文件后缀。`.deb` 也分 `amd64`、`arm64`、`loongarch64`；`.rpm` 也分发行版和系统库版本。能安装不代表能正常运行，能运行不代表所有外设和服务都可用。

### 语言依赖包

很多开发语言还有自己的包生态。它们解决的是“程序内部依赖”，不是完整替代系统包管理器。

| 生态 | 常见文件 / 工具 | 关注点 |
| --- | --- | --- |
| Node.js | `package.json`、`node_modules`、npm、pnpm、yarn | Node 版本、锁文件、原生模块架构 |
| Python | `requirements.txt`、`pyproject.toml`、pip、venv | Python 版本、虚拟环境、系统库依赖 |
| Java | Maven、Gradle、`.jar` | JDK 版本、仓库镜像、依赖冲突 |
| .NET | NuGet、`.nupkg` | Runtime 版本、目标框架 |
| Rust | Cargo、`Cargo.toml` | 目标架构、系统库、交叉编译 |
| Go | Go modules、`go.mod` | Go 版本、CGO、目标系统和架构 |

语言包经常依赖系统能力。例如 Python 的图像库可能依赖系统图形库，Node 的原生模块可能需要按 CPU 架构重新编译，Java 程序可能需要系统字体和证书。

### 包管理和现场排障

| 现象 | 常见原因 | 排查方向 |
| --- | --- | --- |
| 安装包提示架构不支持 | 下载了错误架构 | 对比 `uname -m`、系统信息和包名 |
| 安装时缺依赖 | 软件源不完整、系统版本太旧 | 检查仓库、离线依赖包、厂商源 |
| 安装成功但启动失败 | 运行库、配置、权限、服务未就绪 | 看启动日志和系统日志 |
| 升级后功能异常 | 依赖版本变化、配置迁移失败 | 看升级日志、配置差异、回滚方案 |
| 离线现场无法安装 | 没准备完整依赖 | 提前做离线包、镜像源或安装介质 |
| 同一安装包有的机器能跑有的不能 | 系统补丁、架构、库版本、驱动不同 | 记录完整环境，不只记录系统名称 |

交付安装包时，建议同时标明系统、架构、版本和安装方式，例如 `product-linux-arm64-v1.2.3.deb`、`product-windows-x64-v1.2.3.msi`、`product-loongarch64-v1.2.3.tar.gz`。

## 从源码到运行

源码是给人和工具看的。运行时，源码必须被编译、解释、打包或加载。

```mermaid
flowchart LR
  A[源码\nGo / C / Rust / Java / JS] --> B{构建方式}
  B -->|编译| C[二进制可执行文件]
  B -->|打包| D[前端静态资源 / 客户端包]
  B -->|解释执行| E[脚本 + 解释器]
  B -->|字节码| F[虚拟机 / 运行时]
  C --> G[操作系统加载运行]
  D --> H[浏览器 / 客户端壳加载]
  E --> I[运行时读取执行]
  F --> I
```

| 语言/技术 | 常见运行方式 | 现场关注点 |
| --- | --- | --- |
| Go / Rust / C / C++ | 编译成二进制 | 架构是否匹配、依赖库是否缺失、权限是否可执行 |
| Java | JVM 运行字节码或 jar | JDK/JRE 版本、启动参数、内存限制 |
| Node.js | Node 运行 JS | Node 版本、依赖包、环境变量 |
| Python | Python 解释器运行脚本 | Python 版本、虚拟环境、pip 依赖 |
| Web 前端 | 浏览器加载 HTML/CSS/JS | 资源路径、浏览器兼容、接口地址、缓存 |
| Electron | Chromium + Node + 本地壳 | 系统依赖、打包资源、自动更新、权限 |

## 程序如何被操作系统启动

当你双击一个程序，或在命令行执行一个文件时，操作系统大致会做这些事：

1. 找到可执行文件。
2. 判断当前系统和处理器能不能识别它。
3. 检查执行权限。
4. 加载程序本身和它依赖的动态库。
5. 创建进程，分配内存、文件句柄、网络资源。
6. 设置参数、环境变量和工作目录。
7. 把控制权交给程序入口。

对应到现场问题：

| 现象 | 可能原因 |
| --- | --- |
| 双击没反应 | 架构不匹配、依赖缺失、权限不足、被安全软件拦截 |
| 提示找不到库 | 动态库缺失、库版本不对、搜索路径不对 |
| Linux 下提示 `Permission denied` | 文件没有执行权限，或目录权限不足 |
| Linux 下提示 `Exec format error` | 程序架构和系统架构不匹配 |
| 程序启动后马上退出 | 配置错误、端口冲突、依赖服务不可用 |

排查时不要只看“能不能打开”，要确认系统类型、CPU 架构、启动方式、运行用户、工作目录、参数、环境变量和日志。

## 命令行环境

### 终端、Shell 和 CLI

终端是输入输出通道，Shell 是解释命令的程序，CLI 是命令行界面这种交互方式。

| 概念 | 说明 |
| --- | --- |
| 终端 | 负责接收键盘输入、显示程序输出。现代常见为终端模拟器或 SSH 会话 |
| Shell | 读取命令、解析参数、启动程序，例如 `bash`、`zsh`、`cmd.exe`、PowerShell |
| CLI | Command Line Interface，命令行界面，例如 `git`、`ssh`、`curl` |

Shell 读取一行文本，判断这是内置命令、脚本，还是某个可执行文件，然后请操作系统启动对应程序。

```bash
curl https://example.com
ls -l /opt
./install.sh --port 8080
```

### 命令、参数和退出码

命令行程序靠文本输入输出和退出码表达结果。

| 概念 | 说明 |
| --- | --- |
| 命令 | 要执行的程序名或脚本名 |
| 参数 | 告诉程序要做什么，例如 `--port 8080` |
| 标准输出 stdout | 正常结果输出 |
| 标准错误 stderr | 错误、警告、诊断信息 |
| 退出码 | 程序结束状态，通常 `0` 表示成功，非 `0` 表示失败 |

排查 CLI 时要保留完整命令和完整输出。只说“运行失败”不够，需要知道当前目录、执行用户、参数、stdout、stderr 和退出码。

## Unix 传统

Unix 系统把命令行、进程、文件和权限的组合模式做得很彻底。20 世纪 60 年代末，贝尔实验室的 Ken Thompson、Dennis Ritchie 等人从大型分时系统的经验里，做出了一个更小、更可组合的系统。后来 C 语言、Unix、BSD、GNU/Linux、macOS、Android、服务器运维工具链，都沿着这条线继续发展。

Unix 给后来的软件世界留下了几个重要想法：

| 想法 | 含义 | 现场价值 |
| --- | --- | --- |
| 小工具做一件事 | `cat`、`grep`、`awk`、`curl`、`ssh` 各自解决清晰的小问题 | 出问题时可以一步步拆开验证 |
| 文本作为接口 | 命令输入和程序输出多用文本表达 | 日志、脚本、自动化都容易串起来 |
| 管道组合 | 一个程序的输出可以接到另一个程序的输入 | `cat app.log \| grep ERROR \| tail` 可以快速过滤问题 |
| 一切皆文件 | 普通文件、设备、管道、Socket 都尽量用类似文件的方式访问 | 理解路径、权限、句柄、日志、设备访问会更统一 |
| 用户和权限 | 程序以某个用户身份运行，只能访问被授权的资源 | 解释大量“手动能跑，服务跑不了”的问题 |

“一切皆文件”不是绝对规则，而是一个有用的理解模型。普通文件是文件，日志是文件，配置是文件；很多设备也暴露成路径，例如 Linux 的 `/dev/ttyUSB0` 串口设备；进程、端口、系统状态也常通过类似文件或文本接口查看。

## DOS、cmd 和 PowerShell

命令行不是 Unix 独有的。个人电脑普及后，很多人第一次接触命令行是在 DOS 里。

DOS 可以理解成早期个人电脑上的磁盘操作系统。机器启动后，用户看到的往往不是图形桌面，而是类似这样的提示符：

```bat
C:\>
```

这里的 `C:` 是盘符，`\` 是路径分隔符，`>` 后面等待用户输入命令。用户输入 `dir` 看目录，输入 `copy` 复制文件，输入程序名启动软件。很多批处理脚本用 `.bat` 或 `.cmd` 结尾，用来把一串命令自动跑完。

```bat
dir C:\data
copy app.exe D:\backup\
ping 192.168.1.1
```

Windows 9x 还和 DOS 关系很深；Windows NT 之后的命令提示符主要是 `cmd.exe`。它保留了很多 DOS 风格命令和习惯，但现代 Windows 的 `cmd.exe` 不是“真正的 DOS”。它是 Windows 里的命令解释器，运行在 Windows 的权限、进程、文件系统和安全模型之上。

PowerShell 也是 Shell，但它比传统 `cmd.exe` 更适合自动化系统管理。Unix 管道通常传文本，PowerShell 管道主要传对象，所以它可以更稳定地处理服务、进程、注册表、证书、JSON 等结构化信息。

```powershell
Get-Process
Get-Service | Where-Object Status -eq "Running"
Get-ChildItem C:\data | Sort-Object Length
```

常见差异：

| 主题 | DOS / cmd | Unix Shell | PowerShell |
| --- | --- | --- | --- |
| 常见提示符 | `C:\>` | `$` 或 `#` | `PS C:\>` |
| 路径习惯 | `C:\data\app.exe` | `/opt/app/app` | 两种路径都能处理，Windows 下常见 `C:\...` |
| 脚本后缀 | `.bat`、`.cmd` | `.sh` | `.ps1` |
| 管道 | 文本为主 | 文本为主 | 对象为主 |
| 权限模型 | 早期 DOS 基本是单用户模型，现代 cmd 使用 Windows 权限 | `rwx`、用户、组、其他人 | Windows ACL、执行策略、管理员权限 |
| 常见用途 | 兼容老脚本、简单维护命令 | Linux/macOS/服务器运维 | Windows 自动化、系统管理、跨平台脚本 |

现场排障时，不要只问“是不是命令行”，要问清楚是哪一种命令行：

| 问题 | 为什么重要 |
| --- | --- |
| 是 `cmd.exe` 还是 PowerShell？ | 同一条命令的引号、变量、管道、转义规则可能不同 |
| 是 Windows 还是 Linux？ | 路径、权限、可执行文件格式、服务管理方式不同 |
| 是本机终端还是 SSH 远程终端？ | 当前用户、工作目录、网络位置都可能不同 |
| 是管理员权限还是普通用户？ | Windows 下很多安装、服务、设备操作需要管理员权限 |
| 是手动运行还是服务自动运行？ | 服务环境变量、工作目录、用户身份经常和手动终端不同 |

## 权限

### Unix-like 权限和 chmod

Unix-like 系统的基础权限通常分为三组：

| 对象 | 说明 |
| --- | --- |
| user / owner | 文件所有者 |
| group | 文件所属组 |
| others | 其他用户 |

每组又有三种基础权限：

| 权限 | 文件上的含义 | 目录上的含义 |
| --- | --- | --- |
| `r` read | 读取文件内容 | 列出目录内文件名 |
| `w` write | 修改文件内容 | 在目录内创建、删除、重命名文件 |
| `x` execute | 把文件当程序执行 | 进入或穿过这个目录 |

`chmod` 的意思是 change mode，用来修改这些权限位。

```bash
chmod +x install.sh
chmod 755 app
chmod 644 config.yaml
chmod -R u+rwX data/
```

| 命令 | 作用 |
| --- | --- |
| `chmod +x install.sh` | 给脚本增加执行权限，否则 `./install.sh` 可能提示 `Permission denied` |
| `chmod 755 app` | 所有者可读写执行，组和其他用户可读可执行，常用于可执行程序 |
| `chmod 644 config.yaml` | 所有者可读写，其他人只读，常用于普通配置文件 |
| `chmod -R u+rwX data/` | 递归给所有者读写权限，并给目录或已有可执行文件加执行权限 |

目录上的 `x` 不是“执行目录”，而是允许进入或穿过目录。服务用户如果没有某一级目录的 `x` 权限，即使最终文件本身可读，也可能读不到。

### Windows 权限

Windows 常见权限模型是 ACL、管理员权限和 UAC。Windows 的“拒绝访问”和 Linux 的 `Permission denied` 看起来像同一类问题，底层模型不同。

| 系统 | 常见权限问题 |
| --- | --- |
| Windows | ACL 不允许访问、没有管理员权限、UAC 拦截、文件被占用、执行策略限制 PowerShell 脚本 |
| Linux / Unix-like | `rwx` 不足、属主属组不对、目录缺少 `x` 权限、服务用户和手动用户不同 |

## 运行环境

### 依赖

很多软件不是孤立运行的。它可能依赖运行时、系统库、驱动或外部服务。

| 类型 | 例子 | 出问题时的表现 |
| --- | --- | --- |
| 语言运行时 | JVM、Node.js、Python、.NET Runtime | 版本不兼容、命令不存在、启动参数不支持 |
| 动态库 | `.dll`、`.so`、系统图形库、驱动库 | 缺库、库版本冲突、启动时报错 |
| 外部服务 | 数据库、Redis、对象存储、消息队列 | 程序能启动但接口报错或功能不可用 |
| 系统能力 | 字体、证书、打印服务、串口权限 | 页面乱码、HTTPS 失败、打印失败、设备打不开 |

所谓“部署环境”，就是把程序需要的运行时、依赖、配置、权限和外部服务准备好。

### 进程、服务和端口

程序运行起来后，在操作系统里通常表现为进程。长期运行的后台程序一般会被配置成服务。

| 概念 | 说明 | 现场关注点 |
| --- | --- | --- |
| 进程 | 正在运行的程序实例 | 是否存在、CPU/内存是否异常 |
| 服务 | 由系统管理的长期程序 | 是否启动、是否开机自启 |
| 守护进程 | 后台持续运行的服务进程 | 崩溃后是否自动拉起 |
| 端口监听 | 服务等待外部连接 | 是否监听正确 IP 和端口 |

一个 Web 后端如果启动成功，通常会监听某个端口。页面访问失败时，要区分是“程序没启动”“端口没监听”“网络不通”还是“接口本身报错”。

### 配置

同一份程序在不同现场表现不同，往往是因为配置不同。

| 配置来源 | 常见内容 | 常见问题 |
| --- | --- | --- |
| 配置文件 | 数据库地址、端口、账号、路径、功能开关 | 改错文件、格式错误、路径不存在 |
| 环境变量 | 运行模式、密钥、服务地址 | 变量没传进去、大小写写错 |
| 启动参数 | 监听端口、配置路径、日志级别 | 参数顺序错、参数不兼容 |
| 默认值 | 程序内置配置 | 忘记覆盖，导致连到默认地址 |

现场排障时，要确认“程序实际读到的配置”，不要只看你以为它读的是哪个文件。

### 日志、缓存和临时文件

不要只看页面提示。页面提示通常经过包装，真正原因经常在服务日志、浏览器网络请求或系统日志里。

| 类型 | 用途 | 常见问题 |
| --- | --- | --- |
| 应用日志 | 记录程序运行过程和错误 | 日志没开、路径不对、权限不足 |
| 系统日志 | 记录服务启动、崩溃、权限等系统事件 | 只看应用日志会漏掉启动失败原因 |
| 浏览器网络请求 | 查看前端请求哪个接口、返回什么 | 接口地址错、跨域、证书问题 |
| 缓存 | 减少重复计算或请求 | 旧数据未刷新、缓存污染 |
| 临时文件 | 保存运行过程中的中间结果 | 磁盘满、权限不足 |

## 前端、后端和数据库

一套业务系统通常不是一个程序，而是多个部分协作。

| 部分 | 主要职责 | 常见形态 |
| --- | --- | --- |
| 前端 | 展示页面，接收用户操作 | 浏览器页面、Electron 客户端、移动端页面 |
| 后端 | 处理业务逻辑，提供接口 | Java / Go / Node.js / Python 服务 |
| 数据库 | 持久保存业务数据 | MySQL、PostgreSQL、SQLite |
| 缓存 | 临时保存高频数据 | Redis、本地缓存 |

现场排障时先判断问题发生在哪一层：页面打不开通常先看前端资源和网络；按钮报错通常看接口；数据不对通常看后端逻辑和数据库。

## 虚拟机和容器

虚拟机和容器都能提供隔离环境，但隔离方式不同。

```mermaid
flowchart TB
  subgraph Type1["Type 1 裸机虚拟化"]
    H1[硬件] --> VMM1[虚拟机管理程序\nKVM / ESXi / PVE / Hyper-V]
    VMM1 --> VM1[虚拟机 A]
    VMM1 --> VM2[虚拟机 B]
  end

  subgraph Type2["Type 2 宿主虚拟化"]
    H2[硬件] --> OS2[宿主操作系统\nWindows / macOS / Linux]
    OS2 --> VMM2[虚拟机软件\nVMware / VirtualBox / Parallels]
    VMM2 --> VM3[虚拟机 A]
    VMM2 --> VM4[虚拟机 B]
  end

  subgraph Container["容器"]
    H3[硬件] --> OS3[宿主操作系统\nLinux]
    OS3 --> ENG[容器引擎\nDocker / Podman]
    ENG --> C1[容器 A\n共享内核]
    ENG --> C2[容器 B\n共享内核]
  end
```

| | Type 1 | Type 2 | 容器 |
| --- | --- | --- | --- |
| 隔离方式 | 完整虚拟硬件和系统 | 在宿主系统上跑完整虚拟机 | 共享宿主内核 |
| 性能 | 高 | 略低 | 高 |
| 启动速度 | 秒到分钟 | 秒到分钟 | 毫秒到秒 |
| 适合 | 服务器虚拟化、PVE、ESXi | 本机测试、桌面虚拟机 | Web 服务、数据库、CI |
| 不适合 | 轻量单服务快速启停 | 生产高密度部署 | 内核/驱动级隔离 |

选择建议：

| 场景 | 选择 |
| --- | --- |
| 跑 Web 服务 / 数据库 / API | 容器（Docker / Podman） |
| 编译代码 / CI 流水线 | 容器 |
| 需要完整 Linux 环境 + SSH | 虚拟机 或 WSL2 |
| 开发内核模块 / 驱动 | 虚拟机 |
| 需要不同架构（ARM / MIPS） | QEMU |
| 需要直通 GPU / USB | 虚拟机 |
| GPU 加速推理 | 容器 + NVIDIA Container Toolkit |
| 测试旧系统兼容性 | 虚拟机 |

## 常见故障

| 现象 | 先看什么 | 常见原因 |
| --- | --- | --- |
| 程序打不开 | 系统、架构、权限、依赖 | 包不匹配、缺运行库、被拦截 |
| 安装包装不上 | 包格式、CPU 架构、软件源 | `.deb` / `.rpm` 不匹配、架构不对、离线依赖缺失 |
| `Permission denied` | 运行用户、文件权限、目录权限 | 没有执行位、目录缺少 `x`、服务用户不同 |
| Windows 拒绝访问 | 管理员权限、ACL、文件占用 | UAC、权限不足、文件被其他进程占用 |
| 找不到库 | 动态库路径、运行时版本 | `.dll` / `.so` 缺失或版本不匹配 |
| 手动运行正常，服务失败 | 服务用户、工作目录、环境变量 | systemd/Docker/Nginx 下环境不同 |
| 页面 404 | 浏览器地址、前端资源、接口路径 | 路由配置、资源路径、反向代理、后端接口 |
| 页面 500 | 后端日志、数据库、外部服务 | 配置错误、依赖不可用、程序异常 |
| 端口访问失败 | 进程、端口监听、防火墙、代理 | 服务没启动、监听地址错、网络不通 |
| 打印/串口/USB 失败 | 设备文件、驱动、用户组 | 权限不足、驱动缺失、设备被占用 |

## 参考资料

| 资料 | 适合看什么 |
| --- | --- |
| Dennis M. Ritchie, [The Evolution of the Unix Time-sharing System](https://www.nokia.com/bell-labs/about/dennis-m-ritchie/hist.html) | Unix 从分时系统、Multics 背景中演化出来的历史 |
| Dennis M. Ritchie, Ken Thompson, [The UNIX Time-Sharing System](https://www.nokia.com/bell-labs/about/dennis-m-ritchie/cacm.html) | Unix 早期设计思想，包含文件、进程、Shell 等核心概念 |
| Microsoft Learn, [Windows Commands](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands) | Windows 命令行、Command shell、PowerShell 的官方说明 |
| Microsoft Learn, [`cmd`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd) | Windows `cmd.exe` 的参数和行为 |
| Microsoft Learn, [What is PowerShell?](https://learn.microsoft.com/en-us/powershell/scripting/overview) | PowerShell 的定位、Shell、脚本和对象管道 |
| The Open Group, [POSIX `chmod`](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/chmod.html) | `chmod` 在 POSIX 标准里的定义 |
| GNU Coreutils Manual, [`chmod` invocation](https://www.gnu.org/software/coreutils/manual/html_node/chmod-invocation.html) | GNU/Linux 常见 `chmod` 行为和选项 |
| Linux man-pages, [`chmod(1)`](https://man7.org/linux/man-pages/man1/chmod.1.html) | Linux 命令手册里的权限位、符号模式和八进制模式说明 |

---

---
url: /wiki/concepts-basics/operating-systems-architecture.md
---

# 操作系统与处理器架构

操作系统与处理器架构解释“程序跑在什么系统上、系统能不能兼容、驱动和硬件能不能工作”。

同一个软件在不同现场表现不同，常见原因不是业务代码变了，而是操作系统、发行版、CPU 架构、系统库、驱动、桌面环境、浏览器内核或安全策略不同。

## 概览

排查系统兼容性问题时，先确认以下信息：

![操作系统生态图谱](/illustrations/concepts-basics/operating-systems-ecosystem-map.png)

这张图把操作系统家族、Linux 发行版、云与虚拟化、嵌入式 / RTOS、国产桌面与服务器生态放在同一张地图里。阅读本章时可以先把它当作“方向图”：系统名称只是入口，真正影响兼容性的通常是内核、发行版体系、处理器架构、包管理、驱动和厂商生态。

| 层次 | 要确认什么 | 为什么重要 |
| --- | --- | --- |
| 操作系统家族 | Windows、Linux、macOS、国产 Linux 发行版 | 决定程序格式、权限模型、服务管理方式 |
| 发行版和版本 | Ubuntu、Debian、统信 UOS、银河麒麟、openEuler 等 | 决定包管理器、系统库版本、桌面环境 |
| 处理器架构 | x86\_64、ARM64、LoongArch 等 | 决定软件包能不能直接运行 |
| 内核版本 | Linux kernel、Windows NT 内核版本 | 影响驱动、容器、文件系统、硬件支持 |
| 桌面环境 | GNOME、KDE、DDE、UKUI 等 | 影响窗口、托盘、输入法、远程桌面体验 |
| 驱动和外设 | 打印机、串口、USB、摄像头、读卡器 | 影响现场硬件是否能识别和调用 |
| 安全策略 | UAC、SELinux、AppArmor、杀毒、信任策略 | 影响安装、执行、端口监听和文件访问 |

不要只问“是不是 Linux”或“是不是国产系统”。至少要拿到系统名称、版本、CPU 架构、安装包架构、运行用户和报错日志。

## 常见操作系统家族

| 系统 | 常见用途 | 现场关注点 |
| --- | --- | --- |
| Windows | 办公电脑、桌面客户端、现场终端、部分服务器 | 远程桌面、驱动、开机自启、UAC、杀毒拦截、PowerShell 执行策略 |
| Linux | 服务器、网关、边缘设备、容器宿主机、国产桌面系统基础 | 服务管理、权限、日志、网络配置、包管理器、系统库版本 |
| macOS | 研发个人电脑、设计和测试设备 | 开发环境、签名、公证、权限、Apple Silicon / Intel 架构差异 |
| Android / 嵌入式系统 | 移动设备、屏幕终端、专用设备 | APK 架构、系统权限、厂商定制、外设接口 |

跨系统运行时，最容易出问题的是路径、权限、驱动、字体、浏览器内核、证书、系统库版本和开机自启动方式。

## Linux、GNU、内核和发行版

日常说的 “Linux” 往往混合了多个层次。

| 名称 | 说明 |
| --- | --- |
| Linux 内核 | 管硬件、进程、内存、文件系统、网络、驱动和系统调用 |
| GNU 工具链 | 提供 Shell、命令行工具、编译工具、C 库等基础用户空间 |
| 用户空间 | 系统服务、命令行工具、桌面环境、包管理器、应用程序 |
| 发行版 | 把内核、工具链、服务、桌面、软件仓库和安装器组合成可安装系统 |
| 桌面环境 | 提供窗口、菜单、设置、文件管理器，例如 GNOME、KDE、DDE、UKUI |

所以“Linux 兼容”不是一句话能说明的。一个程序可能在 Ubuntu x86\_64 上正常，在统信 UOS ARM64 上缺依赖，在银河麒麟 LoongArch 上完全不能运行。

## 发行版概念

发行版不是“换个主题的 Linux”。发行版会决定软件包格式、系统库版本、默认安全策略、桌面环境、服务管理方式和硬件支持周期。

| 发行版体系 | 常见系统 | 包管理 / 包格式 | 现场关注点 |
| --- | --- | --- | --- |
| Debian 系 | Debian、Ubuntu、统信 UOS Desktop 常见基础 | `apt`、`.deb` | 包源、依赖版本、桌面组件、国产软件仓库 |
| Red Hat 系 | RHEL、CentOS、Rocky、Anolis、部分服务器发行版 | `dnf` / `yum`、`.rpm` | 企业服务器生态、SELinux、长期支持 |
| openEuler 系 | openEuler、部分国产服务器系统基础 | `dnf`、`.rpm` | ARM64 / 鲲鹏生态、服务器场景、社区与商业发行版差异 |
| Arch 系 | Arch Linux、Manjaro | `pacman` | 滚动更新，适合研发，不适合保守生产现场 |
| 独立或深度定制 | 银河麒麟、统信 UOS、中科方德等 | 多为 `.deb` 或 `.rpm`，以厂商说明为准 | 版本、架构、厂商补丁、认证清单比“像哪个上游”更重要 |

现场判断时，不要只根据包格式推断兼容性。两个系统都支持 `.deb`，也不代表系统库、桌面组件和驱动完全一样。

### 发行版分支图

Linux 发行版之间存在上游、下游、社区版、商业版、衍生版关系。下面这张图来自 Wikimedia Commons，可用来建立“发行版会分支和演化”的直观概念：

![Linux Distribution Timeline](https://upload.wikimedia.org/wikipedia/commons/8/8c/Linux_Distribution_Timeline_Dec._2020.svg)

图中没有覆盖 2020 年之后的所有国产发行版和商业版本，但它说明了一个关键事实：发行版不是孤立存在的，很多系统会继承某个社区生态的软件包格式、工具链和用户空间习惯，再由厂商做长期维护、桌面定制、安全增强和硬件适配。

### 发行版、版本和补丁包

同一个发行版还会分版本、更新批次和补丁包。

| 信息 | 示例 | 用途 |
| --- | --- | --- |
| 产品名称 | 统信 UOS、银河麒麟、openEuler | 判断系统体系和厂商支持 |
| 大版本 | V20、V10、22.03 LTS 等 | 判断系统代际和软件仓库 |
| 架构版本 | x86\_64、ARM64、LoongArch | 判断安装包是否匹配 |
| 补丁级别 | SP、Update、Service Pack、补丁批次 | 判断库版本、浏览器版本、驱动修复 |
| 桌面 / 服务器版 | Desktop、Server、Advanced Server | 判断是否有图形界面、服务组件和默认策略 |

同名系统的“桌面版”和“服务器版”不要混用安装包和排障经验。桌面版更关注窗口、输入法、浏览器、打印和外设；服务器版更关注服务、网络、存储、容器和安全策略。

## 处理器架构

处理器架构决定程序能不能直接运行。安装包名称里的 `amd64`、`x86_64`、`aarch64`、`arm64`、`loongarch64` 通常就是架构信息。

| 架构 / 处理器 | 常见位置 | 说明 |
| --- | --- | --- |
| x86\_64 / amd64 | 普通 PC、服务器、部分国产 CPU | 当前最常见的桌面和服务器架构 |
| ARM64 / aarch64 | 手机、ARM 服务器、边缘设备、部分国产终端 | 低功耗设备、鲲鹏、飞腾等生态常见 |
| LoongArch / loongarch64 | 龙芯新生态桌面和服务器 | 需要 LoongArch 对应软件包，不能当作 x86 或 ARM 使用 |
| MIPS / mips64el | 老龙芯生态、部分嵌入式设备 | 新项目中逐渐被 LoongArch 替代 |
| RISC-V | 研发板、实验性设备、部分嵌入式场景 | 生态仍在发展，生产适配需谨慎 |

国产处理器和常见架构关系：

| 处理器 / 厂商 | 常见架构归类 | 适配关注点 |
| --- | --- | --- |
| 龙芯 | LoongArch，新旧设备可能涉及 MIPS | 安装包架构、浏览器插件、外设驱动、旧生态迁移 |
| 飞腾 | ARM64 | ARM64 包、驱动、桌面兼容性 |
| 鲲鹏 | ARM64 | 服务器软件、数据库、中间件、容器镜像架构 |
| 兆芯 | x86\_64 兼容 | 多数 x86\_64 软件更容易适配，但仍要验证驱动和性能 |
| 海光 | x86\_64 兼容 | 服务器场景常见，关注内核、虚拟化、密码模块和性能 |

下载软件包时必须同时看系统和架构。`linux-x64`、`linux-arm64`、`loongarch64` 是不同产物。

## 国产化与信创

信创通常指信息技术应用创新。它不是单个软件或单个系统，而是一套国产基础软硬件生态的替换和适配工作。

### 发展脉络

国产化发展可以粗略理解为几个阶段：

| 阶段 | 重点 | 典型工作 |
| --- | --- | --- |
| 可用替代 | 先把关键办公、业务和基础设施跑在国产系统上 | 操作系统安装、浏览器适配、驱动适配 |
| 生态补齐 | 让数据库、中间件、办公软件、外设和安全软件能协同 | 驱动、插件、字体、证书、打印、UKey |
| 规模部署 | 大量终端和服务器统一运维 | 镜像、补丁、软件仓库、远程支持、资产管理 |
| 深度适配 | 充分利用国产 CPU、国密、安全策略和厂商能力 | 多架构构建、性能调优、认证测试、长期维护 |

现场不要把信创理解成“Windows 换 Linux”。实际工作通常同时涉及操作系统、CPU、浏览器、数据库、中间件、外设、证书、安全软件和运维流程。

### 信创组件

| 类别 | 示例 | 常见关注点 |
| --- | --- | --- |
| 操作系统 | 统信 UOS、银河麒麟、中标麒麟、中科方德、openEuler 衍生系统 | 版本、架构、包管理、桌面环境、系统库 |
| 处理器 | 龙芯、飞腾、鲲鹏、兆芯、海光 | 指令集、软件包架构、驱动支持、性能 |
| 浏览器 | 系统自带浏览器、360 安全浏览器、奇安信可信浏览器等 | Chromium 内核版本、证书、插件、兼容模式 |
| 数据库 | 达梦、人大金仓、OceanBase、openGauss 等 | SQL 兼容、驱动、字符集、连接池、事务行为 |
| 中间件 | 东方通、金蝶 Apusic、宝兰德等 | Java 版本、部署包格式、连接池、日志路径 |
| 办公与外设 | WPS、OFD、打印机、扫描仪、UKey | 字体、插件、驱动、浏览器调用、本地权限 |

### 常见国产操作系统

| 系统 | 常见定位 | 分支 / 生态口径 | 版本差异关注点 |
| --- | --- | --- | --- |
| 统信 UOS 桌面版 | 国产桌面系统，政企办公和终端场景常见 | 与 deepin / Debian 生态关系密切，常见 `.deb` 和 `apt` 体验 | 家庭/专业/企业等版本定位不同，桌面组件、软件商店、浏览器和外设适配不同 |
| 统信 UOS 服务器版 | 国产服务器系统 | 版本和架构较多，部分服务器产品线会面向 openEuler 等服务器生态适配 | 包源、内核、容器、服务组件、CPU 架构和厂商认证要按具体版本确认 |
| 银河麒麟桌面操作系统 | 桌面、政企信创终端常见 | 国产桌面发行版，常见 `.deb` 生态和 UKUI 桌面 | 桌面组件、浏览器、输入法、外设驱动和补丁批次差异明显 |
| 银河麒麟高级服务器操作系统 | 政企服务器和信创服务器常见 | 服务器产品线与 openEuler 等服务器生态关系密切，常见 `.rpm` / `dnf` 体验 | 服务组件、安全策略、内核、容器、数据库和中间件认证要按具体版本确认 |
| 中标麒麟 | 较早期国产 Linux 生态中常见，存量项目较多 | 历史版本多，曾长期面向 Red Hat / CentOS 服务器生态做兼容适配 | 版本年代差异大，需确认内核、包源、补丁、硬件支持和是否仍可维护 |
| 中科方德 | 党政、行业终端和服务器场景 | 厂商深度定制发行版，桌面/服务器产品线和包格式需按具体版本确认 | 外设、浏览器插件、CPU 架构、驱动和厂商认证清单很关键 |
| openEuler | 开源服务器操作系统社区，常作为商业发行版基础 | 独立开源社区，服务器生态，常见 `.rpm` / `dnf` | LTS 版本、创新版本、厂商衍生版之间软件包和支持策略不同 |
| openKylin | 开源桌面操作系统社区 | 桌面社区发行版，面向国产桌面生态 | 更偏社区和桌面生态，生产项目要看具体商业支持和硬件认证 |
| Anolis OS | 龙蜥社区服务器发行版 | Red Hat / CentOS 迁移场景常见，`.rpm` / `dnf` | 关注 ABI、包源、服务兼容和迁移成本 |

这里的“版本差异”不要只看名字。交付时更重要的是：具体镜像、CPU 架构、补丁级别、厂商认证清单、浏览器版本、数据库驱动版本和外设驱动版本。

### 国产服务器版本和上游口径

服务器版要按具体大版本拆开看。桌面版通常关心窗口、输入法、浏览器和外设；服务器版更关心内核、包管理器、系统库、容器、数据库、中间件、安全策略和长期补丁。

下表里的“上游 / 基线 / 兼容生态”是现场适配口径：能帮助判断该准备 `.deb` 还是 `.rpm`、该按 Debian 习惯还是 openEuler / Red Hat 习惯排障。商业发行版通常还会加入厂商补丁、硬件适配和认证能力，不等同于简单换皮。

| 服务器系统版本 | 上游 / 基线 / 兼容生态 | 常见包管理口径 | 现场适配重点 |
| --- | --- | --- | --- |
| 银河麒麟高级服务器操作系统 V10 [🔗](https://www.kylinos.cn/productPc/server/serverMain/) | Linux Kernel 4.19 基线；融合 openEuler LTS / SP 特性 [🔗](https://www.openeuler.org/zh/) | `.rpm`、`dnf` / `yum` 口径 | 存量信创服务器常见；重点看 CPU 架构、补丁批次、数据库/中间件认证 |
| 银河麒麟高级服务器操作系统 V11 [🔗](https://www.kylinos.cn/productPc/server/serverMainV11/) | Linux Kernel 6.6 基线 [🔗](https://www.kernel.org/)；面向新一代国产算力和 openEuler 服务器生态 [🔗](https://www.openeuler.org/zh/) | `.rpm`、`dnf` 口径 | 新项目优先关注；重点看 2503 等小版本、内核能力、容器、国密和多架构镜像 |
| 统信 UOS 服务器操作系统 V20 欧拉版 [🔗](https://www.chinauos.com/) | openEuler 生态口径 [🔗](https://www.openeuler.org/zh/) | `.rpm`、`dnf` 口径 | 关注欧拉版和非欧拉版差异，不能只写“UOS V20” |
| 统信 UOS 服务器操作系统 V20 企业版 [🔗](https://www.chinauos.com/) | 统信服务器产品线；具体上游和包格式按安装镜像确认 | 以现场镜像为准 | 重点确认 `os-release`、包管理器、CPU 架构、厂商源和补丁批次 |
| 中科方德高可信服务器操作系统 V4.0-G320 [🔗](https://www.nfschina.com/) | Linux 内核基础；强调 Red Hat / CentOS 生态兼容口径 [🔗](https://www.centos.org/) | `.rpm`、`yum` / `dnf` 口径 | 存量行业服务器常见；重点看驱动、包源、硬件认证和是否仍有维护支持 |
| openEuler LTS [🔗](https://www.openeuler.org/zh/) | openEuler 社区发行版 | `.rpm`、`dnf` 口径 | 很多国产服务器商业版的生态参考；重点看 LTS / SP / 创新版差异 |
| Anolis OS 8 [🔗](https://openanolis.cn/anolisos) | Anolis / CentOS 迁移兼容口径 [🔗](https://www.centos.org/) | `.rpm`、`dnf` 口径 | CentOS 迁移项目常见；重点看 RHEL/CentOS 兼容、ABI 和软件仓库 |
| Anolis OS 23 [🔗](https://openanolis.cn/anolisos) | 龙蜥社区新分支 | `.rpm`、`dnf` 口径 | 不是简单 CentOS 替代；重点看新版本生态、内核、软件仓库和兼容性 |

如果现场必须精确判断“基于哪个上游”，不要只看产品名称。优先采集这些信息：

```bash
cat /etc/os-release
uname -r
uname -m
rpm -q filesystem
rpm -q glibc
dnf repolist
```

这些输出比“麒麟 V10”四个字更可靠。比如同样是麒麟 V10，不同 CPU 架构、不同 SP、不同补丁批次和不同厂商镜像，依赖库和驱动状态都可能不同。

### 国产 OS、处理器和分支口径

国产化项目里，经常需要同时回答三个问题：这个 OS 属于哪个生态分支、它跑在哪类 CPU 上、我们要准备哪种安装包。

| OS / 产品线 | 常见分支 / 生态口径 | 常见 CPU 架构 | 包和适配关注点 |
| --- | --- | --- | --- |
| 统信 UOS 桌面 | deepin / Debian 生态口径 | x86\_64、ARM64、LoongArch 等，以厂商镜像为准 | `.deb`、`apt`、桌面组件、浏览器、打印和外设 |
| 统信 UOS 服务器 | 服务器发行版生态，部分版本面向 openEuler 等生态适配 | x86\_64、ARM64、LoongArch 等，以版本清单为准 | 服务器包源、容器、systemd、数据库和中间件认证 |
| 银河麒麟桌面 | 国产桌面发行版，常见 UKUI 桌面和 `.deb` 生态 | x86\_64、ARM64、LoongArch 等，以厂商镜像为准 | 桌面体验、浏览器、输入法、外设、应用商店 |
| 银河麒麟高级服务器 | 服务器发行版生态，部分版本与 openEuler 生态关系密切 | x86\_64、ARM64、LoongArch 等，以版本清单为准 | `.rpm` / `dnf` 场景、内核、安全策略、容器和服务组件 |
| 中科方德桌面 | 厂商定制桌面发行版 | x86\_64、ARM64、LoongArch 等，以厂商适配清单为准 | 桌面环境、浏览器插件、打印扫描、UKey |
| 中科方德服务器 | 厂商定制服务器发行版 | x86\_64、ARM64、LoongArch 等，以厂商适配清单为准 | 包源、服务管理、安全策略、数据库和中间件 |
| openEuler | openEuler 社区 | x86\_64、ARM64、LoongArch、RISC-V 等随社区版本扩展 | `.rpm`、`dnf`、服务器软件、容器镜像架构 |
| openKylin | openKylin 社区 | x86\_64、ARM64、RISC-V、LoongArch 等随社区版本扩展 | 桌面生态、应用兼容、社区版和商业版边界 |
| Anolis OS | Anolis / Red Hat 兼容生态口径 | x86\_64、ARM64 等 | `.rpm`、`dnf`、CentOS/RHEL 迁移兼容 |

这张表是“适配口径”，不是严格源代码血缘表。国产商业发行版通常会吸收上游社区、厂商补丁、硬件适配和认证体系；实际交付以厂商版本说明、适配清单和现场镜像为准。

### 信创版本差异

同一个信创项目里，经常同时存在多种版本差异：

| 差异类型 | 例子 | 风险 |
| --- | --- | --- |
| 操作系统版本不同 | UOS V20、麒麟 V10、openEuler LTS | 系统库、包源、桌面组件不同 |
| CPU 架构不同 | x86\_64、ARM64、LoongArch | 二进制、容器镜像、浏览器插件不能混用 |
| 桌面版 / 服务器版不同 | Desktop vs Server | 是否有图形界面、默认服务、安全策略不同 |
| 厂商补丁不同 | 同一大版本不同补丁批次 | 驱动、浏览器、证书、系统库行为不同 |
| 浏览器内核不同 | Chromium 版本差异、兼容模式 | 前端 CSS/JS、证书、WebSocket、插件表现不同 |
| 数据库兼容层不同 | MySQL 模式、Oracle 模式、PostgreSQL 兼容 | SQL 方言、分页、大小写、事务行为不同 |

因此，信创适配报告里要写完整环境，不要只写“已适配国产系统”。

推荐记录格式：

```text
操作系统：银河麒麟桌面操作系统 V10 SPx
CPU 架构：ARM64 / 飞腾
内核版本：uname -r 输出
浏览器：系统自带浏览器，Chromium xx
数据库：达梦 DM8，驱动版本 xx
安装包：product-linux-arm64-v1.2.3.deb
外设：某型号打印机，驱动版本 xx
```

## BIOS、UEFI 和启动链路

系统启动需要固件，虚拟机和物理机都一样。

| 类型 | 说明 | 常见场景 |
| --- | --- | --- |
| BIOS / Legacy | 旧式启动方式，通常配合 MBR 分区 | 老系统、旧设备兼容 |
| UEFI | 现代启动方式，通常配合 GPT 分区 | 新系统、新硬件、Secure Boot |
| Secure Boot | 启动时校验引导程序和内核签名 | 安全要求高的终端、部分信创环境 |

现代操作系统优先用 UEFI。调试旧系统、旧镜像或特殊设备启动时，可能需要切到 BIOS / Legacy。Secure Boot 打开时，未签名驱动或自定义内核模块可能加载失败。

## 驱动、外设和桌面环境

操作系统负责管理硬件和程序权限。现场问题经常发生在业务软件和硬件之间。

| 问题 | 常见原因 | 排查方向 |
| --- | --- | --- |
| USB 设备识别不到 | 驱动缺失、权限不足、设备被虚拟机/宿主机占用 | 看系统设备列表、驱动、用户权限 |
| 串口打不开 | 端口号变化、权限不足、被其他程序占用 | 看 `/dev/ttyUSB*` 或 Windows 设备管理器 |
| 打印失败 | 打印服务异常、驱动不匹配、权限不足 | 看 CUPS / Windows 打印队列和驱动 |
| 摄像头打不开 | 驱动、权限、浏览器授权、设备占用 | 看系统权限、浏览器权限、占用进程 |
| 扫描仪 / UKey 调用失败 | 厂商驱动、浏览器插件、本地服务异常 | 看驱动版本、插件、服务状态 |
| 服务开机没启动 | 没配置自启动、依赖服务未就绪、启动用户不对 | 看 systemd / 任务计划程序 / 启动日志 |
| 程序能手动运行但服务运行失败 | 工作目录、环境变量、权限不同 | 对比手动用户和服务用户环境 |

桌面环境也会影响应用体验。DDE、UKUI、GNOME、KDE 在托盘、输入法、窗口管理、远程桌面和高 DPI 上可能表现不同。

## 系统信息采集

### Linux / 国产 Linux

```bash
uname -a
uname -m
cat /etc/os-release
lsb_release -a
systemctl status 服务名
journalctl -u 服务名 -n 200
```

常见判断：

| 命令 | 看什么 |
| --- | --- |
| `uname -m` | CPU 架构，例如 `x86_64`、`aarch64`、`loongarch64` |
| `cat /etc/os-release` | 发行版名称、版本和 ID |
| `uname -r` | 内核版本 |
| `systemctl status` | 服务状态、运行用户、失败原因 |
| `journalctl` | 服务启动日志和系统错误 |

### Windows

```powershell
systeminfo
Get-ComputerInfo
$env:PROCESSOR_ARCHITECTURE
Get-Service
Get-EventLog -LogName System -Newest 50
```

常见判断：

| 信息 | 看什么 |
| --- | --- |
| Windows 版本 | 家庭版、专业版、企业版、Server 版本 |
| 架构 | x64、ARM64 |
| 权限 | 是否管理员、UAC 是否拦截 |
| 事件日志 | 服务启动失败、驱动失败、权限错误 |

## 常见故障

| 现象 | 先看什么 | 常见原因 |
| --- | --- | --- |
| 安装包无法安装 | 包格式、架构、发行版版本 | `.deb` / `.rpm` 不匹配、架构不对、依赖缺失 |
| 程序提示格式错误 | `uname -m` 和安装包名称 | x86\_64 包跑在 ARM64 / LoongArch 上 |
| 缺少动态库 | 系统库版本、包源、依赖包 | 发行版版本太旧、缺运行库、厂商仓库不全 |
| 浏览器页面异常 | 浏览器内核、证书、缓存、兼容模式 | 信创浏览器 Chromium 版本不同或插件缺失 |
| 打印 / 扫描失败 | 驱动、服务、权限 | 厂商驱动未适配当前架构或系统版本 |
| Docker 镜像启动失败 | 镜像架构、宿主内核、权限 | 只拉了 amd64 镜像，宿主是 ARM64 |
| 服务开机不启动 | 服务管理器、依赖、启动用户 | systemd 配置不完整或权限不足 |
| 同一系统有的机器正常有的不正常 | 补丁级别、架构、驱动、浏览器版本 | 镜像批次不同或后续补丁不同 |

## 参考资料

| 资料 | 适合看什么 |
| --- | --- |
| Linux Kernel, [What is the Linux kernel?](https://www.kernel.org/) | Linux 内核定位和官方入口 |
| GNU, [The GNU Operating System](https://www.gnu.org/gnu/gnu-history.html) | GNU 和自由软件操作系统历史 |
| Debian, [About Debian](https://www.debian.org/intro/about) | Debian 发行版概念 |
| Ubuntu, [Ubuntu documentation](https://help.ubuntu.com/) | Ubuntu 使用和系统管理 |
| openEuler, [openEuler documentation](https://docs.openeuler.org/) | openEuler 版本、服务器生态和文档 |
| Anolis OS, [龙蜥操作系统](https://openanolis.cn/anolisos) | Anolis OS 版本和 CentOS 迁移场景 |
| openKylin, [openKylin documentation](https://docs.openkylin.top/) | openKylin 桌面社区文档 |
| 统信软件, [统信 UOS](https://www.chinauos.com/) | 统信 UOS 产品和生态信息 |
| 麒麟软件, [银河麒麟](https://www.kylinos.cn/) | 麒麟操作系统产品和生态信息 |
| 中科方德, [方德操作系统](https://www.nfschina.com/) | 中科方德产品和生态信息 |
| Microsoft Learn, [Windows client documentation](https://learn.microsoft.com/en-us/windows/) | Windows 版本、管理和兼容性文档 |

---

---
url: /wiki/concepts-basics/networking-protocols.md
---

# 网络和常见协议

网络和常见协议关注“设备之间能不能互相访问、访问的是哪个服务、数据走什么协议”。

## IP 地址

每台联网设备的唯一编号，类似于门牌号。

| 类型 | 范围 | 说明 |
| --- | --- | --- |
| 内网 IP | `192.168.x.x` / `10.x.x.x` / `172.16-31.x.x` | 仅局域网内可访问，外部不可达 |
| 公网 IP | 其他 | 全球唯一，外部可直接访问 |
| `127.0.0.1` | 本机 | 只能本机访问自己（localhost） |
| `0.0.0.0` | 所有网卡 | 监听所有网络接口 |

> **核心问题**：现场设备通常只有内网 IP，外部无法直接访问，需要端口转发或 VPN 穿透。

```plantuml
@startuml
cloud "公网" as internet
rectangle "公司网络" as corp {
  [办公电脑] as pc
  cloud "VPN 服务" as vpn
}
rectangle "现场网络" as site {
  [密集架控制器] as ctrl
  [飞度网关] as gw
}
internet --> vpn
vpn --> pc
pc ..> ctrl : VPN 穿透
gw --> ctrl : 内网直连
@enduml
```

## 端口

一个 IP 上区分不同服务的编号，类似门牌号里的房间号。

| 常见端口 | 服务 |
| --- | --- |
| 22 | SSH |
| 23 | Telnet（不加密，不要用） |
| 53 | DNS |
| 80 | HTTP |
| 443 | HTTPS |
| 3389 | RDP（Windows 远程桌面） |
| 5900-5901 | VNC |
| 8080 | 常用 Web 服务端口 |

如果 IP 能 ping 通但服务访问不了，通常要继续看端口是否监听、防火墙是否放行、服务是否绑定在正确网卡上。

## NAT、端口转发和内网穿透

NAT（Network Address Translation）让多台内网设备共享一个公网 IP 上网。

```mermaid
flowchart LR
  A[内网设备\n192.168.1.100] --> B[路由器/网关\nNAT 转换] --> C[公网\n1.2.3.4]
  D[外部访问] --> C
  C -.->|被 NAT 丢弃| D
```

NAT 只管出去的连接，外面主动进来的连接会被丢弃。要从外部访问内网设备，常见方式如下。

| 方案 | 原理 | 特点 |
| --- | --- | --- |
| 端口转发 | 路由器/防火墙映射端口 | 需要路由器管理权限 |
| frpc / GOST | 客户端连公网服务端，服务端转发 | 需要公网服务器 |
| ZeroTier / WireGuard | 虚拟组网，设备在同一虚拟局域网 | 长期稳定，多设备互通 |
| RustDesk / 向日葵 | 厂商中继服务器转发 | 开箱即用，无需公网 IP |

## 端口转发 vs VPN

| | 端口转发 | VPN / 组网 |
| --- | --- | --- |
| 原理 | 映射一个端口到外部 | 建立虚拟局域网 |
| 访问范围 | 只能访问映射的那一个端口 | 可以访问设备所有端口 |
| 配置 | 每次换端口都要重新配 | 一次配好，所有端口都能访问 |
| 适合 | 临时访问单个服务 | 长期维护多台设备 |

## SSH、RDP 和 VNC

这些都是远程访问协议，但用途不同。

| 协议 | 默认端口 | 传输内容 | 适合 |
| --- | --- | --- | --- |
| SSH | 22 | 命令行输入输出 | Linux 服务器、网关、嵌入式设备 |
| RDP | 3389 | Windows 桌面画面和输入 | Windows 远程桌面 |
| VNC | 5900-5901 | 屏幕帧缓冲和输入 | 跨平台桌面远控 |

```mermaid
sequenceDiagram
  participant C as 客户端
  participant S as 服务端 (SSH)
  C->>S: TCP 连接请求 (IP:22)
  S->>C: 发送公钥指纹
  C->>S: 确认指纹 + 发送加密请求
  S->>C: 验证密码/密钥
  C->>S: 加密通道建立
  Note over C,S: 所有命令和输出都加密传输
```

前提：客户端能访问到服务端的 IP 和端口。如果服务端在内网，需要先解决网络可达性。

## 远程终端 vs 远程桌面

| | 远程终端 | 远程桌面 |
| --- | --- | --- |
| 传输内容 | 文字命令和输出 | 整个屏幕画面 |
| 网络带宽 | 极低（几 KB/s） | 较高（几百 KB 到几 MB/s） |
| 适合 | 服务器管理、命令行操作 | GUI 操作、排障桌面软件 |
| 代表方案 | SSH / ttyd | RDP / VNC / 向日葵 / RustDesk |

## HTTP、HTTPS、DNS 和防火墙

| 概念 | 说明 | 常见问题 |
| --- | --- | --- |
| HTTP | Web 明文协议，默认 80 端口 | 被代理、跨域、接口路径错误 |
| HTTPS | HTTP + TLS 加密，默认 443 端口 | 证书过期、证书不受信任、域名不匹配 |
| DNS | 把域名解析成 IP | 解析到旧地址、内外网解析不同 |
| 网关 | 网络出口设备 | 网关错了会导致跨网段不可达 |
| 防火墙 | 控制端口是否允许访问 | 服务正常但端口被拦截 |

访问一个 Web 服务时，可以按顺序判断：域名能否解析、IP 是否可达、端口是否开放、协议是否正确、接口是否返回预期内容。

---

---
url: /wiki/product-lines.md
---

# 产品线

产品线目录用于按产品组织研发资料。先从产品视角理解业务能力，再进入系统架构、开发流程、部署交付和调试运维。

## 当前产品线

## 阅读顺序

| 顺序 | 内容 | 说明 |
| --- | --- | --- |
| 1 | 产品视图 | 先看系统提供哪些能力 |
| 2 | 系统架构 | 再看模块边界、服务职责和数据流 |
| 3 | 开发流程 | 查版本线、代表仓库和项目演进 |
| 4 | 打包分发 / 备份迁移 | 查部署、发布、升级、迁移和现场验证 |

## 补充原则

* 新产品线先建总览页，再补产品视图和系统架构。
* 客户定制内容不要直接混进主线能力，先标明项目范围。
* 代码仓库、部署方式、协议文件要链接到稳定位置，避免散落在多篇文档里。

---

---
url: /wiki/sdv.md
---

# 智档宝

智档宝是围绕档案业务、库房设备、环境控制、RFID、数字化和现场交付形成的一条产品线。它不是单个 Web 项目，而是一组前端、后端、本地服务、设备程序、固件和定制项目共同组成的系统。

![智档宝产品线总览](/illustrations/smart-doc-vault-index.png)

## 总览草稿

下面这张是讲解“三合一系统”时使用的 Excalidraw 草稿，用于辅助理解产品能力和现场系统之间的大致关系，不作为最终架构定稿。

## 文档定位

这个目录用于沉淀智档宝研发侧的稳定知识，包括产品能力、系统架构、代码仓库、设备接入、部署交付、调试运维和项目定制。

这里的文档按“先理解产品，再理解系统，再处理开发和交付”的顺序维护。产品线总览只放稳定入口，不承载临时项目记录。

## 阅读路径

| 读者 | 先看 | 目的 |
| --- | --- | --- |
| 新人研发 | [1-产品视图](/wiki/sdv/product-view) | 先理解智档宝覆盖哪些业务能力 |
| 前端 / 后端 | [2-系统架构](/wiki/sdv/system-architecture) | 确认模块边界、服务职责和协作关系 |
| 产品 / 测试 | [1-产品视图](/wiki/sdv/product-view) | 按能力查找业务流程和功能范围 |
| 实施 / 运维 | [4-打包分发](/wiki/sdv/packaging-distribution)、[5-备份迁移](/wiki/sdv/backup-migration) | 查部署、升级、迁移、回滚和现场验证方式 |
| 项目负责人 | [3-开发流程](/wiki/sdv/development-workflow) | 区分主线、能力线、定制线和历史版本 |

## 主线文档入口

| 章节 | 解决的问题 | 适合什么时候看 |
| --- | --- | --- |
| [1-产品视图](/wiki/sdv/product-view) | 智档宝有哪些业务能力，档案、数字化、环境控制、RFID 分别覆盖什么 | 新人进入产品线、产品/测试确认功能边界 |
| [2-系统架构](/wiki/sdv/system-architecture) | 前端、后端、中间件、本地服务、设备接入和硬件之间怎么协作 | 开发排查问题、设计新能力、判断故障位置 |
| [3-开发流程](/wiki/sdv/development-workflow) | 版本线、分支关系、代表仓库、版本 hash 和开发演进 | 找仓库、查版本来源、判断定制线关系 |
| [4-打包分发](/wiki/sdv/packaging-distribution) | Linux / Windows 离线包怎么构建、命名、发布和验证 | 发版、交付、现场安装、确认包来源 |
| [5-备份迁移](/wiki/sdv/backup-migration) | 旧现场怎么备份、换机、迁移、验证和回滚 | 升级前、重装前、换机前、跨系统迁移前 |

## 按场景阅读

| 场景 | 建议顺序 |
| --- | --- |
| 新人熟悉智档宝 | [1-产品视图](/wiki/sdv/product-view) -> [2-系统架构](/wiki/sdv/system-architecture) -> [3-开发流程](/wiki/sdv/development-workflow) |
| 开发定位线上问题 | [2-系统架构](/wiki/sdv/system-architecture) -> [3-开发流程](/wiki/sdv/development-workflow) -> 具体功能页 |
| 准备正式发版 | [3-开发流程](/wiki/sdv/development-workflow) -> [4-打包分发](/wiki/sdv/packaging-distribution) |
| 现场部署或升级 | [4-打包分发](/wiki/sdv/packaging-distribution) -> [5-备份迁移](/wiki/sdv/backup-migration) |
| 换机、重装、跨系统迁移 | [5-备份迁移](/wiki/sdv/backup-migration) -> [4-打包分发](/wiki/sdv/packaging-distribution) -> [2-系统架构](/wiki/sdv/system-architecture) |

## 目录结构

```text
智档宝
├─ 1-产品视图
├─ 2-系统架构
├─ 3-开发流程
├─ 4-打包分发
└─ 5-备份迁移
```

## 维护原则

* 主线能力写在产品线目录，客户差异写到项目定制目录。
* 仓库地址和版本关系优先维护在 [3-开发流程](/wiki/sdv/development-workflow)，不在每篇文章重复堆列表。
* 项目定制分组要标注来源主线、能力线和差异点，避免多年后无法判断 fork 关系。
* 架构文档只写稳定边界和关键流向，临时方案写到调试或项目记录。
* 打包、发布、备份、迁移和回滚必须写清楚来源包、版本 hash、数据对象和验证动作。
* ShowDoc 导入内容作为历史资料逐步迁移，不直接替代现行研发文档。

---

---
url: /wiki/sdv/product-view.md
---

# 1-产品视图

产品视图用于从业务能力角度理解智档宝。它回答“系统给用户提供什么能力”，不直接按代码仓库、服务进程或部署组件组织。

![智档宝产品能力地图](/illustrations/smart-doc-vault-product-view.png)

## 阅读目标

* 知道智档宝目前主要由哪些产品能力组成。
* 区分主线能力、正在开发能力和项目定制能力。
* 给产品、实施、研发、测试提供统一的功能地图。

## 产品主线

从产品视角看，智档宝目前主要分为四大块。

| 主块 | 当前定位 | 状态 |
| --- | --- | --- |
| 档案管理 | 智档宝的基础业务主线，围绕档案、库房、架体、借阅、盘点、权限展开 | 主线能力 |
| 环境控制 | 围绕库房环境、传感器、网关、空调、除湿、漏水、报警、监控等现场环境能力展开 | 现场设备能力 |
| 数字化 | 围绕电子档案、文件上传、文件解析、预览、搜索和断点续传展开 | 主线能力 / 持续增强 |
| RFID | 围绕 RFID 标签、门口机、手持机、盘点车、RFID 打印机和实物识别流程展开 | 截至目前仍在开发中 |

## 档案管理

档案管理是智档宝最核心的业务能力。它解决“档案在哪里、是什么状态、谁能操作、如何流转”的问题。

### 能力范围

| 能力 | 产品说明 |
| --- | --- |
| 档案建档 | 建立档案基础信息，形成可检索、可流转的业务对象 |
| 档案查询 | 按档号、题名、分类、库房、状态等条件查询档案 |
| 档案借阅 | 支持借阅申请、借出、归还、状态变更和记录追踪 |
| 档案入库 / 出库 | 将档案和库房位置、架体位置、库区信息关联起来 |
| 档案盘点 | 对档案实物、系统记录和设备识别结果进行核对 |
| 档案状态流转 | 维护在库、借出、归还、待上架、异常等状态 |
| 档案架具 | 管理库区、架体、列、节、层、位等空间结构 |
| 密集架 / 回转柜 | 维护实体档案装具、库位映射、上架下架和现场联动 |
| 权限控制 | 控制用户能访问哪些库房、档案和功能 |

### 产品边界

* 档案管理关注业务流程和状态一致性。
* 具体设备如何移动、识别、开架、扫码，放到环境控制、RFID 或设备文档里说明。
* 数字化文件、全文检索、文件预览属于数字化能力，但会和档案对象关联。

### 后续建议拆页

```text
档案管理
├─ 档案建档
├─ 档案查询
├─ 借阅 / 归还
├─ 入库 / 出库
├─ 档案盘点
├─ 档案状态
├─ 档案架具
├─ 密集架 / 回转柜
└─ 权限控制
```

## 环境控制

环境控制是智档宝面向库房环境和现场安全的能力板块。它关注环境数据采集、设备控制、异常告警和现场联动。

| 能力 | 产品说明 |
| --- | --- |
| 温湿度监测 | 采集库房温湿度，展示实时状态和历史趋势 |
| 空气质量 | 对空气质量、颗粒物等环境数据进行接入和展示 |
| 空调 / 除湿 / 加湿 | 控制或联动库房环境设备 |
| 漏水 / 报警 | 识别漏水、异常状态和告警事件 |
| 网关接入 | 通过网关统一接入现场设备 |
| 摄像头 / 门禁 | 对接监控、门禁等现场安全设备 |

### 产品边界

* 环境控制关注库房环境和安全状态，不负责档案业务状态本身。
* 环境控制设备可以影响档案管理和大屏展示，但业务规则仍由主系统承载。
* 具体协议、网关型号、MQTT、Modbus、HTTP、串口等技术细节放到系统架构或设备文档。

### 后续建议拆页

```text
环境控制
├─ 环境控制总览
├─ 温湿度 / 空气质量
├─ 空调 / 除湿 / 加湿
├─ 漏水 / 报警
├─ 网关接入
├─ 摄像头 / 监控
└─ 门禁接入
```

## 数字化

数字化用于把纸质档案、附件和多媒体材料转成可上传、可预览、可解析、可搜索的电子档案。

### 能力范围

| 能力 | 产品说明 |
| --- | --- |
| 文件上传 | 上传档案附件、扫描件、图片、音视频、办公文档等文件 |
| 断点续传 | 大文件或不稳定网络下继续上传，避免重复传输 |
| 文件预览 | 对图片、PDF、Office、音视频等常见格式进行在线预览 |
| 文件解析 | 提取文档内容，为检索和后续处理提供基础 |
| 全文搜索 | 对电子档案内容进行检索，支持按关键字定位资料 |
| 电子档案 | 将文件、元数据、档案对象绑定，形成电子档案能力 |
| 文件存储 | 对接对象存储或本地文件服务，管理文件落盘和访问 |

### 文件类型

数字化能力需要覆盖常见档案材料：

```text
图片：jpg、png、bmp
文档：txt、doc、docx、xls、xlsx、ppt、pptx、pdf
音频：mp3、wav、flac
视频：mp4、flv、m3u8、avi、mkv
压缩包和其他附件：按项目需求扩展
```

### 产品边界

* 数字化关注文件从上传到可用的完整链路。
* 文件存储、解析服务、搜索服务属于系统架构层，但产品视图需要明确它们承载的用户能力。
* 如果某个项目只需要上传和预览，不需要全文检索，应在项目定制中单独说明。

### 后续建议拆页

```text
数字化
├─ 文件上传
├─ 断点续传
├─ 文件预览
├─ 文件解析
├─ 全文搜索
├─ 电子档案
└─ 文件类型支持
```

## RFID

RFID 是智档宝面向实物档案识别和现场操作的能力板块。截至目前仍在开发中，文档需要明确已完成能力、正在开发能力和项目定制差异。

| 能力 | 产品说明 |
| --- | --- |
| RFID 标签 | 将档案实物与 RFID 标签绑定 |
| 门口机 | 支持出入库识别、通行识别或现场操作入口 |
| 手持机 | 支持移动盘点、查找、扫码、现场操作 |
| 盘点车 | 面向批量盘点和现场巡检 |
| RFID 打印机 | 支持标签打印和档案标识制作 |
| RFID 服务 | 负责读写器、标签、设备事件和主系统之间的衔接 |

### 产品边界

* RFID 关注实物档案识别、盘点和现场操作。
* RFID 会和档案管理产生业务联动，例如绑定标签、盘点、出入库识别。
* RFID 相关设备包含门口机、手持机、盘点车、RFID 打印机等。
* 读写器、设备服务、标签协议、打印协议等技术实现放到系统架构或设备文档。
* 截至目前仍在开发中的能力，需要在具体页面标记状态，不要和已稳定能力混写。

### 后续建议拆页

```text
RFID
├─ RFID 总览
├─ RFID 标签
├─ 门口机
├─ 手持机
├─ 盘点车
└─ RFID 打印机
```

## 其他

| 能力 | 说明 | 关联模块 |
| --- | --- | --- |
| 授权管理 | 系统授权、离线授权、授权审批和授权校验 | 授权服务、部署交付 |
| 大屏展示 | 新大屏、定制大屏、库房状态展示 | 大屏前端、后端接口、数据可视化 |
| 密集架 / 回转柜 | 归入档案管理中的档案架具和库位能力，其他页只保留入口 | 档案管理、系统架构、设备接入 |
| 打印服务 | 普通打印、标签打印、模板打印 | 打印服务、本地服务、RFID 打印机 |
| 人脸识别 | 身份识别、门禁或现场操作辅助 | 人脸服务、门口机、项目定制 |
| 服务监控 | Windows 服务、本地服务、现场程序状态监控 | 本地服务、运维工具 |
| 项目定制 | 面向客户项目的差异功能和交付形态 | 项目分支、定制仓库、交付文档 |

## 推荐拆页方式

产品能力页不要直接写代码实现。每个页面先描述业务对象、流程和边界，再链接到系统架构、代码仓库和调试文档。

## 当前目录

```text
1-产品视图
├─ 档案管理
├─ 环境控制
├─ 数字化
├─ RFID
└─ 其他
```

## 单篇文档模板

每个产品能力建议按同一模板维护。

```text
业务目标
核心对象
主要流程
状态流转
前端入口
后端模块
关联设备
配置项
常见问题
关联仓库
```

## 维护原则

* 产品视图只描述“用户能做什么”和“业务怎么流转”。
* 技术实现细节放到系统架构、代码仓库或调试文档。
* 项目定制差异只写摘要，详细内容放到项目定制目录。
* 一个能力如果同时涉及前端、后端和设备，也仍然只在产品视图里维护一份业务说明，避免多处重复。

---

---
url: /wiki/sdv/archive-management.md
---

# 档案管理

![档案管理业务场景](/illustrations/archive-management-overview.png)

档案管理是智档宝的基础业务主线，负责把库区、档案、档案装具、借阅、盘点和权限组织成可管理、可查询、可追溯的业务体系。

## 业务定位

档案管理重点回答三个问题：

* 档案在哪里：档案归属哪个库房、库区、架体、柜体或格口。
* 档案是什么：档案有哪些著录信息、密级、保管期限、电子文件和业务扩展字段。
* 档案怎么流转：档案从建档、上架、借阅、归还、盘点异常到销毁如何变化。

## 目录总览

| 目录 | 解决的问题 | 主要内容 |
| --- | --- | --- |
| 库区 | 档案和装具实际放在哪里 | 库房、库区、层级结构、密集架、回转柜、当前接入类型 |
| 档案 | 一份档案如何建档、扩展和流转 | 档案主数据、档案分类、自定义字段、导入导出、生命周期、借阅、回转柜盘点 |
| 档案装具 | 档案盒、袋、夹等载体如何管理 | 装具类型、装具位置、装具字段、装具内档案、装具借阅和盘点 |
| 打印 | 档案业务中哪些内容需要输出纸质或标签 | 档案标签、装具标签、借阅单、移交单、盘点单、模板和字段 |
| 研发参考 | 研发如何理解产品对象和代码模块 | 产品对象、模型映射、前后端入口、关联仓库 |
| 产品边界 | 哪些内容属于档案管理，哪些不属于 | 数字化、RFID、环境控制、设备协议和系统架构边界 |

## 核心对象

| 对象 | 说明 |
| --- | --- |
| 库区 | 档案存放的业务空间，承载架体、柜体、权限、统计和盘点范围 |
| 档案 | 系统管理的核心业务对象，包含基础信息、状态、位置、扩展字段和关联文件 |
| 档案装具 | 档案盒、档案袋、档案夹、档案箱、防磁柜、光盘、磁带等承载对象 |
| 档案架具 | 密集架、固定列、回转柜等实体或逻辑存放结构 |
| 借阅记录 | 记录借阅申请、审批、借出、归还和超期情况 |
| 盘点记录 | 记录盘点任务、盘点结果、差异和处理状态 |
| 用户 / 权限 | 控制人员能访问的库房、档案范围和操作能力 |

## 前端页面结构

当前前端主线按“档案概览 / 档案维护”组织。档案概览面向日常检索、建档和对象操作；档案维护面向待办队列、异常处理和借阅流转。

| 一级入口 | 二级入口 | 主要处理对象 | 前端目录 |
| --- | --- | --- | --- |
| 档案概览 | 档案概览 | 单份档案、电子档案、档案位置、暂存、组卷、借阅、转移、删除、出库、导出 | `fit-archive-ng/src/views/ArchivesManagement/overview/File` |
| 档案概览 | 档案装具概览 | 档案盒、袋、夹、箱等装具，支持暂存、拆卷、借阅、转移、删除、出库、导出 | `fit-archive-ng/src/views/ArchivesManagement/overview/FileBox` |
| 档案维护 | 新档上架 | 待分配明确库位的档案和装具 | `fit-archive-ng/src/views/ArchivesManagement/maintain/PutOnShelves` |
| 档案维护 | 档案回收站 | 已删除但可恢复或销毁的档案和装具 | `fit-archive-ng/src/views/ArchivesManagement/maintain/RecycleBin` |
| 档案维护 | 遗失档案 | 现场确认遗失后的档案和装具，可找回或彻底遗失处理 | `fit-archive-ng/src/views/ArchivesManagement/maintain/LostFile` |
| 档案维护 | 借阅审批 | 待审批、已通过、已拒绝等借阅申请 | `fit-archive-ng/src/views/ArchivesManagement/maintain/BorrowingApproval` |
| 档案维护 | 待取档案 | 审批通过后等待现场取档的借阅对象 | `fit-archive-ng/src/views/ArchivesManagement/maintain/PendingFile` |
| 档案维护 | 在借档案 | 已借出、可归还或标记遗失的对象 | `fit-archive-ng/src/views/ArchivesManagement/maintain/BorrowingFiles` |
| 档案维护 | 超期档案 | 超过借阅期限的在借对象 | `fit-archive-ng/src/views/ArchivesManagement/maintain/OverdueFile` |
| 档案维护 | 归还上架 | 已归还但还需要重新确认位置的档案和装具 | `fit-archive-ng/src/views/ArchivesManagement/maintain/ReturnToShelf` |
| 档案维护 | 借阅用户 | 借阅人账号、审批人和借阅权限维护 | `fit-archive-ng/src/views/ArchivesManagement/maintain/FileUser` |
| 档案维护 | 已出库档案 | 已出库但可找回的档案和装具 | `fit-archive-ng/src/views/ArchivesManagement/maintain/outLibraryFile` |

页面上看到的“档案概览”和“档案装具概览”是两套对象列表，但维护页通常会同时提供档案和装具两个 Tab。写业务说明时不要把“档案”和“档案装具”合成一个对象，也不要把“分类”写成实体装具。

## 库区

库区用于描述档案实物存放的空间范围。它是库房管理、上架、查找、借阅取档、归还上架、盘点和大屏统计的共同基础。

### 层级结构

```text
库房
└─ 库区
   └─ 架体 / 柜体
      ├─ 密集架：列 / 左右侧 / 节 / 层 / 格
      └─ 回转柜：柜体 / 层 / 格口
         └─ 档案 / 档案装具
```

| 层级 | 产品含义 |
| --- | --- |
| 库房 | 档案保管的物理空间，通常也是权限、统计和大屏展示的基础范围 |
| 库区 | 库房下的业务分区，可按楼层、房间、区域或项目习惯划分 |
| 架体 / 柜体 | 密集架、固定列、回转柜等档案架具 |
| 密集架位置 | 通过列、左右侧、节、层、格定位档案或装具 |
| 回转柜位置 | 通过柜体、层、格口定位档案 |
| 档案 / 装具 | 最终落位到库区中的实体对象 |

对外或跨系统调用开架能力时，不能只提供“第几列”。密集架同一列通常有左右两面，必须提供档案所在侧，必要时再带上节、层、格。推荐位置编码可按“区域号-列号-侧编码-节-层-格”组织，例如 `A01-3-01-2-4-5`，其中 `01` 表示左侧，`02` 表示右侧。

### 密集架

密集架是库区中最常见的智能架具。产品上需要把“库位结构”和“设备联动”分开理解：档案管理负责库位、状态和业务流程，设备服务负责执行开架、闭架、移动列控制和状态回传。

| 能力 | 产品说明 |
| --- | --- |
| 固定列 / 移动列 | 维护密集架的固定列、移动列和列号关系 |
| 架体结构 | 维护区、列、左侧 / 右侧、节、层、格等空间结构 |
| 库位映射 | 将档案、档案盒或档案袋绑定到具体库位 |
| 上架 / 下架 | 将待上架档案放入指定库位，或从库位移出 |
| 开架 / 闭架联动 | 在业务操作中触发或提示现场架体动作 |
| 状态回传 | 展示架体在线、移动、异常、占用等状态 |
| 盘点联动 | 结合库位清单、设备状态或 RFID 结果完成盘点 |

| 结构 / 统计 | 说明 |
| --- | --- |
| 固定列位置 | 支持左侧、右侧、中间等固定列位置口径 |
| 列号范围 | 描述一个库区内密集架可用列号 |
| 业务列号 / 设备列号 | 用户看到的列号和硬件通信使用的列号可能不同 |
| 左右侧节层格 | 左侧和右侧可分别配置节数、层数、格数 |
| 左右侧在库数 | 按左右侧统计在库档案数量 |
| 左右侧借阅数 | 按左右侧统计借阅相关档案数量 |
| 通道距离 | 可展示当前通道距离百分比 |
| AI / 异物状态 | 可展示分析中、空闲、资源不足、平台离线、无异物、有物、有人有物等状态 |

#### 密集架接入类型

| 接入类型 | 当前实现口径 | 协议 | 对接文档 / 资料 |
| --- | --- | --- | --- |
| FD-01 | 方德密集架 | TCP Client / USB Serial | [FD-01 协议文档](/wiki/reference-docs#fd-01-密集架协议)，网盘：[固定列与计算机间通讯协议 V5](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%9B%BA%E5%AE%9A%E5%88%97%E4%B8%8E%E8%AE%A1%E7%AE%97%E6%9C%BA%E9%97%B4%E9%80%9A%E8%AE%AF%E5%8D%8F%E8%AE%AEV5%E7%89%88%E6%9C%AC%EF%BC%88%E7%AC%AC3%E6%96%B9%EF%BC%89.doc) |
| FD-02 | 北泰 / TLU6820 系列 | HTTP | 网盘：[密集架远程对接接口 V1.9](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%AF%86%E9%9B%86%E6%9E%B6%E8%BF%9C%E7%A8%8B%E5%AF%B9%E6%8E%A5%E6%8E%A5%E5%8F%A3V1.9%281%29.docx)、[密集架远程控制实例](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%AF%86%E9%9B%86%E6%9E%B6%E8%BF%9C%E7%A8%8B%E6%8E%A7%E5%88%B6%E5%AE%9E%E4%BE%8B%282%29.docx) |
| FD-03 | 天骄固定列 WebApi | HTTP | 网盘：[密集架固定列 WebApi 通信协议 v3.1.1](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%AF%86%E9%9B%86%E6%9E%B6%E5%9B%BA%E5%AE%9A%E5%88%97WebApi%E9%80%9A%E4%BF%A1%E5%8D%8F%E8%AE%AEv3.1.1.pdf) |
| FD-04 | 云档密集架 | HTTP | 网盘：[云档 Apifox 导出](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E4%BA%91%E6%A1%A3Apifox%E5%AF%BC%E5%87%BA.pdf) |
| FD-05 | 华升 / 高频密集架 | HTTP | 网盘：[高频密集架管理系统对接接口说明书 V1.4](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E9%AB%98%E9%A2%91%E5%AF%86%E9%9B%86%E6%9E%B6%E7%AE%A1%E7%90%86%E7%B3%BB%E7%BB%9F%E5%AF%B9%E6%8E%A5%E6%8E%A5%E5%8F%A3%E8%AF%B4%E6%98%8E%E4%B9%A6V1.4%281%29.docx)、[智能密集架控制系统对接接口说明书 V1.3](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E6%99%BA%E8%83%BD%E5%AF%86%E9%9B%86%E6%9E%B6%E6%8E%A7%E5%88%B6%E7%B3%BB%E7%BB%9F%E5%AF%B9%E6%8E%A5%E6%8E%A5%E5%8F%A3%E8%AF%B4%E6%98%8E%E4%B9%A6V1.3%E6%9C%80%E6%96%B0%E7%89%88.docx)、[华升密集架.rar](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%8D%8E%E5%8D%87%E5%AF%86%E9%9B%86%E6%9E%B6.rar) |
| FD-06 | 飞度密集架 | HTTP / WS | 网盘：[飞度密集架 Apifox 导出](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E9%A3%9E%E5%BA%A6%E5%AF%86%E9%9B%86%E6%9E%B6Apifox%E5%AF%BC%E5%87%BA.pdf)，以 `fit-denserack`、`smart-doc-vault` 中的 FD-06 实现和现场镜像为准 |

网盘目录：[开发 / 对接文档](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3)。

| 接入类型 | 现场识别特征 | 代码入口 |
| --- | --- | --- |
| FD-01 | 固定列协议，走串口服务器或 USB 串口；库区配置里 `accessMode` 常见为 `串口服务器` 或 `USB串口` | `smart-doc-vault/pkg/mjj/fd01_mjj.go`、`service/system/mjj.go` |
| FD-02 | HTTP 路径为 `/IntelligentCabinetAPIServer/...`，常见接口有 `OpenCol`、`ReportStatus`、`ReportInfo`，文档默认端口为 `16000` | `smart-doc-vault/pkg/mjj/fd02_mjj.go`、`service/system/mjj_fd02.go` |
| FD-03 | HTTP 路径为 `/MjjWebApi/...`，请求头 `token` 由开发识别码、用户名、密码 Base64 生成；库区配置会额外维护授权码、用户名、密码 | `smart-doc-vault/pkg/mjj/fd03_mjj.go` |
| FD-04 | HTTP 固定请求 `/MjjWebApi`，动作放在 JSON 字段 `Op`，例如 `GetConfig`、`getShelfStatus`、`OpenShelf`、`CloseShelf` | `smart-doc-vault/pkg/mjj/fd04_mjj.go` |
| FD-05 | HTTP 路径为 `/denseshelf/...`，返回字段常见 `resultcode`、`resultdata`，按 `zone` 区号操作 | `smart-doc-vault/pkg/mjj/fd05_mjj.go` |
| FD-06 | 飞度自研密集架，平台侧维护 `FD06AuthCode`，支持 WebSocket 绑定和 `/mjj/fd06proxy/...` HTTP 代理 | `smart-doc-vault/pkg/mjj/fd06_mjj.go`、`mjjs/mjj_fd06.go`、`service/system/mjj_ws.go` |

当前代码实现中，FD-03 是天骄固定列 WebApi，FD-04 是云档密集架；历史资料里如果出现相反写法，以代码实现和现场接口路径为准。

### 回转柜

回转柜也是库区中的智能架具，更适合按“档案直接落格口”理解。它和密集架一样归入库区管理，但现场动作、通信协议和控制程序通常会单独实现。

RFID 在这里可以理解为“给档案或装具一个可被无线读取的身份”。档案绑定 RFID 标签后，读写器可以在取档、归档、盘点时读取标签号，再和系统中的档案、格口、库位关系进行比对。回转柜场景下，RFID 通常不直接决定业务状态，而是作为辅助识别手段，用来确认“拿到的是不是这份档案”“归回的是不是这个格口”“盘点结果和系统记录是否一致”。

| 能力 | 产品说明 |
| --- | --- |
| 柜体管理 | 维护回转柜设备和所属库区 |
| 格口 / 库位 | 将柜体内部空间映射成可绑定档案的位置 |
| 取档 | 根据档案位置找到对应柜体和格口，辅助现场取档 |
| 归档 | 将归还档案重新绑定到柜体库位 |
| 状态同步 | 展示柜体在线、故障、占用或执行状态 |
| 项目定制 | 不同项目的柜体型号、库位规则和操作流程可能不同 |

| 统计项 | 产品说明 |
| --- | --- |
| 全部档案 | 柜内系统记录的总档案数，不论状态 |
| 在库档案 | 柜内实际可视为在库的档案，包含在库和借阅未取 |
| 在借档案 | 借阅流程中的档案，包含借阅中和在借未取 |
| 不在库档案 | 系统记录在柜内，但盘点不到或未按借阅流程出库的档案 |
| 剩余格口 | 回转柜总格口数减去已占用档案数 |

#### 回转柜档案状态

回转柜有一套特殊的档案展示状态。普通密集架主要看 `ArchiveModel.Status`，而回转柜档案会优先结合最新盘点结果 `InventoryResultModel.NewBorrowStatus` 展示状态；同时用盘点结果判断 `HzgStatus`，结果为“正常 / 盘盈”时视为在位，其他结果通常视为不在位。

| 回转柜展示状态 | 形成口径 | 产品含义 |
| --- | --- | --- |
| 待上架 | 业务状态仍是待上架 | 档案还没有完成格口确认 |
| 在库 | 档案状态、借阅关系和盘点结果一致，或归还后已盘到原格口 | 柜内可视为正常在位 |
| 未在库 | 系统认为应在库，但盘点未识别到对应 RFID | 需要人工确认是漏读、错放、取走未登记还是遗失 |
| 借阅审批 | 档案在库，存在待审批借阅申请 | 审批未完成，现场不应直接取走 |
| 借阅待取 | 审批通过，等待现场取档 | 柜内仍可能在位，表示审批通过但尚未取走 |
| 借阅 | 档案处于借阅流程，且盘点关系支持当前状态 | 业务上已进入借阅状态 |
| 借阅未取 | 档案业务状态是借阅，但回转柜盘点仍显示在位 | 常见于系统已登记借出、现场尚未取走或状态未同步 |
| 归还待上架 | 档案已归还，但盘点或位置尚未确认 | 需要完成归还上架或重新确认格口 |
| 借阅超期 | 借阅超过期限 | 借阅流程异常状态，仍需结合在位 / 不在位判断现场处理 |

这组状态不应直接套到密集架或普通档案盒上。回转柜状态更像“业务状态 + 借阅审批状态 + RFID 盘点结果”的合成展示，用来指导现场开柜、取档、归还和异常处理。

回转柜不要默认套用档案盒上架逻辑。具体 TCP 服务、控制命令和厂商差异放到系统架构或设备调试文档。

#### 回转柜接入类型

| 接入类型 | 厂商 | 协议 | 对接文档 |
| --- | --- | --- | --- |
| FD-01 | 中芯回转柜 | TCP server | 网盘：[回转柜通讯协议](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%9B%9E%E8%BD%AC%E6%9F%9C%E9%80%9A%E8%AE%AF%E5%8D%8F%E8%AE%AE%E6%94%B9%281%29.docx)、[回转柜补充](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/%E5%9B%9E%E8%BD%AC%E6%9F%9C%E8%A1%A5%E5%85%85.jpg)，调试：[网络协议调试地址](/wiki/network-protocol-debug-urls) |

调试协议侧已有旧文档记录：

| 标识 | 说明 |
| --- | --- |
| `hzg` | 回转柜，TCP server |
| `mjj` | 密集架，TCP Client / USB，其中 USB 已弃用 |
| `udp` | 设备调试，UDP |
| `mqtt` | 设备通信，MQTT |

## 档案

档案是一切业务流转的核心对象。它既包含标准著录信息，也需要承接项目差异字段，并且要在生命周期中持续变化。

### 档案主数据

| 字段方向 | 产品说明 |
| --- | --- |
| 基础信息 | 档案名称、档案编号、备注、维护人、创建时间 |
| 分类信息 | 目录位置、分类路径、年度、类别、全宗或项目定义的分类字段 |
| 保管属性 | 保密等级、有效期、保管期限、责任部门 |
| 实体位置 | 库房、库区、架体、柜体、层级位置 |
| 装具关系 | 档案可以归属到档案盒、档案袋等装具 |
| 电子档案 | 物理档案可以挂接电子档案文件 |
| RFID | 档案可绑定 RFID 标签，用于盘点和状态判断 |
| 审批关系 | 档案可关联借阅审批 |
| 回转柜盘点关系 | 档案可关联最新回转柜盘点结果，展示在位 / 不在位 |

| 类型 | 当前口径 |
| --- | --- |
| 保密等级 | 公开、内部、秘密、机密、绝密 |
| 有效期 | 永久、三年、五年、十年、十五年、二十年、二十五年、三十年 |

当前前端“新建档案”不是单一表单，而是先选择档案类型，再决定是否直接入库或进入待上架队列。

| 前端档案类型 | 代码值 | 产品含义 |
| --- | --- | --- |
| 独立成盒 | `A` | 不需要记录装具内部细分档案信息，按单份档案选择位置或进入待上架 |
| 存入现有盒 | `B` | 将档案信息存入一个已有档案装具内，不单独选择上架模式 |
| 多册组卷 | `C` | 创建新的档案装具并记录其中档案信息，后续按装具位置处理 |

| 上架模式 | 代码值 | 产品含义 |
| --- | --- | --- |
| 直接入库 | `A` | 直接选择档案位置或档案装具位置，创建后自动完成上架 |
| 暂不分配位置 | `B` | 先选择大致库房位置，创建后进入“新档上架”等待分配明确库位 |

本地静态词典里还保留了“档案载体类型”和“档案门类”的基础口径：载体类型包括纸质档案、电子档案、照片档案、音视频档案；档案门类包括文书档案、科技档案、会计档案、声像档案。项目落地时可以扩展字段，但这些名称应优先作为检索和导入导出的稳定口径。

这些字段是查询、权限、借阅审批和档案移交销毁判断的基础，不建议只作为普通备注字段维护。

### 档案分类

档案分类用于替代传统“卷宗”在系统里的组织作用。传统卷宗更像一组纸质材料的业务集合，但在智档宝里，分类应当承担“怎么归类、怎么检索、怎么授权、怎么统计”的职责；实体承载关系交给档案装具处理。

| 概念 | 当前口径 |
| --- | --- |
| 档案分类 | 档案的业务归属和目录层级，用来组织档案、设置查询条件、统计范围和权限范围 |
| 卷宗 | 作为传统业务说法保留理解，不建议在新模型里作为独立核心对象扩展 |
| 档案装具 | 档案盒、袋、夹等实体承载对象，解决“档案放在哪个盒子里” |
| 库区位置 | 库房、库区、架体、层格等空间位置，解决“档案或装具放在哪里” |

分类可以按客户业务定义成多级树，例如“年度 / 门类 / 保管期限 / 项目 / 部门”。同一份档案只要分类路径清楚，就可以被查询、导入、导出、授权和统计；是否装入某个档案盒，不应该改变它的分类含义。

前端实现上，档案分类对应的是 `/dir/*` 目录树接口，而不是一个叫“卷宗”的独立模型。系统支持维护根分类名称、加载子目录、新增、编辑、删除和批量排序。

| 能力 | 接口口径 |
| --- | --- |
| 分类树 | `/dir/getDirs`、`/dir/getDirChildren` |
| 新增 / 编辑 / 删除 | `/dir/addDir`、`/dir/editDir`、`/dir/deleteDir` |
| 排序 | `/dir/batchSort` |
| 根分类名称 | `/setting/getRootDirName`、`/setting/setRootDirName` |

```text
档案分类
├─ 文书档案
│  ├─ 永久
│  └─ 定期
├─ 项目档案
│  ├─ 项目 A
│  └─ 项目 B
└─ 会计档案
```

维护分类时要避免把“分类”和“装具”混用：分类是逻辑目录，装具是实体载体。一个分类下可以有很多档案，这些档案可以分布在多个档案盒中；一个档案盒也可能承载同一分类下的一批档案。

### 自定义字段

自定义字段用于承接不同项目、不同客户、不同档案类型的著录差异。它的目标是让项目可以扩展字段，而不是为了每个客户反复修改档案主数据。

| 字段类型 | 说明 |
| --- | --- |
| 档案扩展字段 | 补充档案主数据之外的项目著录项，例如合同编号、业务系统编号、责任人、所属项目等 |
| 字段展示 | 在档案详情、列表、查询条件中按项目需要展示 |
| 导入导出 | 导入模板、导出表格、批量维护时需要保持字段含义一致 |
| 项目差异 | 不同客户项目可以维护不同字段，但同一项目内字段命名要稳定 |

#### 历史方案演进

自定义字段在智档宝里不是一次成型的能力，历史上大致经历了“JSON 扩展字段”到“字段定义 + EAV 值表 + 表头配置”的演进。

| 阶段 | 方案 | 解决的问题 | 局限 |
| --- | --- | --- | --- |
| 早期方案 | 在档案或装具主数据里保存 JSON 格式扩展字段 | 不改数据库表结构就能承接项目著录差异，适合快速交付 | 查询、筛选、导入校验、字段重命名和统计都比较重，跨数据库兼容也不好控制 |
| 过渡方案 | 保留前端 `extends` 结构，字段用 `id-字段ID` 作为动态列标识 | 前端列表、详情、导入导出可以用统一方式处理标准字段和扩展字段 | 值如果只靠 JSON 保存，精确筛选和全文搜索仍然依赖额外解析 |
| 当前主线 | 字段定义表 + EAV 值表 + 每用户表头配置 | 字段可配置，值可按字段 ID 查询和筛选，列表列宽、排序、显隐可按用户保存 | 字段数量过多时查询会变复杂，需要控制字段治理和索引策略 |

当前实现里，档案和档案装具各自有一套扩展字段体系：档案使用 `sys_archive_extend`、`sys_archive_extend_value`、`sys_archive_field`；装具使用 `sys_box_extend`、`sys_box_extend_value`、`sys_box_field`。字段类型目前以 `text`、`date`、`select` 为主，`select` 字段需要维护可选值，必填字段会在建档或建装具时校验。

| 当前能力 | 档案接口 / 表 | 装具接口 / 表 | 说明 |
| --- | --- | --- | --- |
| 字段定义 | `/archive/addArchiveExt`、`/archive/editArchiveExt`、`/archive/deleteArchiveExt`、`sys_archive_extend` | `/box/addBoxExt`、`/box/editBoxExt`、`/box/deleteBoxExt`、`sys_box_extend` | 维护字段名称、类型、选项、必填和备注 |
| 字段值 | `sys_archive_extend_value` | `sys_box_extend_value` | 按对象 ID + 字段 ID 保存值，字段名冗余保存用于减少关联成本 |
| 表头配置 | `/archive/getArchiveSysExtList`、`/archive/setArchiveField`、`/archive/setArchiveFieldWidth`、`sys_archive_field` | `/box/getBoxExtSysList`、`/box/setBoxField`、`/box/setBoxFieldWidth`、`sys_box_field` | 支持列表列显隐、排序、列宽和动态字段列 |
| 查询筛选 | `id-字段ID` 进入字段过滤，EAV 子查询匹配 | `id-字段ID` 进入字段过滤，EAV 子查询匹配 | 前端动态列的 `dataIndex` 形如 `id-12` |
| 导入导出 | `archive_excel.go` | `box_excel.go` | 导入模板和导出清单会读取扩展字段定义 |

因此，文档里说“自定义字段”时要区分三个层面：字段定义决定能填什么，字段值记录每个档案或装具填了什么，表头配置决定某个用户在列表里怎么看。不要把扩展字段直接理解成“在主表里临时加一列”。

维护原则：

* 标准字段用于所有项目都稳定存在的内容，例如档案编号、名称、状态、密级、位置。
* 自定义字段用于项目差异和客户著录差异，例如额外编号、业务分类、备注字段。
* 自定义字段应进入查询、导入、导出和详情展示，但不应直接替代生命周期状态、库位、借阅审批等核心字段。
* 字段名称、字段类型和导入导出口径需要稳定维护，避免同一含义在不同项目中出现多个名字。

### 导入导出

导入导出是档案管理的批量交付入口。它不只是“下载 Excel / 上传 Excel”，还承担字段模板、数据校验、错误回填、批量建档、批量建装具和现场核对清单的职责。

| 能力 | 档案 | 档案装具 | 说明 |
| --- | --- | --- | --- |
| 下载模板 | `/archive/excelTemplate` | `/box/excelTemplate` | 根据基础字段和当前扩展字段生成模板 |
| 上传文件 | `/archive/importExcelUpload` | `/box/importExcelUpload` | 上传后校验文件类型、表头和重复导入 |
| 开始导入 | `/archive/importExcelStart` | `/box/importExcelStart` | 使用上传返回的 `key` 执行导入，档案装具导入还会带位置和分类参数 |
| 错误文件 | `/archive/downloadExcelError` | `/box/downloadExcelError` | 把验证错误、创建错误写回原 Excel，便于修正后重新提交 |
| 导出列表 | `/archive/exportArchiveList` | `/box/exportBoxList` | 支持导出所选、导出本页、导出全部 |
| 出库导出 | 出库档案列表 | 出库档案装具列表 | 表头会把删除人、删除原因、删除时间替换成出库人、出库原因、出库时间 |

当前导入流程分两步：先上传 Excel，后端读取并缓存文件，返回导入 `key`；再由前端带 `key` 调用开始导入接口。这样做的好处是可以先做表头校验和重复文件判断，再进入真正的数据校验和批量创建。

```text
下载模板
  ↓
填写 Excel
  ↓
上传文件，得到 key
  ↓
开始导入
  ├─ 成功：生成档案 / 装具并写入日志
  └─ 失败：下载带错误列和批注的 Excel，修正后重新上传
```

| 校验点 | 产品口径 |
| --- | --- |
| 表头校验 | 档案模板必须包含“档案名称”，装具模板必须包含“档案装具名称” |
| 必填字段 | 档案名称、档案编号、装具名称、编号、类型，以及自定义字段中标记为必填的字段 |
| 编号唯一 | 档案编号和装具编号不应重复，批量文件内部也要避免重复 |
| 下拉字段 | 保密等级、有效期、装具类型、`select` 自定义字段需要使用模板提供的可选值 |
| 时间字段 | 支持常见日期时间格式，导入错误文件会尽量保留时间列格式 |
| 位置和分类 | 导入时需要明确对象最终归属的库房、库区、位置或分类，不能只靠 Excel 备注描述 |
| 并发导入 | 当前档案导入和装具导入各自有导入锁，同一类导入任务同时只处理一个 |
| 重复文件 | 后端会计算文件 MD5，避免同一文件被重复导入 |

导出要区分“业务清单”和“数据迁移”。导出所选、本页、全部适合现场核对和交付清单；如果要做系统间迁移，必须确认字段定义、分类树、库区位置和装具关系是否已经在目标系统中存在。不要把导出的列表文件直接当作完整备份。

### 档案生命周期

档案生命周期描述实体档案从建档、上架、借阅、归还到异常处理和最终销毁的完整状态流转。

```text
建档 / 导入
  ↓
待上架
  ↓
在库
  ├─ 借阅审批中
  │   ↓
  │  借阅待取
  │   ↓
  │  借阅中
  │   ↓
  │  归还待上架
  │   ↓
  │  在库
  ├─ 盘点异常
  │   ├─ 不在库
  │   └─ 遗失
  ├─ 删除 / 回收站
  └─ 已销毁
```

| 状态 / 场景 | 产品说明 |
| --- | --- |
| 待上架 | 档案已经建档或导入，但还没有落到明确库位 |
| 在库 | 档案已经绑定库位，处于可借阅、可盘点状态 |
| 借阅审批中 | 借阅申请已提交，等待审批 |
| 借阅待取 | 审批通过但档案还未被取走 |
| 借阅中 | 档案已经借出 |
| 归还待上架 | 档案已归还，但还未重新绑定或确认库位 |
| 借阅超期 | 借阅超过期限，需要提醒或处理 |
| 不在库 | 盘点或现场识别发现档案不在预期位置 |
| 遗失 | 经业务确认后的遗失状态 |
| 删除 / 回收站 | 软删除状态，可恢复 |
| 已出库 | 通过出库操作移出当前库内管理，可在“已出库档案”中找回 |
| 已销毁 | 业务上已销毁或停止使用，不再作为正常档案流转 |

当前前端列表常用状态筛选集中在 `待上架`、`在库`、`借阅`、`归还上架`。`借阅审批`、`待取档案`、`在借档案`、`超期档案`更多体现为维护页队列和审批关系，不应简单等同于档案主表的单一状态。回转柜还会额外使用 `未在库`、`借阅未取`、`归还待上架` 等合成展示状态，具体口径见“回转柜档案状态”。

回转柜盘点会影响状态展示。例如回转柜盘点结果为“正常 / 盘盈”时，可以展示为“在位”；否则展示为“不在位”。回转柜盘点结果不应直接替代业务审批流程，但会提示后续处理动作。

### 借阅与归还

借阅能力由审批流程承载，档案和装具都可能参与借阅。

| 阶段 | 产品说明 |
| --- | --- |
| 申请 | 用户选择档案、装具或电子档案发起借阅 |
| 审批 | 审批人确认是否允许借阅 |
| 待取 | 审批通过，等待现场取档 |
| 借阅中 | 档案已从库位取走，进入借阅周期 |
| 归还 | 借阅完成后归还档案 |
| 归还待上架 | 归还后还需要重新确认库位 |
| 超期 | 超过借阅期限，进入提醒或处理 |

前端真实流程里，借阅从“借阅车”开始，审批通过后进入待取，现场取档后进入在借，归还后再进入归还上架。

| 操作入口 | 接口口径 | 说明 |
| --- | --- | --- |
| 借阅车 | `/borrow/list`、`/borrow/add`、`/borrow/delete`、`/borrow/deletes` | 临时收集要借阅的档案、装具或电子档案 |
| 创建借阅 | `/borrow/create` | 提交用途、原因、期限、审批人和借阅对象 |
| 审批列表 / 详情 | `/approval/list`、`/approval/info` | 查看审批单及其中的档案、装具对象 |
| 同意 / 拒绝 | `/approval/agree`、`/approval/reject` | 审批人处理申请 |
| 开始取档 | `/approval/start` | 审批通过后进入现场取档阶段 |
| 归还 | `/approval/return` | 借阅完成后登记归还 |
| 归还上架 | `/approval/getArchiveList`、`/approval/getBoxList`、`/approval/returnShelf` | 对已归还对象重新确认库位 |

借阅状态和回转柜盘点结果会互相影响展示。例如“借阅待取”但回转柜盘点仍在位，可以理解为审批通过但现场未取；“借阅中”但回转柜盘点仍在位，则需要业务处理确认。

### 维护页面口径

档案维护页本质是一组待办和异常队列，和概览页的对象清单互相补充。

| 维护入口 | 产品口径 | 关键动作 |
| --- | --- | --- |
| 新档上架 | 创建时选择“暂不分配位置”的档案和装具 | 计算可用容量、选择明确位置、完成上架 |
| 档案回收站 | 软删除后的档案和装具 | 恢复、销毁、导出 |
| 遗失档案 | 借阅或盘点后确认遗失的对象 | 找回、彻底遗失、导出 |
| 已出库档案 | 出库后的档案和装具 | 找回到原位置或进入新档上架 |
| 待取档案 | 审批通过但尚未取走的对象 | 查看审批、开始取档或后续流转 |
| 在借档案 | 已借出对象 | 查看审批、全部归还上架、标记存在遗失 |
| 超期档案 | 借阅超过期限的对象 | 提醒处理、归还上架、标记遗失 |
| 归还上架 | 已归还但未重新上架的对象 | 选择上架模式、确认位置、完成归还上架 |
| 借阅用户 | 借阅人和审批相关账号 | 新增、编辑、启停、修改密码 |

### 回转柜盘点

这里的盘点特指回转柜盘点，用于校验系统记录和回转柜内实物是否一致。当前支持定时、手动、自动等盘点类型，结果包含正常、盘盈、盘亏、异常、设备忙、设备离线。

| 回转柜盘点结果 | 产品说明 |
| --- | --- |
| 正常 | 系统记录和现场识别一致 |
| 盘盈 | 现场识别到系统预期外或位置外的档案 |
| 盘亏 | 系统记录应在库，但现场未识别到 |
| 异常 | 盘点过程出现业务或数据异常 |
| 设备忙 | 回转柜设备暂时无法执行盘点 |
| 设备离线 | 设备不可用或通信失败 |

回转柜盘点结果需要给出处理动作，例如更改档案状态为未在库、档案上架至位置、档案转移至位置、借阅未取、已借阅取走、已归还上架、新建未知档案等。处理动作应由业务人员确认后执行，避免设备误读直接改变档案业务状态。

## 档案装具

档案装具用于承载和组织实体档案。它既有自己的基础信息和状态，也能绑定位置、参与借阅和盘点。

| 装具类型 | 说明 |
| --- | --- |
| 档案盒 | 最常见的档案载体，可包含多份档案 |
| 档案袋 | 适合零散或特定材料归集 |
| 档案夹 | 适合临时或轻量归档 |
| 档案箱 | 适合批量存放 |
| 档案架 | 可作为普通实体架具记录 |
| 防磁柜 | 适合特殊载体或安全要求更高的材料 |
| 光盘 / 磁带 | 用于电子介质归档 |

| 能力 | 说明 |
| --- | --- |
| 基础信息 | 装具名称、编号、类型、状态、密级、有效期 |
| 自定义字段 | 承接不同项目对装具的额外著录要求 |
| 装具内档案 | 一个装具可包含多份档案 |
| 所在库位 | 装具可以落到库区、密集架或其他库位中 |
| 借阅 / 归还 | 装具可参与借阅、归还和待上架流程 |
| 盘点 / 异常处理 | 装具可参与盘点、异常定位和差异处理 |

### 组卷与拆卷

组卷和拆卷在系统里更适合理解为“档案与装具关系的建立、重建和销毁”，而不是重新发明一个卷宗对象。当前前端的拆卷口径比较强：拆卷时会销毁档案装具，并要求给拆出的档案重新指定位置或待上架范围。

| 操作 | 产品含义 | 系统变化 |
| --- | --- | --- |
| 组卷到新装具 | 把若干份档案归入新建档案盒、档案袋或档案夹 | 先创建装具，再调用 `/archive/archiveRoll` 建立档案与新装具关系 |
| 组卷到已有装具 | 把若干份档案归入已有档案装具 | 直接调用 `/archive/archiveRoll`，档案原先在其他装具中时会移入目标装具 |
| 拆卷 | 将一个装具拆开，拆出的档案重新选择位置、库房位置和分类 | 调用 `/box/unRoll`；前端提示会销毁档案装具，并记录拆卷原因 |
| 位置转移 | 档案或装具从一个库位转移到另一个库位 | 调用档案或装具批量转移接口，分类不应变化 |
| 整盒上架 | 装具整体绑定到库位 | 装具内档案继承或关联该装具位置，现场按盒取放 |
| 整盒借阅 | 借阅对象选择装具 | 装具和装具内档案都需要进入可追踪的借阅状态 |

组卷时要先确认档案分类和基础著录已经稳定，再把档案放入装具。前端组卷弹窗会提示：如果所选档案在现有装具中，组卷完成后档案将移入新的装具。拆卷时必须保留操作记录，尤其是借阅中、归还待上架、盘点异常的档案，不能只删除装具关系后就认为业务完成。

上架时既可能直接上架档案，也可能先把档案归入装具，再把装具放到密集架或其他库位中。回转柜当前更适合按档案直接落格口理解，不建议默认把装具逻辑套到回转柜上。

## 打印

打印在档案管理中主要服务于“实物标识”和“业务单据”。产品上要先明确打印对象、模板字段和触发场景，具体打印服务、本地驱动、RFID 打印机协议等实现细节放到系统架构或设备文档中维护。

### 打印对象

| 对象 | 产品说明 |
| --- | --- |
| 档案标签 | 给单份档案生成纸质标签、条码、二维码或 RFID 标签内容，用于粘贴、识别和盘点 |
| 档案装具标签 | 给档案盒、档案袋、档案箱等装具生成标签，便于装具上架、借阅和盘点 |
| 借阅单 | 借阅审批通过后输出取档、借出、归还或签收单据 |
| 移交 / 上架单 | 批量建档、移交、上架、归档时输出操作清单 |
| 盘点单 | 盘点任务执行前后输出盘点范围、结果差异和处理记录 |
| 查询结果 | 按查询条件导出或打印档案列表，适合现场核对和人工流转 |

### 触发场景

| 场景 | 说明 |
| --- | --- |
| 建档后打印 | 档案建档或导入后打印档案标签 |
| 装具生成后打印 | 新建档案盒、档案袋或档案箱后打印装具标签 |
| 上架前打印 | 上架前打印位置、编号、装具和档案清单，便于现场核对 |
| 借阅审批后打印 | 审批通过后打印借阅单、取档单或签收单 |
| 归还处理时打印 | 归还后打印归还确认单或重新上架清单 |
| 盘点前后打印 | 盘点前打印盘点范围，盘点后打印差异和处理结果 |

### 模板和字段

打印模板应围绕业务对象维护，不建议在代码里写死版式。不同项目可以有不同模板，但字段含义要稳定。

| 模板字段 | 说明 |
| --- | --- |
| 基础字段 | 档案编号、档案名称、分类、年度、密级、保管期限 |
| 位置字段 | 库房、库区、架体、列、侧、节、层、格或回转柜格口 |
| 装具字段 | 装具编号、装具名称、装具类型、装具内档案数量 |
| 借阅字段 | 借阅人、部门、审批人、借阅时间、归还期限、用途 |
| 标识字段 | 条码、二维码、RFID 编码、系统唯一编号 |
| 项目字段 | 通过自定义字段补充项目特定著录项 |

### 服务演进和仓库

档案管理里的打印能力不是单个接口。它经历过普通标签 / 单据打印、本地打印服务增强，再到 RFID 标签打印的演进。写业务文档时建议按“业务对象”和“本地服务形态”分开描述。

| 阶段 | GitLab 仓库 | 当前定位 | 主要说明 |
| --- | --- | --- | --- |
| 老打印服务 | [`fit-archive/electron-hiprint`](https://gitlab.singzer.cn/fit-archive/electron-hiprint) | 普通打印和早期标签打印服务 | 基于 Electron 和 `vue-plugin-hiprint`，面向本机打印机列表、静默打印、PDF / HTML 打印等基础能力；历史接口以 Socket.IO `news` 等事件为主 |
| 新打印服务 | [`fit-archive/rfid/rfid-printer-node`](https://gitlab.singzer.cn/fit-archive/rfid/rfid-printer-node) | 当前打印服务演进版本 | 继续兼容普通打印，同时补充服务面板、打印机能力识别、日志、驱动检查、Socket.IO `17521` 端口和 `/api/printer-list` 等能力 |
| RFID 打印衍生 | [`fit-archive/rfid/rfid-printer-node`](https://gitlab.singzer.cn/fit-archive/rfid/rfid-printer-node)、[`fit-archive/rfid/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/rfid/fit-archive-ng)、[`fit-archive/rfid/smart-doc-vault-rfid`](https://gitlab.singzer.cn/fit-archive/rfid/smart-doc-vault-rfid)、[`fit-archive/rfid/rfid-device-go`](https://gitlab.singzer.cn/fit-archive/rfid/rfid-device-go) | RFID 标签打印、读写和现场识别链路 | 前端选择 RFID 打印能力，后端维护档案 / 标签业务关系，本地服务调用 RFID 打印机读 TID、写 EPC 或打印标签；设备服务负责 RFID 读写器和现场设备侧能力 |

普通打印和 RFID 打印不要混成同一种能力。普通打印解决“把单据或标签版式打出来”，RFID 打印还要处理标签芯片识别、TID / EPC、厂商 SDK、驱动、耗材状态和现场读写验证。

### 产品边界

* 档案管理负责决定“打印什么、什么时候打印、模板使用哪些业务字段”。
* 老打印服务、新打印服务和 RFID 打印服务都属于实现形态；档案管理页只维护业务对象、触发场景和字段口径。
* RFID 标签写入、RFID 打印机、TID / EPC 和标签协议归入 RFID 或设备接入文档。
* 普通打印机驱动、本地打印服务、`electron-hiprint`、`rfid-printer-node`、部署端口等实现放到系统架构或本地服务文档。
* 导出 Excel / PDF 和打印可以共用字段口径，但不要把导出能力直接等同于打印能力。

## 研发参考

结合当前智档宝代码结构，档案管理的核心模型不是单表档案，而是一组围绕“库区 + 档案 + 装具 + 状态 + 审批 + 盘点”的模型。

| 产品对象 | 代码模型 / 模块 | 产品含义 |
| --- | --- | --- |
| 档案 | `ArchiveModel` / `sys_archive` | 档案主数据，包含编号、名称、状态、密级、有效期、位置、RFID、扩展字段和电子档案挂接 |
| 档案装具 | `BoxModel` / `sys_box` | 档案盒、袋、夹、箱等实体载体，可绑定多个档案 |
| 库房位置 | `LocationModel` | 库房位置树，承载库房、楼层、房间等位置路径 |
| 库区 | `AreaModel` | 库房下的业务区域，区分智能密集架、回转柜等库区类型 |
| 架体 / 柜体 | `ShelfModel` / `sys_shelf` | 密集架列、固定列、移动列、回转柜柜体等实体架具 |
| 借阅审批 | `ApprovalModel` / `ApprovalConnectModel` | 借阅、待取、归还、超期、驳回、取消等流程状态 |
| 盘点任务 | `InventoryModel` | 手动、定时、自动盘点任务 |
| 回转柜盘点结果 | `InventoryResultModel` | 正常、盘盈、盘亏、异常、设备忙、设备离线等回转柜盘点明细 |

前端主要入口集中在 `fit-archive-ng/src/views/ArchivesManagement`，接口层集中在 `fit-archive-ng/src/api/ArchivesManagement`、`ApiBorrowManagement`、`ApiSystemManagement/apiArchivesSort`、`ApiReservoirManagement` 等目录。后端路由侧主要在 `smart-doc-vault/router/system/archive.go`、`box.go`、`borrow.go`、`approval.go`、`shelf.go`、`location.go`、`mjj.go`、`hzg.go`。

| 前端模块 | 主要接口 | 说明 |
| --- | --- | --- |
| `overview/File` | `/archive/getArchiveList`、`/archive/addArchive`、`/archive/editArchive`、`/archive/archiveRoll`、`/archive/batchTransferArchive`、`/archive/exportArchiveList` | 档案概览、新建、编辑、组卷、转移、导出和暂存 |
| `overview/FileBox` | `/box/getBoxList`、`/box/addBox`、`/box/editBox`、`/box/unRoll`、`/box/batchTransferBox`、`/box/exportBoxList` | 档案装具概览、新建、编辑、拆卷、转移、导出和暂存 |
| `maintain/PutOnShelves` | `/maintain/putOnShelves/getArchiveList`、`/archive/newArchiveShelf`、`/maintain/putOnShelves/getBoxList`、`/box/newBoxShelf` | 新档上架，分档案和装具 |
| `maintain/RecycleBin` | `/maintain/deleteArchiveList`、`/archive/recoverArchive`、`/archive/batchDestroyArchive`、`/maintain/deleteBoxList`、`/box/recoverBox`、`/box/batchDestroyBox` | 回收站恢复和销毁 |
| `ApiBorrowManagement` | `/borrow/create`、`/approval/list`、`/approval/info`、`/approval/agree`、`/approval/reject`、`/approval/start`、`/approval/return`、`/approval/returnShelf` | 借阅申请、审批、取档、归还和归还上架 |
| `ApiSystemManagement/apiArchivesSort` | `/dir/getDirs`、`/dir/getDirChildren`、`/dir/addDir`、`/dir/editDir`、`/dir/deleteDir`、`/dir/batchSort` | 档案分类目录树 |

### 关联仓库

| 仓库 / 目录 | 视角 | 说明 |
| --- | --- | --- |
| `fit-archive/fdmjj` | 密集架主线 | 飞度密集架相关前后端、设备联动和项目交付能力索引 |
| `fit-archive/hzg` | 回转柜主线 | 回转柜相关业务、库位映射和现场控制能力索引 |
| `fit-archive/A` | 项目版本线 | 架具能力在项目版本中的定制入口 |
| `fit-archive/B` | 项目版本线 | 架具能力在项目版本中的定制入口 |
| `fit-archive-ng` | 当前前端业务系统 | 档案总览、维护、上架、借阅审批、设备管理等页面入口 |
| `smart-doc-vault` | 后端主服务 | 档案、装具、审批、盘点、库房、架体、密集架、回转柜等 API 和业务服务 |
| `fit-denserack*` | 密集架终端 / 控制 | 密集架本地终端、开架接口、硬件控制和项目更新能力 |

## 产品边界

* 档案管理关注库区、档案、装具、生命周期、借阅、盘点和权限。
* 自定义字段只承接项目著录差异，不替代生命周期、库位、借阅审批等核心字段。
* 文件上传、文件解析、文件预览和全文搜索归入数字化。
* RFID 标签识别、门口机、手持机、盘点车归入 RFID。
* 温湿度、空调、除湿、漏水、摄像头、门禁等现场环境能力归入环境控制。
* 密集架 / 回转柜在档案管理中只描述架具、库位、状态和业务联动。
* 设备协议、服务进程、TCP / UDP / MQTT、数据库、对象存储等实现细节放到系统架构或设备接入文档。

---

---
url: /wiki/sdv/environment.md
---

# 环境控制

环境控制是智档宝面向库房环境和现场安全的能力板块，关注环境数据采集、设备控制、异常告警和现场联动。

![智档宝环境控制](/illustrations/sdv-environment-control-xiaohei.png)

## 设备草稿

下面这张是讲解现场设备、网络、网关和调试入口时使用的 Excalidraw 草稿，用于辅助理解环境控制设备接入，不作为最终架构定稿。

## 业务定位

环境控制回答“库房现场是否安全、环境是否正常、设备是否可控”的问题。它服务于档案保管环境，也服务于现场运维和大屏展示。

## 设备类型

环境控制设备先按设备类型组织，再在每个类型下面看具体型号、主子设备关系和业务能力。这样比直接按“温湿度、漏水、空调”罗列更接近现场调试和后端实现。

| 设备类型 | 说明 | 典型设备 |
| --- | --- | --- |
| POE 设备 | 飞度自研或适配的 POE / MQTT 设备，是当前环境控制主线 | 网关 Lite、中枢网关、空气质量传感器、温湿度传感器、漏水报警、短信报警、16DI、8DO、加湿除湿一体机 |
| 其他设备 | 不走 POE 设备模型，但属于库房现场安防和视频能力 | 推流盒子、摄像头、门禁、海康 ISAPI / 网关、监控平台 |
| 虚拟设备 | 不一定有独立硬件，更多是平台内聚合、映射或软件状态 | 大屏卡片、智能面板展示项、软件模拟设备、状态聚合设备 |
| 无线设备 | 通过无线网络或 LoRaWAN 平台进入系统，后端以 `chirpstack` 源类型区分 | ChirpStack 设备、无线温湿度、无线采集节点 |

### POE 设备

POE 设备是当前环境控制的主线设备模型。这里的“POE”不只是供电方式，也代表一套现场接入方式：设备接入局域网，平台先通过 UDP 做发现和网络配置，再通过 MQTT 做运行期数据上报、状态同步和控制下发。

#### UDP

UDP 是 POE 设备的现场发现和初始化配置通道。设备刚上电、还没有接入平台时，实施人员先通过 UDP 在局域网里找到设备，再把设备改到正确的网络和 MQTT 配置。

| 能力 | 说明 |
| --- | --- |
| 发现设备 | 扫描局域网里的 POE 设备，拿到 SN、IP、MAC、设备型号、固件版本等基础信息 |
| 设置 IP | 把设备设置为静态 IP 或指定网络参数，避免现场重启后地址漂移 |
| 设置 MQTT | 把 MQTT 服务器地址、端口等连接参数写入设备 |
| 重启 / 重置 | 远程重启设备，或在配置错误时重置设备 |

| 端口 | 方向 / 场景 | 说明 |
| --- | --- | --- |
| `10086/udp` | 平台广播 / 发现 / 配置 | 当前 `fdmjj` 后端 `UdpBoardCast` 使用的主线端口，后端 Dockerfile 也暴露这个 UDP 端口 |
| `1234/udp` | 历史发现 / 模拟工具 / 软网关兼容 | `virtual-device-builder`、`soft-gateway` 等历史或模拟工具仍会向 `255.255.255.255:1234` 广播设备状态，后端 Dockerfile 也保留暴露 |
| `1883/tcp` | MQTT 连接结果 | 不是 UDP 端口；UDP 的 `Set_Mqtt` 会把设备指向这个 MQTT broker 端口 |

现场排查时不要只看其中一个 UDP 端口。当前主线配置优先看 `10086/udp`，但历史虚拟设备、软网关和部分调试工具可能还在发 `1234/udp`；防火墙、容器端口映射、交换机 VLAN 和广播隔离要一起确认。

| UDP 命令 | 方向 | 用途 |
| --- | --- | --- |
| `Device_Status_BoardCast` | 设备 -> 平台 | 设备主动广播自己的 SN、IP、MAC、固件、MQTT 状态和基础信息，用于设备列表和在线发现 |
| `DISCOVERY` | 设备 -> 平台 | 设备请求平台下发 MQTT 地址；平台侧需要打开设备发现开关才会响应 |
| `Set_Mqtt` | 平台 -> 设备 | 下发 MQTT broker 地址和端口，让设备进入运行期 MQTT 通道 |
| `IP_MODE_SET` | 平台 -> 设备 | 设置静态 IP、网关、掩码、DNS 或网络模式 |
| `REBOOT` | 平台 -> 设备 | 重启设备 |
| `RESET` | 平台 -> 设备 | 重置设备配置 |

设备状态广播示例，常见于 `Device_Status_BoardCast`：

```json
{
  "device_info": {
    "device_type": "FEIDU_POE_GATEWAY_LITE",
    "HW_version": "1.0",
    "FW_version": "1.4.0",
    "role": "NONE",
    "read_time_interval": 5000,
    "compile_time": 1714576349,
    "device_sn": "e465b86741fb",
    "ip": "192.168.0.52",
    "mac": "E4:65:B8:67:41:FB",
    "gateway": "192.168.0.1",
    "dns": "169.254.0.1",
    "subnet": "255.255.255.0",
    "NetWork_Mode": "STATIC",
    "mqtt_server_host": "192.168.0.2",
    "mqtt_server_port": 1883,
    "clientID": "esp32-e465b86741fb",
    "mqtt_status": true,
    "mqtt_config_st": "true",
    "device_ota_status": "false",
    "register_status": "false",
    "deviceOnDI1": "none",
    "deviceOnDI2": "none",
    "deviceOnDI3": "none",
    "deviceOnDI4": "none"
  },
  "command": "Device_Status_BoardCast",
  "task_id": -1,
  "param": {
    "message": "Device_Status_BoardCast"
  }
}
```

设备主动发现示例：

```json
{
  "device_info": {
    "device_sn": "e465b86741fb"
  },
  "command": "DISCOVERY",
  "task_id": 1,
  "param": {}
}
```

平台回发 MQTT 配置示例：

```json
{
  "device_sn": "e465b86741fb",
  "command": "Set_Mqtt",
  "task_id": 1,
  "mqtt_server_host": "192.168.0.2",
  "mqtt_server_port": "1883"
}
```

平台下发网络配置示例：

```json
{
  "device_sn": "e465b86741fb",
  "command": "IP_MODE_SET",
  "task_id": 1710000000000,
  "param": {
    "NetWork_Mode": "STATIC",
    "ip": "192.168.0.52",
    "gateway": "192.168.0.1",
    "subnet": "255.255.255.0",
    "dns": "192.168.0.1"
  }
}
```

平台重启 / 重置设备示例：

```json
{
  "device_sn": "e465b86741fb",
  "command": "REBOOT",
  "task_id": 123
}
```

```json
{
  "device_sn": "e465b86741fb",
  "command": "RESET",
  "task_id": 123
}
```

UDP 解决的是“设备在哪里、怎么让它连上平台”。如果 UDP 扫不到设备，优先检查供电、网线、交换机 VLAN、电脑和设备是否在同一网段，以及现场防火墙是否拦截广播。

#### MQTT

MQTT 是 POE 设备运行期的主通道。设备完成 UDP 初始化后，会连接到平台配置的 MQTT 服务，后端再根据设备消息创建、更新和控制设备。

参考资料：[POE 设备 MQTT 协议说明](https://www.yuque.com/u278353/kb/cctwwabm0lm313sh?singleDoc#)。

当前 `fdmjj` 后端订阅的是固定 topic，不是按设备 SN 分 topic。旧代码注释里出现过 `/sn/control`、`/sn/information`、`/sn/warning` 这种方向，但当前主线按 `information`、`warning`、`control` 三个 topic 维护。

| Topic | 方向 | 用途 | 后端入口 |
| --- | --- | --- | --- |
| `information` | 设备 / 虚拟设备 -> 后端 | 常规状态、传感器数据、控制回包、心跳类数据 | `MqttInfoMessageHandler` |
| `warning` | 设备 / 虚拟设备 -> 后端 | 突发事件、DI 变化、报警触发类数据 | `MqttWarningMessageHandler` |
| `control` | 后端 -> 设备 / 虚拟设备 | 控制命令、读取命令、继电器控制、空调控制、设置命令 | `SendCommand` 发布 |

| 消息对象 | 说明 |
| --- | --- |
| `device_info` | 设备基础信息，包含 `device_type`、SN、IP、MAC、固件版本、MQTT 状态等 |
| `command` | 设备上报或控制命令，例如传感器读取、继电器状态、空调控制、漏水状态等 |
| `param` | 命令参数和业务数据，例如温湿度、空气质量、串口号、地址、DI/DO 状态等 |
| `device_type` | 后端识别设备处理分支的关键字段，例如 `FEIDU_POE_GATEWAY_LITE` |
| `task_id` | `-1` 表示普通上报；非负数通常表示控制请求 / 回包，用于后端等待响应 |
| `device_sn` | 控制下发时放在顶层；设备上报时以 `device_info.device_sn` 为准 |

后端按 `device_type` 分流处理 MQTT 消息。主设备消息会更新自己的在线和状态；网关类设备还会根据串口、地址、DI/DO 通道，把数据同步到子设备。

设备状态上报示例，发布到 `information`：

```json
{
  "device_info": {
    "device_type": "FEIDU_POE_AIR_SENSOR",
    "HW_version": "0.3",
    "FW_version": "1.2.3",
    "role": "NONE",
    "read_time_interval": 5000,
    "compile_time": 1714455742,
    "device_sn": "a0b765fa0c77",
    "ip": "192.168.0.55",
    "mac": "A0:B7:65:FA:0C:77",
    "gateway": "192.168.0.1",
    "dns": "169.254.0.1",
    "subnet": "255.255.255.0",
    "NetWork_Mode": "STATIC",
    "mqtt_server_host": "192.168.0.2",
    "mqtt_server_port": 1883,
    "clientID": "esp32-a0b765fa0c77",
    "mqtt_status": true,
    "mqtt_config_st": "true",
    "register_status": "false"
  },
  "command": "get_sensor",
  "task_id": -1,
  "param": {
    "temp": 19.48,
    "humidity": 31.65,
    "tvoc": 216,
    "eco2": 534,
    "pm10": 31,
    "pm25": 46,
    "pm100": 58,
    "ch2o": 0.052
  }
}
```

网关子设备上报示例，发布到 `information`。后端会按 `device_info.device_sn + serial + address` 形成子设备 SN，例如 `e465b86741fb_Serial1_3`：

```json
{
  "device_info": {
    "device_type": "FEIDU_POE_GATEWAY_LITE",
    "device_sn": "e465b86741fb",
    "clientID": "esp32-e465b86741fb",
    "mqtt_status": true,
    "mqtt_config_st": "true"
  },
  "command": "get_device_temp_hum",
  "task_id": -1,
  "param": {
    "serial": "Serial1",
    "address": 3,
    "temperature": 22.6,
    "humidity": 53.1,
    "message": "success"
  }
}
```

DI 变化示例，发布到 `warning`。后端只处理 `DIstatusN = Changed` 的通道，并把对应子设备状态同步到 Redis 和报警逻辑：

```json
{
  "device_info": {
    "device_type": "FEIDU_POE_16DI_CONTROL",
    "device_sn": "d8132a2f7a1b"
  },
  "command": "IO_change",
  "task_id": -1,
  "param": {
    "DI1": 1,
    "DIstatus1": "Changed",
    "DI2": 0,
    "DIstatus2": "Unchanged"
  }
}
```

后端控制示例，发布到 `control`。设备或虚拟设备需要订阅 `control`，按顶层 `device_sn` 判断是否是自己的命令；如果 `device_sn = "#"`，表示广播命令：

```json
{
  "command": "relay_control",
  "task_id": 123,
  "device_sn": "08f9e08bd9f3",
  "relay_states": [
    {
      "relay_index": 1,
      "activate": true,
      "connection_type": "normally_open"
    }
  ],
  "param": {}
}
```

控制类命令如果需要同步等待结果，设备应在 `information` 回一条相同 `task_id` 的消息。后端会把回包放进内存消息中心的 `task_<task_id>`；空调学习是例外，使用 `air_conditioner_learn_<device_sn>` 等待。

| 常见 `device_type` | 常见 `command` | 处理逻辑 |
| --- | --- | --- |
| `FEIDU_POE_AIR_SENSOR` | `get_sensor` | 直接更新空气质量传感器状态 |
| `FEIDU_POE_GATEWAY_LITE` | `get_io_status` | 更新网关状态，并同步 DI 子设备 |
| `FEIDU_POE_GATEWAY_LITE` | `relay_status_read` | 按 `relay_states` 创建 / 更新 DO 子设备 |
| `FEIDU_POE_GATEWAY_LITE` | `get_device_temp_hum`、`get_air_quality` | 按 `serial` + `address` 更新网关串口子设备 |
| `FEIDU_POE_GATEWAY_LITE` | `custom_*` | 自定义第三方设备数据，直接同步到 `网关SN_serial_address` |
| `FEIDU_POE_16DI_CONTROL` | `get_io_status`、`IO_change` | 16DI 主设备状态和 DI 子通道状态 |
| `FEIDU_POE_8DO_CONTROLLER` | `relay_status_read` | 8DO 主设备状态和继电器子通道状态 |
| `FEIDU_POE_DEHUMIDIFIER` | `DEVICE_STATUS_PUBLISH` | 独立 POE 加湿除湿一体机状态 |

#### 在线方式

POE 设备在线不是只看页面上有没有设备，而是看设备是否能持续完成“网络连接 -> MQTT 连接 -> 状态上报 -> 后端更新时间”这条链路。

| 判断层 | 说明 |
| --- | --- |
| UDP 可发现 | 说明设备在局域网里可见，但不等于已经接入业务系统 |
| MQTT 已连接 | 说明设备已经连上 MQTT 服务，是进入业务系统的前提 |
| 最近有上报 | 后端根据最新 MQTT 消息刷新 `LastUpdateTime`、缓存和设备状态 |
| 主子设备关系正常 | 数据库里主设备 `isMain = true`，子设备通过 `pid` 挂到主设备下 |
| 来源类型正确 | POE 主线设备默认属于 `sourceType = fit`，区别于无线设备的 `sourceType = chirpstack` |

典型链路是：设备上电入网后，实施先用 UDP 扫描到设备，配置设备 IP 和 MQTT 服务器；设备连接 MQTT 后上报 `device_info`、`command`、`param`；后端按 `device_type` 创建或更新主设备，再按串口、地址、DI/DO 通道派生子设备。

现场排查时可以按这个顺序判断：先看 UDP 能不能发现设备；再看设备是否配置到正确的 MQTT 地址；再看 MQTT 是否在线并上报；最后看数据库里主设备 `isMain`、子设备 `pid`、SN 命名和通道绑定是否正确。

#### 设备类型

POE 设备内部再按设备层级理解：主设备直接入网，子设备挂在主设备下面；部分独立传感器虽然不管理子设备，但仍作为 POE 主设备接入。

| 层级 | 说明 | 典型设备 / 能力 |
| --- | --- | --- |
| 主设备 | 直接入网，有独立 SN，平台把它作为设备树的根节点或独立节点 | 网关 Lite、中枢网关、16DI、8DO、空气质量传感器、短信报警模块、POE 加湿除湿一体机、漏水报警模块 |
| 网关串口子设备 | 挂在网关串口下，通常按“父设备 SN + 串口 + 地址”形成子设备 SN | 空调控制器、新风净化一体机、加湿除湿一体机、紫外线传感器、除霉机、新风机、窗帘、驱鼠器、健康防护一体机 |
| DI 输入子设备 | 挂在网关或 16DI 下，采集开关量、报警输入或传感器触发状态 | 人体传感器、烟雾传感器、消防主机、温感传感器、漏水报警监测点、未连接通道 |
| DO 输出子设备 | 挂在网关或 8DO 下，用于继电器输出、声光报警或设备联动 | 声光报警器、继电器输出、8DO 子设备 |
| 展示 / 操作子设备 | 以设备身份进入页面或大屏，但更多承担展示、入口或现场操作能力 | 智能面板、大屏可视设备图标 |

#### POE 主设备列表

| 设备型号 | 中文名称 | 主要职责 | 备注 |
| --- | --- | --- | --- |
| `FEIDU_POE_GATEWAY_LITE` | 网关 Lite | 通过 MQTT 接入平台，管理 DI 通道、DO 输出和串口子设备 | 常见现场主网关；创建后会自动生成 DI 子通道 |
| `FEIDU_POE_CENTER_CONTROL` | 中枢网关 | 汇总或控制一组环境设备，处理传感器和漏水等状态 | 更偏集中控制入口 |
| `FEIDU_POE_16DI_CONTROL` | 16 路采集 | 采集多路开关量输入 | 常用于人体、烟感、消防、温感等输入 |
| `FEIDU_POE_8DO_CONTROLLER` | 8 路控制 | 控制多路继电器输出 | 常用于声光报警、联动输出 |
| `FEIDU_POE_AIR_SENSOR` | 空气质量传感器 | 上报温湿度、PM、TVOC、CO2、甲醛等空气质量数据 | 直接 MQTT 上报，更新频率较高 |
| `FEIDU_POE_DEHUMIDIFIER` | POE 加湿除湿一体机 | 上报和控制加湿、除湿、漏水等状态 | 作为独立主设备接入 |
| `FEIDU_POE_SMS_SENDER` | 短信报警模块 | 上报在线和时间状态，配合报警通知 | 常用于现场短信告警 |
| `FEIDU_POE_VOICE_ALARM_WATER_LEAK_SENSOR` | 漏水报警模块 | 上报漏水状态和监测点状态 | 可以派生漏水报警监测点 |

#### 网关子设备列表

| 子设备类型 | 代码 / 显示名 | 接入逻辑 | 典型用途 |
| --- | --- | --- | --- |
| 空调控制器 | `空调控制器` | 挂在网关串口，按串口和地址轮询状态、下发控制 | 空调学习、空调控制、环境联动 |
| 新风净化一体机 | `新风净化一体机` | 挂在网关串口，读取和控制净化设备 | 空气质量联动 |
| 加湿除湿一体机 | `加湿除湿一体机` | 可作为网关串口子设备，也可能有独立 POE 型号 | 湿度控制、恒温恒湿 |
| 紫外线传感器 | `紫外线传感器` | 挂在网关串口，上报紫外线状态 | 特殊环境监测 |
| 除霉机 | `除霉机` | 挂在网关串口，读取和控制除霉设备 | 库房环境治理 |
| 新风机 | `新风机` | 挂在网关串口，读取和控制新风设备 | 通风联动 |
| 智能窗帘 | `智能窗帘` | 挂在网关串口，执行窗帘控制 | 光照或现场联动 |
| 网关串口漏水报警 | `网关-串口-漏水报警` | 挂在网关串口，上报漏水状态 | 漏水报警和联动 |
| 网关空气质量传感器 | `空气质量传感器` | 挂在网关串口，上报空气质量数据 | 温湿度、PM、TVOC、CO2 等 |
| 驱鼠器 | `驱鼠器` | 挂在网关串口，读取或控制设备状态 | 安防和库房防护 |
| 健康防护一体机 | `健康防护一体机` | 挂在网关串口，读取和控制设备 | 综合环境治理 |
| 温湿度传感器 | `温湿度传感器` | 挂在网关串口，上报温湿度 | 环境曲线和报警 |
| 智能面板 | `智能面板` | 挂在网关下面，作为现场展示和操作入口 | 大屏、面板、库房现场查看 |

#### DI / DO 通道设备

| 类型 | 设备 / 通道 | 逻辑 |
| --- | --- | --- |
| DI 输入 | 人体传感器、烟雾传感器、消防主机、温感传感器 | 后端把输入通道作为子设备管理，通道状态变化进入报警或联动逻辑。 |
| 漏水监测点 | `漏水报警监测点` | 漏水模块或网关串口漏水设备可以拆出监测点，用于区分具体漏水位置。 |
| DO 输出 | 声光报警器、继电器输出、8DO 子设备 | 输出通道用于报警联动、手动控制或自动控制策略。 |
| 未连接 | `未连接` | 网关 DI 通道默认可能先建成未连接，用于保留通道位置；现场绑定后再变成具体传感器。 |

### 其他设备

其他设备通常走独立接口或厂商协议，不一定进入 POE 的主子设备树，但产品上仍属于环境控制现场能力。当前按监控和门禁两条线维护。

#### 监控

监控能力围绕摄像头接入、通道配置和视频预览。当前推流盒子对接的是讯思维（`xsw`），后端通过 `smart-doc-vault/xsw` 访问推流盒子。这里用的是逆向网页接口，不是按厂商正式对接文档接入；维护时应以现有页面接口、登录态和返回结构为准。

| 能力 | 当前口径 |
| --- | --- |
| 推流盒子 | 当前对接讯思维（`xsw`），作为监控推流服务器管理 |
| 摄像头通道 | 在推流盒子下维护通道、RTSP 地址、用户名、密码和所属位置 |
| 流状态 | 通过逆向网页接口读取讯思维设备信息、通道配置、推流状态和带宽信息 |
| 预览地址 | 后端按推流盒子 IP 和通道拼出 FLV、WebSocket FLV、RTMP、HLS、HTTP-TS、RTSP 等地址；前端当前优先播放 `wsFlv` |
| 页面入口 | 设备管理 / 监控、库房监控大屏卡片、3D 库房或设备点位预览 |

当前前端监控预览不是普通 `<video>` 直接播 RTSP。推流盒子先把摄像头 RTSP 拉进来，再对外提供多种流地址；前端大屏和设备监控页面主要取 `cameraModel.wsFlv`，也就是 `ws://<推流盒子>/ws/hlsram/liveN.flv` 这种 WebSocket FLV 地址，然后交给 Jessibuca 播放器解码渲染。

| 播放链路 | 当前口径 |
| --- | --- |
| 摄像头到推流盒子 | 摄像头侧通常提供 RTSP，通道配置里保存 `rtspUri`、用户名、密码 |
| 推流盒子到后端 | 后端通过讯思维逆向接口读取通道、带宽和状态 |
| 后端返回地址 | `CameraModel.AfterFind` 和大屏 WebSocket 会生成 `httpFlv`、`wsFlv`、`rtmp`、`hls`、`httpTs`、`rstp` |
| 前端实际播放 | 大屏和监控组件取 `wsFlv`，用 Jessibuca 创建播放器实例并调用 `play(wsFlv)` |
| 多路同屏 | 每个通道创建独立 Jessibuca 实例，退出或重连时销毁旧实例，避免页面长期堆积解码器 |

前端选择 `ws-flv + Jessibuca`，主要是为了解决库房监控大屏六路以上同屏播放的问题。浏览器原生能力不能直接播放 RTSP，HLS 延迟偏高，多路 `<video>` + 普通 FLV 方案在低配终端上容易卡顿。当前播放器配置启用了 `useMSE`、`useSIMD`、`autoWasm` 和 `demuxUseWorker`：能走 MediaSource 时走 MSE，解码失败或环境不支持时自动降级到 WASM，解封装放到 worker 里做，音频关闭以减少 CPU 消耗。

| 前端播放器配置 | 作用 |
| --- | --- |
| `videoBuffer: 0.2` | 控制低延迟缓存，减少监控画面滞后 |
| `useMSE: true` | 优先使用 MediaSource 播放 FLV 流 |
| `useSIMD: true` | 在支持的浏览器上启用 SIMD 加速 |
| `autoWasm: true` | 解码路径不可用时自动走 WASM 能力 |
| `demuxUseWorker: true` | 把 FLV 解封装放到 worker，减少主线程压力 |
| `hasAudio: false` | 监控预览不解音频，降低多路同屏负载 |
| `loadingTimeoutReplayTimes: -1` / `heartTimeoutReplayTimes: -1` | 播放异常时持续重试，适配现场网络抖动 |

排查监控画面时按链路分层：通道没画面先看摄像头 RTSP 和讯思维通道状态；只有前端黑屏先看 `wsFlv` 地址、WebSocket 是否被代理或防火墙拦截、浏览器是否加载了 Jessibuca 的 `decoder.js` / `decoder.wasm`；六路以上卡顿优先看终端 CPU、浏览器 WebAssembly / SIMD 支持、是否开启音频、以及同屏实例是否正确销毁。

| 代码入口 | 说明 |
| --- | --- |
| `smart-doc-vault/service/env/camera_server.go` | 推流盒子服务，调用 `xsw` 客户端和 `global.XswGateway` |
| `smart-doc-vault/router/env/common.go` | `/cameraServer/*` 和 `/camera/getTwoStream` 路由 |
| `smart-doc-vault/model/system/camera.go` | 摄像头通道、RTSP、流地址和在线状态模型 |
| `fit-archive-ng/src/utils/jessiBucas.ts` | 前端 Jessibuca 播放器统一配置 |
| `fit-archive-ng/src/views/bigdatascreen/monitorBigScreen.vue` | 监控大屏多路 `wsFlv` 播放、重连和销毁逻辑 |
| `fit-archive-ng/src/views/bigdatascreen/componet/cencterIcon/IconCamera.vue` | 大屏图标点位里的摄像头播放逻辑 |

#### 门禁

门禁能力当前按海康 ISAPI / 网关口径维护，主要对接明眸人脸门禁一体机和海康网关能力。它不走 POE 设备树，后端以 `hik_isapi` 表保存服务地址、账号、密码、端口和库房位置，再通过 `HikIsapiGateway` 查询门禁状态、人员、人脸、卡、事件和远程开门。

网盘文档：[ISAPI开发指南\_明眸\_人脸门禁一体机\_2023\_07\_18w.pdf](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/ISAPI%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97_%E6%98%8E%E7%9C%B8_%E4%BA%BA%E8%84%B8%E9%97%A8%E7%A6%81%E4%B8%80%E4%BD%93%E6%9C%BA_2023_07_18w.pdf)

海康门禁历史上有两套实现口径：早期是单服务 / 单设备口径，当前是网关化的多设备口径。维护时优先看当前 `fdmjj` 分支的 `/accessControl/*`，只有追溯旧现场或旧分支时再看 `/door/*`。

| 阶段 | 实现口径 | 关键差异 | GitLab 线索 |
| --- | --- | --- | --- |
| 历史方案 | `DoorApi` + `global.HikService` + `/door/*` | 以系统设置里的海康地址、账号、密码初始化一个全局 ISAPI 客户端，更偏单门禁服务；旧路由包括 `/door/addPersonInfo`、`/door/controlDoor`、`/door/getAcsEvent` 等 | [zks/smart-doc-vault-hikgateway](https://gitlab.singzer.cn/zks/smart-doc-vault-hikgateway) |
| 当前方案 | `HikIsapiGateway` + `hik_isapi` 表 + `/accessControl/*` | 多海康设备 / 网关管理，服务配置落库，支持连接状态、长连接事件、人员、人脸、卡、事件、远程开门和大屏数据源 | [fit-archive/fdmjj/smart-doc-vault](https://gitlab.singzer.cn/fit-archive/fdmjj/smart-doc-vault) |

| 能力 | 当前口径 |
| --- | --- |
| 服务配置 | 维护海康设备 / 网关 IP、端口、账号、密码、名称和启用状态 |
| 在线状态 | 通过 `HikIsapiGateway` 判断连接状态和门禁状态 |
| 人员 / 人脸 / 卡 | 支持人员信息、人脸信息、卡信息的新增、修改、删除和查询 |
| 门禁事件 | 查询门禁事件、事件图片、事件数量和通行历史 |
| 门状态 / 远程开门 | 查询门状态，并通过 ISAPI / 网关执行远程开门 |
| 大屏展示 | 支持库房门禁、门禁信息统计、门禁信息列表等大屏卡片 |

| 代码入口 | 说明 |
| --- | --- |
| `smart-doc-vault/router/env/hik_isapi.go` | `/accessControl/*` 门禁路由 |
| `smart-doc-vault/service/env/hik_isapi.go` | 海康 ISAPI 业务服务 |
| `smart-doc-vault/model/system/hik_isapi.go` | `hik_isapi` 服务配置和运行状态模型 |
| `fit-archive-ng/src/api/ApiDevice/doorLock` | 前端门禁接口封装 |

### 虚拟设备

虚拟设备用于把软件状态、聚合状态或第三方设备数据放进 POE 设备体系。这里的重点不是“做一个新设备分类”，而是模拟 POE 设备的 MQTT 行为：软件进程直接发布 `information` / `warning`，订阅 `control`，让后端以为它面对的是一个真实网关或传感器。

这个方案适合对接第三方设备时使用。第三方设备如果已经有 TCP、Modbus、HTTP 或厂家 SDK，可以由一个软网关进程读取第三方数据，再翻译成飞度 POE MQTT JSON。这样可以绕过自研 POE 网关硬件和固件定制，减少现场定制硬件、烧录固件、调试串口协议的成本。

| GitLab 线索 | 用途 | 当前判断 |
| --- | --- | --- |
| [fit-archive/virtual-device-builder](https://gitlab.singzer.cn/fit-archive/virtual-device-builder) | 早期虚拟设备 / 模拟器，包含空气质量、温湿度、DI、DO、空调、漏水等模拟脚本 | 适合看消息格式和测试思路 |
| [IOT-FIRMWARE/virtual-device-builder-GUI](https://gitlab.singzer.cn/IOT-FIRMWARE/virtual-device-builder-GUI) | 虚拟设备 GUI 工具 | 适合现场演示或手动构造模拟数据 |
| [fit-archive/yd/soft-gateway](https://gitlab.singzer.cn/fit-archive/yd/soft-gateway) | 软网关实现，读取第三方设备数据后模拟 POE 设备上报 | 更接近第三方设备接入方案 |
| [fit-archive/yd/soft-gateway-new](https://gitlab.singzer.cn/fit-archive/yd/soft-gateway-new) | 新版软网关实现 | 新项目优先参考这个方向 |

#### 方案结构

| 层 | 说明 |
| --- | --- |
| 第三方设备侧 | 真实硬件仍按厂商协议工作，例如 Modbus TCP、串口转 TCP、HTTP API、SDK 等 |
| 软网关进程 | 读取第三方设备状态，转换字段、单位、状态码和控制命令 |
| POE MQTT 适配层 | 按飞度 POE 设备格式发布 `information` / `warning`，并订阅 `control` |
| 智档宝后端 | 继续使用原有 POE 设备逻辑创建设备、更新 Redis、写历史、触发报警和下发控制 |

#### 模拟对象

| 模拟对象 | 推荐模拟方式 | 说明 |
| --- | --- | --- |
| 独立空气质量传感器 | 模拟 `FEIDU_POE_AIR_SENSOR` | 最简单，直接上报 `get_sensor` |
| 网关 + 串口设备 | 模拟 `FEIDU_POE_GATEWAY_LITE` | 用 `serial` + `address` 映射第三方设备，生成子设备 |
| 16DI 输入 | 模拟 `FEIDU_POE_16DI_CONTROL` 或网关 DI | 可把第三方开关量、报警量映射成 `DI1`、`DIstatus1` |
| 8DO 输出 | 模拟 `FEIDU_POE_8DO_CONTROLLER` 或网关 DO | 订阅 `control` 后转成第三方继电器控制 |
| 自定义第三方设备 | 使用 `custom_*` command | 后端会按 `网关SN_serial_address` 同步数据，适合快速接入非标准设备 |

#### 接入原则

| 原则 | 说明 |
| --- | --- |
| SN 必须稳定 | 虚拟 MAC / SN 一旦上线就不要随意变化，否则后端会当成新设备 |
| 优先模拟已支持型号 | 能用 `FEIDU_POE_AIR_SENSOR`、`FEIDU_POE_GATEWAY_LITE`、16DI、8DO 就不要新增协议 |
| 保留 `serial` 和 `address` | 第三方多设备接入时，用这两个字段稳定映射子设备 |
| 控制必须闭环 | 软网关订阅 `control`，执行第三方控制后用同 `task_id` 回包 |
| 状态码要归一 | 厂商状态、寄存器位、单位换算应在软网关里处理，后端只看 POE 标准字段 |
| 故障也要上报 | 读取失败、离线、通信超时不要静默，至少更新在线状态或错误字段 |

| 类型 | 说明 |
| --- | --- |
| 状态聚合 | 把多个设备状态聚合成一个展示项 |
| 大屏卡片 | 给大屏或智能面板提供可配置的数据源 |
| 软件模拟 | 调试或演示时模拟设备上报、报警和控制结果 |
| 平台设备 | 第三方平台、3D 巡检或算法系统映射进来的设备对象 |

#### 软网关示例

以 `fit-archive/yd/soft-gateway` 为例，README 里的现场对象包括温湿度传感器、除湿机、空调控制器、漏水和人体开关量。代码结构上 `fit_device` 是飞度设备协议适配层，外层 `gateway1.py` 负责读第三方 Modbus / TCP 数据，再由 `main.py` 把数据发布到 MQTT。

```json
{
  "device_info": {
    "device_type": "FEIDU_POE_GATEWAY_LITE",
    "device_sn": "08f9e08b6801",
    "ip": "虚拟设备",
    "mac": "08:F9:E0:8B:68:01",
    "mqtt_server_host": "192.168.1.218",
    "mqtt_server_port": 1883,
    "clientID": "esp32-08f9e08b6801",
    "mqtt_status": true,
    "mqtt_config_st": "true"
  },
  "command": "get_device_temp_hum",
  "task_id": -1,
  "param": {
    "serial": "Serial3",
    "address": 1,
    "temperature": 22.8,
    "humidity": 52.3,
    "message": "success"
  }
}
```

这个消息发布到 `information` 后，后端会沿用 POE 网关子设备逻辑：主设备是 `08f9e08b6801`，子设备可以按 `08f9e08b6801_Serial3_1` 进入状态、历史曲线、报警和大屏展示。

### 无线设备

无线设备当前以 ChirpStack 作为主要代码口径。它解决的是“电池供电、低频上报、远距离覆盖”的环境传感器接入，不走 POE 主控 / 子设备树，也不按 POE 设备 1 分钟在线规则判断状态。后端设备模型通过 `sourceType = chirpstack` 区分无线来源，配置里 `dirty.deviceTimeout.byType.chirpstack` 当前是 `7200` 秒，默认兜底也是 2 小时。

| 关注点 | 说明 |
| --- | --- |
| 来源类型 | `fit` 是默认设备来源，`chirpstack` 表示无线设备来源 |
| 数据入口 | ChirpStack MQTT `application/#` 消息解析后创建或更新设备 |
| 状态判断 | 无线设备按最后上报时间和无线设备超时策略判断在线 |
| 典型数据 | 温湿度、电量、电压、RSSI、SNR、网关 ID、频道等 |

#### 接入链路

无线设备链路可以理解成两段：LoRaWAN 网络负责把传感器数据送到 ChirpStack，智档宝后端只消费 ChirpStack 转出的 MQTT JSON。

| 顺序 | 节点 | 作用 |
| --- | --- | --- |
| 1 | LoRaWAN 传感器 | 采集温湿度、光照、气体、电池等数据，并通过 LoRaWAN 上报 |
| 2 | LoRa 网关 | 接收传感器无线数据，按 UDP Packet Forwarder 或 Basic Station 协议转发 |
| 3 | ChirpStack Gateway Bridge | 把网关协议转换成 ChirpStack 使用的 MQTT topic |
| 4 | ChirpStack | 管理应用、设备、网关、设备配置和 uplink 解码 |
| 5 | Mosquitto / MQTT | 承载 ChirpStack integration 输出的 JSON 消息 |
| 6 | 智档宝后端 | 订阅 `application/#`，解析无线设备数据 |
| 7 | 设备表 / Redis | 写入 `source_type = chirpstack` 设备，并刷新当前状态 |

| 环节 | 当前口径 |
| --- | --- |
| 传感器 | ESP32 LoRaWAN 传感器固件上报 `object.sensor_type_name` 和业务数据 |
| 网关 | 支持 UDP Packet Forwarder 和 Basic Station，两种方式最终进入 Gateway Bridge |
| ChirpStack | 使用 v4，区域配置重点看 CN470 子频段 |
| MQTT | ChirpStack MQTT integration 输出 JSON，后端订阅 `application/#` |
| 后端 | `ChirpStackMqttMessageHandler` 解析消息，按 `devEui` 生成设备 SN |

#### 服务部署仓库

无线设备不是直接部署在主系统 compose 里，GitLab 上单独有服务部署 repo。现场如果要排查 LoRa 网关、CN470 频段、ChirpStack 页面或 MQTT 端口，优先看这个部署仓库。

| 仓库 | 用途 | 关键内容 | 当前口径 |
| --- | --- | --- | --- |
| [fit-archive/chirpstack-docker](https://gitlab.singzer.cn/fit-archive/chirpstack-docker) | ChirpStack 服务部署 | `docker-compose.yml`、ChirpStack 配置、Gateway Bridge 配置、Mosquitto 配置、PostgreSQL 初始化脚本、网关配置模板 | 当前无线设备服务部署参考 |
| [IOT-FIRMWARE/esp-32-lorawan-sensors](https://gitlab.singzer.cn/IOT-FIRMWARE/esp-32-lorawan-sensors) | LoRaWAN 传感器固件 | 传感器采集、LoRaWAN 上报、`sensor_type_name` payload 约定 | 当前无线传感器固件参考 |

| 服务 | 镜像 / 版本 | 端口 / 作用 |
| --- | --- | --- |
| `chirpstack` | `chirpstack/chirpstack:4.13.0` | Web / API `8080`，管理应用、设备、网关和设备配置 |
| `chirpstack-rest-api` | `chirpstack/chirpstack-rest-api:4.2.0` | REST API `8090`，部署 repo 保留但官方更推荐 gRPC |
| `chirpstack-gateway-bridge` | `chirpstack/chirpstack-gateway-bridge:4.0.11` | UDP Packet Forwarder `1700/udp` |
| `chirpstack-gateway-bridge-basicstation` | `chirpstack/chirpstack-gateway-bridge:4.0.11` | Basic Station `3001` |
| `chirpstack-gateway-bridge-cn470-*` | `chirpstack/chirpstack-gateway-bridge:4.0.11` | CN470 子频段 Basic Station，`3002` 到 `3013` |
| `mosquitto` | `eclipse-mosquitto:2` | MQTT `1884`，ChirpStack integration 和后端消费共用 |
| `postgres` | `postgres:14-alpine` | ChirpStack 元数据 |
| `redis` | `redis:7-alpine` | ChirpStack 缓存 / 队列 |

CN470 当前按 `cn470_0` 到 `cn470_11` 拆分。部署 repo 的 `GATEWAY_CONNECTION_SUMMARY.md` 里已经把 `3002-3013` 对应到各子频段，网关现场配置时要确认网关使用的子频段和 Basic Station 端口一致。

#### 数据解析

后端启动时只有在 `chirpstack.enable = true` 时才初始化无线链路：先连接 `chirpstack.mqttUrl`，再订阅 `application/#`，然后加载数据库里已有的 `source_type = chirpstack` 设备到内存映射。

| ChirpStack 字段 | 后端用途 |
| --- | --- |
| `deviceInfo.devEui` | 作为设备 SN |
| `deviceInfo.deviceName` | 作为设备原始名称；当有 `sensor_type_name` 时页面名称会改成传感器中文名 |
| `deviceInfo.deviceProfileName` | 作为兜底设备型号 |
| `object.sensor_type_name` | 当前优先作为设备型号，例如 `AHT30`、`ZE08B` |
| `object` | 作为设备状态数据写入 Redis / 页面当前状态 |
| `rxInfo[]` | 选 RSSI 最强的网关，把 `rssi`、`snr`、`gatewayId`、`channel` 注入到状态数据 |

`sensor_type_name = NONE` 和 `LTR390_COMBO` 当前会跳过处理。已存在设备如果型号变化，后端会删除旧设备后按新型号重建；所以现场调试固件时不要随意切换同一个 `devEui` 对应的传感器类型。

#### 设备类型

| `sensor_type_name` | 页面名称 | 上报重点 |
| --- | --- | --- |
| `LTR390_UV` | 紫外线传感器 | 紫外线指数、电池电压、电量、信号质量 |
| `LTR390_LUX` | 光照传感器 | 光照强度、电池电压、电量、信号质量 |
| `ZE08B` | 甲醛传感器 | 甲醛浓度、电池电压、电量、信号质量 |
| `AHT30` | 温湿度传感器 | 温度、湿度、电池电压、电量、信号质量 |
| `SGP30` | TVOC传感器 | TVOC、eCO2、电池电压、电量、信号质量 |
| `BMP30` | 大气压强传感器 | 气压、温度、电池电压、电量、信号质量 |
| `SGP30_ECO2_ONLY` | 二氧化碳传感器 | eCO2、电池电压、电量、信号质量 |
| `SGP30_TVOC_ONLY` | TVOC传感器 | TVOC、电池电压、电量、信号质量 |

#### 在线与排查

无线设备低频上报，不能用 POE 设备“短时间没消息就是离线”的判断方式。排查时按链路从下往上看，先确认无线网络，再看主系统。

| 顺序 | 检查项 | 判断方式 |
| --- | --- | --- |
| 1 | 传感器 | 上电、电池、电压、固件烧录、`devEui` 是否与 ChirpStack 设备一致 |
| 2 | LoRa 网关 | ChirpStack 网关页面是否 Online，`Last seen` 是否更新 |
| 3 | 频段 / 端口 | CN470 子频段、Basic Station 端口或 UDP `1700` 是否和网关配置一致 |
| 4 | ChirpStack uplink | ChirpStack 设备页面是否能看到 uplink 和 decoded object |
| 5 | MQTT | `mosquitto` 是否能看到 `application/#` JSON 消息 |
| 6 | 后端 | `chirpstack.mqttUrl` 是否指向部署 repo 的 MQTT 地址，debug WS 是否出现 `[ChirpStack]` 日志 |
| 7 | 主系统设备 | 设备表是否生成 `source_type = chirpstack`，Redis / 页面当前状态是否更新 |

## 业务类型

环境控制业务类型按“设备数据最终用来做什么”组织。设备类型解决接入对象，业务类型解决展示、分析、控制和告警。

| 业务类型 | 说明 |
| --- | --- |
| 3D 库房对接 | 把设备状态、点位和摄像头映射到库房三维空间 |
| 历史数据 | 保存和查询设备历史状态，用于趋势分析和现场复盘 |
| 自动控制 | 根据环境状态、时间策略或人工指令控制现场设备 |
| 报警中心 | 处理报警规则、报警联动、当前报警和报警历史 |

### 3D 库房对接

3D 库房对接关注“设备状态如何落到空间里”。它不是单独的传感器协议，而是把库房、设备点位、摄像头、环境控制状态和巡检视图组合起来。

| 能力 | 说明 |
| --- | --- |
| 库房 3D 图 | 维护库房 3D 图文件或模型入口 |
| 点位映射 | 将设备、摄像头、门禁或报警点映射到库房空间 |
| 3D 巡检 | 通过三维视图展示现场状态、异常点和巡检入口 |
| 状态叠加 | 把温湿度、空气质量、报警、摄像头等状态叠加到 3D 视图 |

### 历史数据

| 能力 | 说明 |
| --- | --- |
| 当前状态 | 展示设备在线、温湿度、空气质量、漏水、继电器、空调、除湿等状态 |
| 历史曲线 | 通用设备历史查询和导出，用于趋势分析和现场复盘 |
| 环境评分 | 按温湿度或空气质量历史数据计算环境评分 |
| 数据导出 | 将设备历史数据导出为表格，用于现场验收、问题复盘和汇报 |

### 自动控制

| 能力 | 说明 |
| --- | --- |
| 手动控制 | 支持除湿机、新风、DO 输出、空调学习、空调控制、通用命令下发 |
| 自动策略 | 按温湿度范围、自动空调策略或安防定时设防做联动 |

### 报警中心

| 能力 | 说明 |
| --- | --- |
| 报警规则 | 按设备型号、表达式、事件和参数定义报警规则 |
| 报警联动 | 输入设备触发后，可联动声光报警、短信、电话、弹窗和大屏提示 |
| 报警历史 | 记录触发、解除、确认、原始消息和处理详情 |
| 当前报警 | 展示当前仍在触发中的报警状态，支持解除弹窗、静音和缓存同步 |

## 历史发展

环境控制的历史重点不是功能名称变化，而是底层消息中间件、时序数据存储和监控播放方案都换过几轮。现在看到的 POE、UDP、MQTT、历史曲线、报警中心和库房监控，背后主要由三条技术线支撑：MQTT broker 负责设备消息，时序数据库负责环境和设备历史数据，监控播放链路负责把现场摄像头稳定显示到网页和大屏。

### MQTT Broker 演进

| 阶段 | 方案 | 典型仓库 / 线索 | 当前口径 |
| --- | --- | --- | --- |
| 早期 / 历史线 | `gmqtt` | [2024-new-screen/smart-doc-vault](https://gitlab.singzer.cn/fit-archive/2024-new-screen/smart-doc-vault)、[hzg/smart-doc-vault](https://gitlab.singzer.cn/fit-archive/hzg/smart-doc-vault) 中存在 `pkg/gmqtt` 和 `docker-compose.yml` 的 `gmqtt` 服务 | 历史方案，不作为新部署优先口径 |
| 过渡期 | 后端仍用 Paho MQTT client，保留少量 `GmqttAdminClient` 注释或历史代码 | [fdmjj/smart-doc-vault](https://gitlab.singzer.cn/fit-archive/fdmjj/smart-doc-vault) 的 `initialize/mqtt.go`、`iot/iot.go` | 业务代码关心 MQTT 协议，不应再依赖 gmqtt 管理接口 |
| 当前离线部署 | EMQX | [fdmjj/docker-install](https://gitlab.singzer.cn/fit-archive/fdmjj/docker-install) 使用 `emqx/emqx:5.3.2`，容器名 `sdv-emqx` | 当前推荐 broker，现场服务和端口按 EMQX 维护 |

当前文档里的 UDP / MQTT 分工也要按这个口径理解：UDP 是 POE 设备初始化配置通道，MQTT broker 是设备运行期消息通道。设备端不应该关心后端曾经用过哪个 broker；只要 MQTT 地址、端口、topic 和 payload 约定稳定，broker 可以从 gmqtt 切到 EMQX。

### 时序数据库演进

| 阶段 | 方案 | 典型仓库 / 线索 | 当前口径 |
| --- | --- | --- | --- |
| 早期探索 | QuestDB | 后端存在 `initialize/questdb.go`，旧 `docker-compose.yml` 暴露 `9000`、`9009`、`8812` 等 QuestDB 相关端口 | 历史残留，不作为新环境控制历史数据主线 |
| 中间尝试 | CeresDB | 后端配置里曾有 `ceresdb` 的 `host`、`http-port`、`grpc-port` 字段，系统信息接口也留过 CeresDB 查询注释 | 历史残留，不作为当前部署依赖 |
| 当前主线 | InfluxDB 2.x | [fdmjj/smart-doc-vault](https://gitlab.singzer.cn/fit-archive/fdmjj/smart-doc-vault) 启动 `initialize.InfluxDB()`，`iot/tsdb.go` 的通用写入使用 InfluxDB client；[fdmjj/docker-install](https://gitlab.singzer.cn/fit-archive/fdmjj/docker-install) 使用 `influxdb:2.7`，容器名 `sdv-influxdb` | 当前环境控制历史曲线、通用设备历史和导出能力的主线 |

当前时序数据写入的核心已经收敛到 InfluxDB：设备 MQTT 消息进入后端后，通用 TSDB 写入会从 `param` 中提取可序列化字段，写入 InfluxDB bucket。温湿度、空气质量、设备状态、环境评分和历史曲线都应按 InfluxDB 口径维护。

### 监控播放方案演进

监控播放方案的变化，主要是被“浏览器不能直接播放 RTSP”和“库房大屏需要六路以上同屏播放”两个问题推动的。早期更关注单路能打开，后面才逐步转向低延迟、多路、可重连和低 CPU 占用。

| 阶段 | 方案 | 典型线索 | 当前口径 |
| --- | --- | --- | --- |
| 早期单路预览 | RTSP / RTMP / HLS 地址直接暴露 | 后端和模型里一直保留 `rstp`、`rtmp`、`hls`、`httpTs` 等地址字段；推流盒子能同时生成多种播放地址 | 适合排查源流和兼容旧现场，但不是当前前端大屏主播放口径 |
| 文件 / 普通 FLV 尝试 | `flv.js` / `<video>` 播 FLV 或本地视频 | `fit-archive-ng/src/views/bigdatascreen/index.vue` 里有 `flvjs.createPlayer`、`enableWorker`、`enableStashBuffer` 等逻辑；依赖浏览器 MSE 和单个 video 元素 | 更像早期视频文件 / 单路 FLV 预览思路，六路以上同屏容易遇到性能和生命周期问题 |
| 推流盒子多协议输出 | 讯思维 `xsw` 把 RTSP 转成 HTTP-FLV、WS-FLV、RTMP、HLS、HTTP-TS | `CameraModel.AfterFind` 和大屏 WebSocket 会生成 `httpFlv`、`wsFlv`、`rtmp`、`hls`、`httpTs`、`rstp` | 当前仍保留这些地址，便于不同终端调试；前端主线取 `wsFlv` |
| 当前主线 | `ws-flv + Jessibuca + WASM / MSE / worker` | `fit-archive-ng/src/utils/jessiBucas.ts`、`monitorBigScreen.vue`、`IconCamera.vue` 使用 `cameraModel.wsFlv`、`Jessibuca.play()`、`useMSE`、`useSIMD`、`autoWasm`、`demuxUseWorker` | 当前库房监控大屏和多路预览主线，重点解决低延迟、六路以上同屏和异常重连 |

这条演进线里，`wsFlv` 不是“又多一个备用 URL”，而是当前前端监控播放的主入口。HLS 仍适合兼容性排查，但延迟通常不适合监控大屏；RTSP 仍是摄像头到推流盒子的源流，但浏览器不能直接播；普通 FLV / video 方案在单路预览时可用，多路同屏会更依赖实例管理和终端性能。

当前方案的关键是把压力拆开：推流盒子负责从摄像头拉 RTSP 并转出 WebSocket FLV，前端 Jessibuca 负责解封装和解码，`demuxUseWorker` 把解封装放到 worker，`autoWasm` 在浏览器解码能力不稳定时兜底，`hasAudio: false` 避免监控大屏为音频消耗额外 CPU。维护时如果看到旧分支里的 `flv.js`、`xgplayer-flv` 或 HLS 播放逻辑，要先判断它是在处理普通视频文件、旧大屏，还是当前监控通道。

### 维护判断原则

| 判断问题 | 当前建议 |
| --- | --- |
| 新部署 MQTT broker 怎么选 | 用 EMQX；文档、端口和容器名按 `sdv-emqx` 维护 |
| 看到 `gmqtt` 怎么处理 | 视为历史分支或旧部署线索；除非维护旧现场，不要在新文档里推荐 |
| 新部署时序库怎么选 | 用 InfluxDB 2.x；文档、备份和容器名按 `sdv-influxdb` 维护 |
| 看到 QuestDB / CeresDB 怎么处理 | 视为历史探索或残留配置；不要作为当前环境控制历史数据判断依据 |
| 新部署监控播放怎么选 | 前端按 `wsFlv + Jessibuca` 维护，确认 WebSocket FLV、WASM 解码资源、worker 和实例销毁逻辑 |
| 看到 HLS / RTMP / RTSP 怎么处理 | 视为推流盒子兼容地址或源流排查线索；当前网页多路监控不要默认按这些方案实现 |
| 看到 `flv.js` / `xgplayer-flv` 怎么处理 | 先判断是否普通视频文件或旧大屏逻辑；当前库房监控大屏主线看 Jessibuca |
| 设备在线看哪里 | 在线链路仍看 MQTT 连接和最近上报；broker 实现变更不改变设备业务协议 |
| 历史曲线看哪里 | 当前按 InfluxDB 查询和导出能力维护，重点关注 bucket、token、org、数据目录和备份 |
| 监控卡顿看哪里 | 先看推流盒子通道和 `wsFlv`，再看前端 Jessibuca 实例数量、WASM / SIMD 支持、CPU 和销毁重连逻辑 |

## 产品边界

* 环境控制关注库房环境、现场安全、设备状态、设备控制和报警联动，不负责档案业务状态本身。
* 环境控制数据可以进入大屏、3D 库房、告警和运维页面，但档案借阅、上架、盘点等业务规则仍由主系统承载。
* 具体协议、网关型号、设备地址、MQTT payload、Modbus 点位、厂商 SDK 放到系统架构或设备接入文档。
* RFID 读写、标签识别、手持机、盘点车不属于环境控制，放到 RFID 页面维护。

---

---
url: /wiki/sdv/digitization.md
---

# 数字化

数字化用于把纸质档案、附件和多媒体材料转成可上传、可预览、可检索、可长期保存的电子档案。它不是单纯“传一个文件”，而是从档案对象出发，把扫描件、Office、PDF、图片、音视频和批量挂接包纳入档案业务。

## 业务定位

数字化重点回答四个问题：

* 文件怎么进来：扫描件、图片、文档、音视频和批量压缩包如何上传或挂接到档案。
* 文件放在哪里：电子档案文件、预览源文件、索引文本和元数据分别由谁保存。
* 文件怎么用：用户如何预览、下载、重命名、删除和在档案详情里切换电子文件。
* 文件怎么搜：数字化文件名、档案信息和全文内容如何进入检索链路。

## 目录总览

| 目录 | 解决的问题 | 主要内容 |
| --- | --- | --- |
| 电子档案 | 文件和档案对象如何绑定 | 电子档案模型、档案详情入口、文件列表、重命名、删除、下载 |
| 文件采集 | 文件如何进入系统 | 单文件上传、分片上传、批量挂接、ZIP 模板、扫描件和附件管理 |
| 文件存储 | 文件如何保存和迁移 | Minio / 文件目录、bucket、路径规则、MD5、文件大小、备份迁移影响 |
| 文件预览 | 文件如何在线打开 | 图片、PDF、Office、OFD、音频、视频、不可预览文件和下载兜底 |
| 文件解析 | 文件如何转成可搜索文本 | Tika、文档文本提取、索引写入、解析失败处理 |
| 全文检索 | 用户如何查到资料 | 高级搜索、`target=text`、`target=electronic`、Elasticsearch 索引 |
| 权限控制 | 谁能看、下、改、删 | 数字化权限、文件预览、文件下载、重命名、删除、全文检索、数字化文件检索 |
| 研发参考 | 研发如何定位代码 | 前端组件、接口封装、后端路由、模型和任务入口 |
| 产品边界 | 哪些属于数字化，哪些不属于 | 档案业务、环境控制、RFID、打印、部署和存储边界 |

## 核心对象

| 对象 | 说明 |
| --- | --- |
| 档案 | 电子档案的业务归属对象；当前主线电子文件通常挂到档案 `archiveId` 下 |
| 电子档案 | `sys_electronic` 中的文件元数据，包含名称、类型、路径、大小、MD5、档案 ID |
| 文件分片 | `file_models`、`file_chunk_models` 记录分片上传状态、上传 ID、分片总数和 ETag |
| 对象文件 | Minio bucket 或本地文件服务中的真实文件内容 |
| 搜索文档 | Elasticsearch 中的 `electronic`、档案和装具索引数据 |
| 数字化权限 | 控制用户能否预览、下载、重命名、删除和检索电子档案 |

## 前端页面结构

数字化能力当前不是一个独立的完整业务模块页面，而是嵌在档案管理、详情预览、高级搜索和角色权限里。

| 入口 | 主要处理对象 | 前端目录 / 文件 |
| --- | --- | --- |
| 档案详情电子档案 | 单份档案下的电子文件列表、预览、下载、重命名、删除 | `fit-archive-ng/src/views/ArchivesManagement/overview/File/components/DetailsFile.vue` |
| 电子档案资源管理 | 档案详情里的文件树、移动、重命名、批量操作 | `fit-archive-ng/src/views/ArchivesManagement/overview/File/components/fileManagement` |
| 批量导入 / 挂接 | 实体档案导入、电子档案批量挂接、分片上传、ZIP 模板 | `fit-archive-ng/src/views/ArchivesManagement/overview/File/components/fileImport` |
| 文件预览组件 | 图片、PDF、Office、OFD、音视频预览和下载 | `fit-archive-ng/src/components/previewFile` |
| 高级搜索 | 数字化档案、全文检索、结果预览 | `fit-archive-ng/src/components/seniorSearch` |
| 数字化权限 | 角色授权中的预览、下载、重命名、删除、全文搜索、数字化搜索 | `fit-archive-ng/src/views/SystemManagement/roleMan/components/TreeList.ts` |
| API 封装 | 上传分片、完成上传、电子档案列表、重命名、删除、下载 | `fit-archive-ng/src/api/ApiFileManagement/index.ts` |

写产品说明时要把“档案主数据”和“电子档案文件”分开：档案是业务对象，电子档案是挂在档案下面的文件对象。一个档案可以有多个电子文件，文件名、类型、路径、大小、MD5 和预览能力都属于数字化链路。

## 核心链路

```text
实体资料 / 扫描件 / 办公文档 / 音视频
  ↓
单文件上传 / 分片上传 / ZIP 批量挂接
  ↓
Minio / 文件目录保存对象文件
  ↓
sys_electronic 保存电子档案元数据
  ↓
预览组件按文件类型选择打开方式
  ↓
Tika 提取文本，Elasticsearch 建索引
  ↓
高级搜索和全文检索返回档案 / 电子档案结果
```

这条链路里，任何一段失败都会表现成不同问题：上传失败通常看后端和对象存储；文件打不开看预览和路径；能预览但搜不到看 Tika 和 Elasticsearch；搜索结果能出来但无法预览，通常要回头查电子档案路径、权限和 Minio 文件。

## 电子档案

电子档案是数字化的核心业务对象。后端模型 `ElectronicModel` 对应表 `sys_electronic`，它只保存文件元数据和档案关联，不直接保存文件二进制内容。

| 字段 | 产品含义 |
| --- | --- |
| `name` | 电子档案文件名 |
| `type` | 文件类型，当前模型口径包括文档、图片、视频、音频、其他 |
| `path` | 文件在对象存储 / 文件服务中的路径 |
| `size` / `sizeStr` | 文件大小和展示用大小 |
| `archiveId` | 归属档案 ID |
| `md5` | 文件内容摘要，用于识别文件和上传链路 |
| `approval` | 电子档案可被借阅审批关联 |

### 文件操作

| 操作 | 产品说明 | 典型接口 / 入口 |
| --- | --- | --- |
| 查看列表 | 在档案详情或搜索结果中加载电子档案列表 | `/electronic/getElectronicList`，前端 `getElectronicList` |
| 预览 | 按文件类型打开预览组件 | `/electronic/preview`、`/minio/preview`、`/oo/preview` |
| 下载 | 直接下载单个文件或打包下载多个文件 | `/minio/download`、`/minio/downloadMap` |
| 重命名 / 移动 | 修改文件名或文件路径 | `/electronic/rename` |
| 删除 | 删除电子档案记录和对应索引 | `/electronic/deleteElectronicArchives` |

部分接口在后端服务方法和前端封装中保留，具体现场是否注册到路由，要以当前版本 `router/system/electronic.go` 和发布包为准。

## 文件采集

文件采集包含日常上传和批量挂接两类场景。日常上传面向档案详情里的少量附件；批量挂接面向已有档案和大量扫描件的对应关系。

### 上传方式

| 方式 | 场景 | 当前代码口径 |
| --- | --- | --- |
| 普通上传 | 小文件、少量附件、系统图片类资源 | `/minio/upload` |
| 电子档案创建 | 直接把文件挂到指定档案 | `/electronic/createElectronicArchive` |
| 分片上传 | 大文件或批量导入中避免一次性上传失败 | `/electronic/getUploadChunkID`、`/electronic/uploadPart`、`/electronic/completeChunkUpload` |
| ZIP 批量挂接 | 先下载模板包，再把电子档案压缩包上传解析 | `/electronic/createArchiveZip`、`/electronic/parseArchiveZip`、ZIP 分片上传接口 |

前端批量挂接入口在 `fileImport` 下，代码里会先计算文件信息和 MD5，再走分片上传，最后完成合并。这个链路更适合大量扫描件，不适合人工逐个点开档案上传。

### 路径规则

电子档案路径通常和档案 ID 绑定，例如后端索引任务里会按 `archive/<archiveId>/` 去掉前缀后展示相对路径。写导入模板或迁移脚本时，不要只保存文件名，必须保留归属档案、对象存储路径和电子档案记录之间的关系。

## 文件存储

数字化文件最终落到 Minio / 文件目录，数据库只保存元数据。备份迁移时必须同时处理数据库和对象文件，否则会出现“档案能查到，附件打不开”的问题。

| 层 | 保存内容 | 维护重点 |
| --- | --- | --- |
| 数据库 | `sys_electronic`、上传分片表、档案关联关系 | 记录完整性、软删除、MD5、路径一致性 |
| Minio / 文件目录 | 原始文件、预览源文件、下载文件 | bucket、目录、对象路径、磁盘空间、备份恢复 |
| 文件映射 | 大文件打包下载或临时下载映射 | 下载 UUID、过期清理、路径是否可访问 |
| 搜索索引 | 文件名、相对路径、类型、大小、全文内容 | Elasticsearch 索引是否同步 |

对象文件不要脱离数据库单独移动。文件路径如果变化，预览、下载、全文索引和借阅审批关联都会受到影响。

## 文件预览

前端 `previewFile` 组件根据文件扩展名选择预览方式。无法识别或无法在线打开的文件，应回退到下载。

| 类型 | 支持格式口径 | 预览方式 |
| --- | --- | --- |
| 图片 | `jpg`、`jpeg`、`png`、`bmp`、`webp`、`ico`、`jfif`、`gif` | 前端图片预览 |
| PDF | `pdf` | `pdfJS/web/viewer.html` |
| Office / 文档 | `doc`、`docx`、`xls`、`xlsx`、`ppt`、`pptx`、`txt`、`rtf`、`csv`、`odt`、`epub` 等 | `/oo/preview` 转到 7001 文档预览前端 |
| OFD | `ofd` | OFD 预览分支 |
| 音频 | `wav`、`mp3`、`aac`、`opus`、`flac`、`ogg` | 浏览器音频播放 |
| 视频 | `3gp`、`mp4`、`mov`、`mkv`、`webm`、`ogv` | 浏览器视频播放 |
| 其他 | 压缩包、未知格式、无法解析格式 | 显示不支持在线预览，提供下载 |

Office 预览链路当前保留 `/oo/preview` 兼容入口，后端会解析预览文件并跳转到 7001 文档预览前端。这个预览前端来自独立 GitLab 仓库 `fit-archive/onlyoffice-web-local`，构建产物会被集成进后端 `smart-doc-vault/frontend/onlyoffice`，再通过后端 `go:embed frontend/onlyoffice` 以静态站点方式发布。它不是旧的 OnlyOffice Document Server 直连模式，当前预览页内部包含 PDF / OFD / Office 渲染能力，并使用 X2T WASM 等浏览器端能力处理文档。

| 预览组成 | 当前口径 | 代码 / 配置线索 |
| --- | --- | --- |
| 预览前端仓库 | 独立项目 `fit-archive/onlyoffice-web-local` | `https://gitlab.singzer.cn/fit-archive/onlyoffice-web-local` |
| 后端集成位置 | 预览前端构建后放入后端嵌入目录 | `smart-doc-vault/frontend/onlyoffice`、`go:embed frontend/onlyoffice` |
| 默认端口 | `7001` | `document-convert.preview.port`，默认值兜底为 `7001` |
| 转换服务 | `sdv-document-convert` / `document-convert` | 默认服务地址 `http://127.0.0.1:7010` |
| WASM 资源 | 浏览器端文档转换 / 渲染资源 | `frontend/onlyoffice/wasm/x2t/x2t.wasm`、`x2t.js` |

现场如果 Office 文件打不开，要同时检查后端 `/oo/preview`、`document-convert` 配置、7001 预览端口、7010 转换服务、Minio 文件访问地址、WASM 静态资源 MIME 类型和浏览器网络请求。7001 端口打不开时，不要只查主后端 8888；要看后端是否启动了 Office preview web server，以及 `document-convert.preview.port` 是否被改过。

## 文件解析

文件解析用于把电子档案内容转成可搜索文本。后端 `ElectronicMinioToElastic` 会从 Minio 读取电子档案对象，调用 Tika 提取 `text/plain`，再把清洗后的内容写入 Elasticsearch `electronic` 索引。

| 环节 | 说明 |
| --- | --- |
| 读取文件 | 从 Minio bucket 按 `sys_electronic.path` 取对象 |
| 文本提取 | Tika 解析文档内容，返回纯文本流 |
| 内容清洗 | 当前代码会去掉空白字符，再写入 `content` |
| 索引写入 | 文档 ID 使用 `electronic-<电子档案ID>`，索引名为 `electronic` |
| 统计累计 | 解析文本长度会累计到 `setting.total_num` |

解析链路只保证“可提取文本的文件”进入全文检索。图片扫描件如果没有 OCR 结果，Tika 不能自动把图片里的文字变成全文内容；这类需求要单独接 OCR 或在扫描流程里生成可搜索 PDF。

## 全文检索

当前主线检索使用 Elasticsearch。系统启动后会有任务把档案、档案盒、电子档案同步到索引；后端还提供 `/all/syncElastic` 手动触发全量同步。

| 搜索目标 | 产品含义 | 典型入口 |
| --- | --- | --- |
| `target=text` | 全文检索，关注文件内容和档案文本 | 高级搜索“全文检索” |
| `target=electronic` | 数字化文件检索，关注电子档案文件名、路径、类型等 | 高级搜索“数字化档案 / 数字化文件检索” |
| 档案 / 装具索引 | 检索档案主数据和装具信息 | 高级搜索综合结果 |

全文搜索搜不到时，先区分是“索引里没有电子档案记录”，还是“电子档案有记录但没有 `content`”。前者看 `ElectronicToElastic` 和索引同步，后者看 Tika、Minio 文件读取和 `ElectronicMinioToElastic`。

当前 Elasticsearch 不是只启动一个 `9200` 服务就结束，还依赖 IK 插件和 `electronic` 索引 mapping 初始化。Linux Docker 离线包里由 `docker-install` 的 `es-chown` 容器把 `elasticsearch-analysis-ik-8.7.0.zip` 解压到 Elasticsearch 插件目录，再由 `es-init` 容器执行 `elastic_init.sh` 初始化 `electronic` 索引。Go 后端 `InitElasticsearch()` 只负责连接 Elasticsearch 客户端和清理分片上传表，不负责安装 IK 插件，也不负责创建 `electronic` mapping。

| 初始化项 | 当前做法 | 作用 |
| --- | --- | --- |
| IK 插件 | `elasticsearch-analysis-ik-8.7.0.zip` 解压到 `plugins/analysis-ik` | 支持中文分词 |
| `electronic` mapping | `elastic_init.sh` 执行 `PUT /electronic` | 建立电子档案全文索引结构 |
| 正文字段 | `content` 使用 `ik_smart` 作为 `analyzer` 和 `search_analyzer` | 支持中文全文检索和高亮 |
| 文件辅助字段 | `name`、`locationName`、`path` 使用 `wildcard` | 偏文件名、位置、路径匹配 |
| 高亮设置 | `index.highlight.max_analyzed_offset = 5000000` | 允许较长文本做高亮片段 |
| 执行容器 | `sdv-es-init` 等 Elasticsearch healthy 后执行脚本 | 确保初始化发生在 ES 可用之后 |

如果中文全文检索效果异常，优先确认三件事：`analysis-ik` 插件目录是否存在，`electronic` 索引 mapping 里 `content` 是否是 `ik_smart`，以及 `sdv-es-init` 是否成功执行过。只看 Elasticsearch 容器存活，不能证明全文检索已经初始化完成。

## 权限控制

数字化权限是角色权限的一部分，前端 `digitalTalk` 里已经按能力拆分。

| 权限 | 控制内容 | 后端权限种子 |
| --- | --- | --- |
| 文件预览 | 是否能打开电子档案预览 | `/electronic/preview`，名称 `预览` |
| 文件下载 | 是否能下载电子档案 | `/minio/download`，名称 `下载` |
| 重命名 | 是否能改电子档案名称或路径 | `/electronic/rename`，名称 `重命名` |
| 删除 | 是否能删除电子档案；当前权限种子保留，具体路由注册以发布版本为准 | `/electronic/deleteElectronicArchives`，名称 `删除` |
| 全文检索 | 是否能按全文内容搜索 | `/all/elSearch?target=text`，名称 `全文搜索` |
| 数字化文件检索 | 是否能按电子档案文件维度搜索 | `/all/elSearch?target=electronic`，名称 `数字化` |

权限说明要和用户视角保持一致：能看到档案，不代表一定能预览或下载电子档案；能预览，也不代表能删除、重命名或全文检索。

搜索接口存在历史大小写口径：权限种子和前端当前使用 `/all/elSearch`，Swagger / `router/system/elastic.go` 里也能看到小写 `/all/elsearch`。现场排查时优先看当前发布包实际注册的路由和中间件。

## 关联基础设施

| 基础设施 | 在数字化中的作用 | 常见问题 |
| --- | --- | --- |
| Minio / 文件目录 | 保存电子档案文件、预览源文件和附件 | 文件不存在、bucket 错误、路径不一致、磁盘满 |
| Tika | 提取 Office、PDF 等文档文本 | 服务未启动、文件格式不支持、解析超时 |
| Elasticsearch | 保存档案、装具、电子档案和全文索引 | IK 插件缺失、`electronic` mapping 未初始化、索引缺失、同步失败、中文检索效果不符合预期 |
| 文档预览前端 | Office、PDF、OFD 等文档在线预览 | 7001 端口、WASM 资源、Minio URL、转换后文件不可访问 |
| 数据库 | 保存电子档案元数据、权限和分片状态 | 记录和对象文件不一致 |
| 后端服务 | 上传、鉴权、预览、解析、下载和搜索接口 | 路由注册、权限、token、反向代理路径 |

## 历史发展

数字化的历史重点主要在三条技术线上：Office 预览方案、文档解析方案和搜索引擎方案。现在代码里会同时看到 OnlyOffice、`/oo/preview`、Tika、Meilisearch、RedisSearch、Elasticsearch、`document-convert` 等名字，维护时要先判断它们属于当前主线、兼容入口还是历史残留。

### Office 预览方案演进

| 阶段 | 方案 | 典型线索 | 当前口径 |
| --- | --- | --- | --- |
| 早期 / 历史线 | 直接对接 OnlyOffice Document Server | 旧主线 `smart-doc-vault` 有 `onlyoffice` 配置、`OnlyOfficeService`、`InitOnlyOfficeRouter`，前端通过 `/oo/preview` 传入文件 URL、文件名和 token | 历史方案；维护旧现场时仍可能遇到 |
| 兼容过渡 | 保留 `/oo/preview` 入口 | 当前前端 `previewFile` 仍把 Office / 文档类文件交给 `/oo/preview`，后端 `office_preview.go` 负责解析旧 `data` 参数 | 兼容入口，不代表后端仍直接使用旧 OnlyOffice 逻辑 |
| 当前主线 | 独立预览前端 + `document-convert` 转换服务 | `fit-archive/onlyoffice-web-local` 构建为预览前端，后端嵌入 `frontend/onlyoffice` 并默认用 7001 发布；`document-convert` 负责转换缓存，默认 7010 | 新部署优先按当前预览前端、WASM 资源和转换服务维护 |

当前主线的思路是：旧格式 Office 文件先按需要转换成更适合预览的格式，再把转换后的文件缓存到 Minio，最后跳转到 7001 预览前端。`doc`、`odt`、`rtf` 会转成 `docx`，`xls`、`ods` 会转成 `xlsx`，`ppt`、`odp` 会转成 `pptx`。预览前端自身来自 `onlyoffice-web-local`，其中包含 X2T WASM、PDF worker、OFD 渲染和静态字体资源；后端负责把这些静态资源作为嵌入文件系统发布。所以 Office 预览失败时，不只看浏览器页面，还要看转换服务、Minio 缓存目录、7001 预览端口、WASM 资源加载和 `/oo/preview` 兼容入口。

### 文档解析方案演进

| 阶段 | 方案 | 典型线索 | 当前口径 |
| --- | --- | --- | --- |
| 文件名 / 元数据检索 | 只把电子档案名称、路径、类型、大小等写入索引 | `ElectronicToElastic` 写入 `name`、`path`、`type`、`size`、`genres`、`targetId` | 适合数字化文件检索，但不等于全文检索 |
| Tika 文本解析 | 从 Minio 读取电子档案对象，调用 Tika 提取纯文本 | 旧主线和当前主线都有 `InitTika`、`TikaClient`、`ParseReaderWithHeader`、`ElectronicMinioToElastic` | 当前全文内容解析主线 |
| OCR / 可搜索扫描件 | 需要扫描流程或额外 OCR 生成文字层 | 当前文档解析代码主要处理可提取文本的文档，不会自动识别普通图片里的文字 | 不是当前通用主线，需要项目单独接入 |

这里要区分“预览”和“解析”：文件能预览，只说明浏览器或预览服务能打开它；全文能搜到，说明内容已经被 Tika 或其他解析链路提取并写进搜索索引。扫描图片如果没有 OCR，通常只能按文件名、路径或档案元数据检索，不能按图片里的文字检索。

### 搜索引擎方案演进

| 阶段 | 方案 | 典型线索 | 当前口径 |
| --- | --- | --- | --- |
| 早期搜索 | Meilisearch | 旧主线存在 `meilisearch` 配置、`initialize/meilisearch.go`、`MeiliSearchApi`、`UpdateMeiliSearch`、`MinioToMeilisearch` | 历史方案，不作为新部署优先口径 |
| 中间尝试 | RedisSearch / RediSearch | 旧分支有 `initialize/redisearch.go`，使用 `github.com/RediSearch/redisearch-go`，创建 `electronic` 索引并维护 `text`、`name`、`locationName`、`genres`、`status`、`securityLevel`、`path` 等字段 | 历史方案，不作为当前部署依赖 |
| 过渡期 | Meilisearch / RedisSearch 代码残留 + Elasticsearch 接入 | 多个版本线里还能看到 `BoxToMeiliSearch`、`ArchiveToMeilisearch` 注释，以及 `ElasticService.Search` 中的 RediSearch 查询实现；同时已经初始化 Elasticsearch 和 Tika | 维护时不要被函数名或文件名误导，要看实际启动任务和路由 |
| 当前主线 | Elasticsearch + IK 插件 + `electronic` mapping 初始化 | 当前 `fdmjj` 启动任务执行 `FileToElastic`、`ArchiveToElastic`、`BoxToElastic`、`ElectronicToElastic`，接口是 `/all/elSearch` / `/all/elsearch`；部署脚本通过 `elasticsearch-analysis-ik-8.7.0.zip` 和 `elastic_init.sh` 初始化中文全文索引 | 当前全文检索和数字化文件检索主线 |

当前搜索索引不只服务电子档案，还同时承载档案、档案装具和电子档案。`target=electronic` 更偏文件名、路径和电子档案元数据；`target=text` 更偏全文内容。现场排查时先确认 Elasticsearch 是否可用，再看同步任务是否跑过，最后区分是电子档案元数据没进索引，还是 Tika 没把正文写入 `content`。

### 维护判断原则

| 判断问题 | 当前建议 |
| --- | --- |
| 新部署 Office 预览怎么选 | 按 `onlyoffice-web-local` 预览前端、7001 端口、WASM 静态资源和 `document-convert` 维护；`/oo/preview` 只是兼容入口 |
| 看到 OnlyOffice 怎么处理 | 先判断是否旧现场或历史分支；新文档不要默认推荐旧 OnlyOffice 直连方案 |
| 全文解析依赖什么 | 当前按 Tika 维护；图片扫描件文字识别要另接 OCR 或可搜索 PDF 流程 |
| 新部署搜索引擎怎么选 | 按 Elasticsearch + IK 插件 + `electronic` mapping 初始化维护 |
| 看到 Meilisearch 怎么处理 | 视为历史方案或代码残留；除非维护旧现场，不作为当前主线判断依据 |
| 看到 RedisSearch / RediSearch 怎么处理 | 视为中间尝试或旧分支残留；当前主线不要再按 Redis 模块排查全文检索 |
| 搜索搜不到怎么查 | 先看 Elasticsearch 和 IK / mapping 初始化，再看同步任务，再看 Tika 解析和 `sys_electronic.path` 对应的 Minio 文件 |

## 研发参考

| 代码位置 | 视角 | 说明 |
| --- | --- | --- |
| `fit-archive-ng/src/components/previewFile` | 前端预览 | 文件类型判断、Blob URL、PDF / Office / 音视频预览 |
| `fit-archive-ng/src/api/ApiFileManagement/index.ts` | 前端接口 | 分片上传、电子档案列表、重命名、删除、下载 |
| `fit-archive-ng/src/components/seniorSearch` | 前端搜索 | 全文检索、数字化档案结果、预览入口 |
| `fit-archive-ng/src/views/ArchivesManagement/overview/File/components/fileImport` | 批量导入 | 电子档案批量挂接、ZIP 模板和分片上传 |
| `smart-doc-vault/model/system/electronic.go` | 数据模型 | `sys_electronic`、电子档案类型、档案关联 |
| `smart-doc-vault/model/system/file.go` | 上传模型 | 分片上传记录、分片 ETag、上传状态 |
| `smart-doc-vault/api/system/electronic.go` | 后端 API | 电子档案创建、列表、分片上传、ZIP 导入、重命名、删除 |
| `smart-doc-vault/api/system/minio.go` | 文件服务 API | 上传、预览、下载、文件映射 |
| `smart-doc-vault/task/electronic_to_elastic.go` | 索引任务 | 电子档案索引、Minio 文件解析、Tika 到 Elasticsearch |
| `smart-doc-vault/task/electronic_role.go` | 权限初始化 | 数字化权限种子数据 |
| `smart-doc-vault/frontend/onlyoffice` | 文档预览前端产物 | 来自 `fit-archive/onlyoffice-web-local`，被后端嵌入并通过 7001 发布 |
| `docker-install/elastic_init.sh` | Elasticsearch 初始化 | 创建 `electronic` 索引、设置 IK 分词和高亮参数 |

## 产品边界

* 数字化关注文件从采集、上传、保存、预览、解析到检索的完整链路。
* 档案分类、档案状态、借阅、上架、盘点和回转柜状态归入档案管理。
* Minio、Tika、Elasticsearch、文档预览服务的部署、端口和备份细节放到系统架构、打包分发和备份迁移。
* RFID 标签、读写器、盘点设备不属于数字化；即使 RFID 结果能定位档案，电子文件仍按数字化链路维护。
* 打印标签、借阅单、移交单不属于数字化；它们属于档案管理里的打印能力。

---

---
url: /wiki/sdv/rfid.md
---

# RFID

RFID 是智档宝面向实物档案识别和现场操作的能力板块。截至目前仍在开发中，文档需要持续标记已稳定能力、正在开发能力和项目定制差异。

## 业务定位

RFID 解决“实物档案如何被自动识别、快速盘点、出入库校验和现场定位”的问题。它和档案管理强相关，但产品边界更偏向标签、读写设备和现场识别流程。

RFID 不是单独替代档案管理的业务状态。它更像一层现场识别能力：系统先知道“应该有哪些档案、应该在哪里、处于什么流程”，RFID 再用设备读取结果去校验“现场实际读到了什么、读到的位置是否合理、是否需要人工处理异常”。

## 主要能力

| 能力 | 产品说明 |
| --- | --- |
| RFID 标签 | 将档案实物与 RFID 标签绑定 |
| 标签打印 | 通过 RFID 打印机制作可识别的档案标签 |
| 门口机 | 支持出入库识别、通行识别或现场操作入口 |
| 手持机 | 支持移动盘点、查找、扫码、现场操作 |
| 盘点车 | 面向批量盘点和现场巡检 |
| 馆员工作站 | 面向馆员柜台、桌面读写器、标签绑定、标签复核和异常处理 |
| RFID 服务 | 负责读写器、标签、设备事件和主系统之间的衔接 |
| 设备事件 | 接收读写器上报事件，并转换成可被业务处理的数据 |

## 核心对象

| 对象 | 产品说明 |
| --- | --- |
| 档案 / 档案装具 | RFID 最终要识别的业务对象，可以是单份档案，也可以是档案盒、档案袋、档案箱等装具 |
| RFID 标签 | 粘贴或附着在实物上的电子标签，承载可被读写器读取的标识 |
| TID | 标签芯片的唯一识别信息，通常由芯片固化，适合用于防重复和标签校验 |
| EPC | 业务侧可写入或规划的标签编码，适合和档案编号、装具编号、系统唯一编号建立映射 |
| 读写器 | 负责读取或写入标签的硬件设备，可以内置在门口机、手持机、盘点车或桌面写卡设备中 |
| 设备事件 | 读写器读到标签、写入成功、写入失败、设备离线、盘点完成等现场事件 |
| 盘点结果 | 系统应在库清单和 RFID 实际读取结果比对后的结果，通常用于提示正常、盘盈、盘亏和异常 |

写业务文档时，建议把 `TID` 和 `EPC` 分开描述。`TID` 更偏“标签本身是谁”，`EPC` 更偏“系统希望这个标签代表谁”。如果只写“RFID 编码”，后续很容易混淆标签芯片、业务编码和打印内容。

## 与档案管理的联动

| 场景 | 联动方式 |
| --- | --- |
| 标签绑定 | 将档案业务对象和 RFID 标签编号建立关系 |
| 入库 / 出库 | 通过设备识别结果辅助确认档案流转 |
| 盘点 | 将设备识别结果和系统应在库清单进行比对 |
| 查找 | 通过手持机或现场设备辅助定位档案 |
| 异常处理 | 识别未授权移动、漏盘、错位等异常情况 |

### 联动原则

* 档案管理负责业务对象、库位、借阅、归还、上架和盘点任务。
* RFID 负责现场识别、标签读写、设备事件和结果比对。
* RFID 读取结果不能默认直接改变档案业务状态，应该先形成待确认结果或处理建议。
* 对于回转柜这类强依赖盘点结果展示状态的场景，也要保留“业务状态”和“盘点在位状态”的区别。

## 典型流程

### 标签制作与绑定

标签制作解决“这张标签代表哪份档案或哪个装具”的问题。通常流程是先确定业务对象，再打印或写入标签，最后把标签读取结果和业务对象绑定。

```text
选择档案 / 装具
  ↓
生成标签内容
  ↓
打印纸面信息
  ↓
读取 TID / 写入 EPC
  ↓
绑定档案 / 装具
  ↓
现场复核
```

| 步骤 | 产品关注点 |
| --- | --- |
| 选择对象 | 明确是给档案贴标，还是给档案盒、袋、箱等装具贴标 |
| 生成内容 | 标签上展示的文字、条码、二维码和 RFID 写入内容要有统一模板 |
| 读写标签 | 需要区分读取 TID、写入 EPC、打印纸面标签三个动作 |
| 绑定关系 | 一张标签不应同时绑定多个有效对象；换标、重打、作废要保留记录 |
| 现场复核 | 打印完成后应能再次读取标签，确认标签和系统对象一致 |

### 盘点

盘点解决“系统记录和现场实物是否一致”的问题。RFID 盘点通常不是为了生成一份新清单，而是把现场读取结果和系统应在库清单做差异比对。

```text
创建盘点任务
  ↓
确定盘点范围
  ↓
现场设备读取标签
  ↓
上传读取结果
  ↓
系统比对应在库清单
  ↓
生成差异
  ↓
人工确认处理
```

| 盘点结果 | 产品含义 | 建议处理 |
| --- | --- | --- |
| 正常 | 应在库且现场读到，位置或范围匹配 | 保持当前状态，记录盘点时间 |
| 盘盈 | 现场读到，但不在本次应盘清单中 | 确认是否错放、范围配置错误、未建档或未绑定位置 |
| 盘亏 | 应在库但现场未读到 | 确认漏读、遮挡、借出未登记、错放或遗失 |
| 异常 | 标签重复、绑定缺失、设备上报错误或数据不完整 | 进入异常处理，不直接改业务状态 |
| 设备异常 | 设备离线、读写失败、任务中断 | 先处理设备问题，再重新执行或补盘 |

RFID 盘点需要允许现场存在漏读和误读。产品上不要把“未读到”直接等同于“遗失”，也不要把“读到未知标签”直接等同于“新增档案”。这些结果应进入差异处理，由业务人员确认后再改变档案状态、位置或绑定关系。

### 出入库识别

出入库识别用于在档案离开或进入库房、柜体、门口机区域时做校验。它适合做提醒和确认，不适合单独承担完整审批流程。

| 场景 | RFID 作用 | 档案管理作用 |
| --- | --- | --- |
| 借阅取档 | 识别现场取走的档案是否和借阅单一致 | 判断审批是否通过、借阅人是否有权限、是否允许取走 |
| 归还入库 | 识别归还档案是否为本次应归还对象 | 更新归还、待上架或在库状态 |
| 门口通行 | 识别经过门口机的标签，提示未授权带出 | 判断是否存在有效借阅、出库或移交流程 |
| 错拿提醒 | 读到非本次任务对象时提示 | 记录异常并指导人工处理 |

## 设备角色

不同 RFID 设备承担的产品角色不同，不能只按“都能读标签”合并描述。

| 设备 | 主要场景 | 产品重点 |
| --- | --- | --- |
| RFID 打印机 | 标签打印、TID 读取、EPC 写入、贴标复核 | 模板、耗材、打印质量、写入成功率、重打和作废 |
| 馆员工作站 | 建档、绑标、批量校验、柜台操作、异常处理 | 桌面读写器接入、单标签稳定识别、避免串读、操作反馈清晰 |
| 门口机 | 出入库识别、未授权带出提醒、现场入口 | 通行事件、借阅校验、异常提示和记录 |
| 手持机 | 移动盘点、查找、现场核对 | 任务下载、离线能力、扫描反馈、结果上传 |
| 盘点车 | 大范围批量盘点、库区巡检 | 批量读取、路径记录、任务进度、差异汇总 |
| 固定读写器 | 柜体、通道或指定区域持续识别 | 设备在线状态、读取范围、重复读取合并 |

### 终端与设备形态

当前 RFID 能力至少要按五类终端和设备形态维护，不建议只写成“读写器接入”。

| 终端 | 面向用户 | 主要能力 | 当前代码线索 |
| --- | --- | --- | --- |
| RFID 打印机 | 馆员、标签制作人员 | RFID 标签打印、TID 读取、EPC 写入、打印后复核、重打和作废 | `rfid-printer-node`，档案管理中已有 RFID 打印配置和本地打印服务口径 |
| 盘点车 | 档案管理员、实施盘点人员 | 大范围批量扫描、快速创建盘点、天线策略、误扫处理、差异提交 | `fit-archive-ng` 中已有 `盘点车工作台`，后端有盘点车菜单迁移 |
| 馆员工作站 | 馆员、柜台操作人员 | 桌面读写器调试、标签绑定、标签复核、异常标签处理、馆员侧连续识读 | `fit-archive-ng` 中有工作站模式、馆员工作站调试和 USB / 外置读写器配置 |
| 手持机 | 移动盘点人员、现场查找人员 | 手持盘点、档案标签绑定 / 换绑 / 解绑、层架标签绑定、未知标签处理、离线或移动端操作 | `rfid-handset`，应用名和页面能力围绕 RFID 手持机 |
| 门口机 | 库房出入口、通道值守 | 出入库识别、门口机日志、门口机告警、未授权带出提示、进出统计 | `rfid`、`smart-doc-vault-rfid` 门口机模块 |

这五类形态都可能使用 RFID 读写能力，但交互目标不同：RFID 打印机偏标签制作和写入复核，盘点车偏批量扫描，馆员工作站偏柜台和标签处理，手持机偏移动现场操作，门口机偏通行识别和异常告警。

### 现场设备图

| 类型 | 设备图 | 产品口径 |
| --- | --- | --- |
| RFID 打印机 | ![RFID 打印机](/illustrations/sdv/rfid/rfid-printer.png) | 用于打印 RFID 标签，并完成 TID 读取、EPC 写入、打印后复核、重打和作废。 |
| 盘点车 | ![RFID 盘点车](/illustrations/sdv/rfid/inventory-cart.png) | 用于库区批量盘点和现场巡检，重点关注读取范围、任务进度和差异汇总。 |
| 馆员工作站 | ![RFID 馆员工作站](/illustrations/sdv/rfid/librarian-workstation.png) | 用于柜台建档、绑标、复核和异常标签处理，重点关注单标签稳定识别和操作反馈。 |
| 手持机 | ![RFID 手持机](/illustrations/sdv/rfid/handheld-terminal.png) | 用于移动盘点、现场查找、标签绑定、换绑、解绑和未知标签处理。 |
| 门口机 | ![RFID 门口机](/illustrations/sdv/rfid/door-gate.png) | 用于出入口通行识别、未授权带出提醒、门口机日志和现场告警。 |

### 设备接入项目

RFID 设备侧不要让前端直接拼串口或 TCP 协议帧。当前本地服务以 `rfid-device-go` 做统一入口，再由上层前端或后端调用 HTTP / WebSocket 接口。

| 项目 | 仓库（可用地址） | 产品职责 |
| --- | --- | --- |
| RFID 读写器服务 | [rfid-device-go](https://gitlab.singzer.cn/fit-archive/rfid/rfid-device-go) | 统一接入读写器，封装 TCP / 串口传输、双协议命令、连续读卡、设备状态和本地 SQLite 状态 |
| RFID 打印服务 | [rfid-printer-node](https://gitlab.singzer.cn/fit-archive/rfid/rfid-printer-node) | 统一接入 RFID 打印机，负责本地打印、打印机列表、标签内容下发、TID / EPC 读写和打印结果回传 |
| RFID 前端能力线 | [fit-archive-ng](https://gitlab.singzer.cn/fit-archive/rfid/fit-archive-ng) | 馆员工作站、盘点车工作台、门口机管理、RFID 配置和主系统页面入口 |
| RFID 后端能力线 | [smart-doc-vault-rfid](https://gitlab.singzer.cn/fit-archive/rfid/smart-doc-vault-rfid) | 门口机、盘点车、标签、档案状态和消息中心等后端业务能力 |
| 门口机终端 | [rfid](https://gitlab.singzer.cn/fit-archive/rfid/rfid) | 门口机大屏 / 终端应用，负责出入库扫描展示、日志、告警和现场交互 |
| RFID 手持机 | [rfid-handset](https://gitlab.singzer.cn/fit-archive/rfid/rfid-handset) | 手持机 App，负责移动盘点、查找、档案标签和层架标签操作 |

## 协议厂家

`rfid-device-go` 当前按 `/v1` 和 `/v2` 维护两套主流读写器协议，业务侧通过统一命令入口调用，不需要直接关心底层帧格式。

| 协议 | 厂家 / 口径 | 适用场景 | 连接方式 | 业务说明 |
| --- | --- | --- | --- | --- |
| `v1` | GX / 国芯物联 | 常规 RFID 读写器、馆员工作站、盘点类读卡场景 | TCP / 串口 | 对应 `GX.zip` 中的 `RFID读写器数据通信协议.pdf`，支持读写器信息、温度、GPI/GPO、功率、频段、EPC 基带、单次读卡、连续读卡等能力 |
| `v2` | RD / 英频杰 | 门口机和部分 UHF\_RFID 读写器场景 | TCP / 串口 | 对应 `RD.zip` 中的 `UHF_RFID模块通信协议V1.8.4.pdf`，支持硬件 / 固件 / 唯一 ID、功率、GPIO、门禁触发读卡、门禁方向和门禁统计等能力 |

### 协议资料

| 资料 | 用途 |
| --- | --- |
| 网盘：[GX.zip](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/RFID/GX.zip) | GX / 国芯物联协议资料，主文档为 `RFID读写器数据通信协议.pdf` |
| 网盘：[RD.zip](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3/RFID/RD.zip) | RD / 英频杰协议资料，主文档为 `UHF_RFID模块通信协议V1.8.4.pdf` |

接口入口按协议分组：

```text
/v1/command
/v1/commands/ws
/v2/command
/v2/commands/ws
```

其中 `command` 用于普通命令和设备管理，`commands/ws` 用于连接设备、执行命令、启动 / 停止读卡流和订阅事件。设备唯一标识按 `deviceType-uuid` 形成，例如门口机、盘点车或馆员工作站各自维护自己的设备标识。

## 数据关系

RFID 页面只维护产品口径，不直接展开数据库结构。但业务上需要明确几组关系，否则后续很难判断异常属于哪个模块。

```text
档案 / 装具
  ├─ 绑定 RFID 标签
  ├─ 归属库区 / 库位
  ├─ 参与借阅 / 归还 / 上架
  └─ 参与盘点任务

RFID 标签
  ├─ TID
  ├─ EPC
  ├─ 标签状态
  └─ 绑定对象

设备事件
  ├─ 设备
  ├─ 标签读取结果
  ├─ 场景 / 任务
  └─ 处理结果
```

| 关系 | 说明 |
| --- | --- |
| 对象和标签 | 一份档案或一个装具可以绑定当前有效标签，历史换标需要保留记录 |
| 标签和设备事件 | 同一标签可能被多台设备多次读取，需要按任务、设备和时间合并 |
| 盘点任务和读取结果 | 读取结果必须归属到明确任务或场景，否则不能直接进入盘点差异 |
| 业务状态和识别状态 | 业务状态来自档案流程，识别状态来自现场读取，两者需要比对而不是互相覆盖 |

## 状态与异常

RFID 能提高现场识别效率，但也会引入设备误读、漏读、标签损坏和绑定错误。产品上应把异常作为正常流程的一部分设计。

| 异常 | 常见原因 | 处理方向 |
| --- | --- | --- |
| 标签未绑定 | 新标签未绑定对象，或历史数据缺失 | 进入待绑定或异常标签处理 |
| 标签重复 | 一个编码被多个对象使用，或重打后旧标签未作废 | 查重、作废旧绑定、重新绑定 |
| 读取不到 | 标签损坏、遮挡、距离不合适、设备功率或天线问题 | 复读、换标、检查设备和现场环境 |
| 读到多余标签 | 串读、范围外标签进入读取区域、盘点范围配置错误 | 过滤、人工确认、调整读取范围 |
| 设备离线 | 服务未启动、网络断开、设备故障 | 检查本地服务、MQTT、网络和硬件 |
| 业务不一致 | RFID 显示在位，但业务已借出，或业务在库但现场读不到 | 进入差异处理，由业务人员确认 |

## 设备范围

```text
RFID
├─ RFID 标签
├─ RFID 打印机
├─ 门口机
├─ 手持机
├─ 盘点车
├─ 馆员工作站
├─ 读写器
└─ RFID 服务
```

## 产品边界

* RFID 关注实物档案识别、盘点和现场操作。
* 档案借阅、入库、出库、盘点任务本身仍属于档案管理。
* 读写器协议、设备服务、标签协议、打印协议等技术实现放到系统架构或设备文档。
* 截至目前仍在开发中的能力，需要在具体页面标记状态，不要和已稳定能力混写。
* 普通纸质标签、借阅单、移交单打印属于档案管理里的打印能力；RFID 标签读写和 RFID 打印机能力归入 RFID。
* 如果某个项目只使用条码或二维码，不使用 RFID 芯片读写，不应归入 RFID 主能力。

## 当前开发口径

当前 RFID 相关能力主要沉淀在 `fit-archive/rfid` 版本线，和稳定交付线、历史线要分开理解。写文档时建议标注能力状态：

| 状态 | 文档写法 |
| --- | --- |
| 已稳定 | 明确可交付范围、入口、限制和常见问题 |
| 开发中 | 写清楚目标流程和当前已实现部分，不承诺完整交付 |
| 项目定制 | 标注项目差异、设备型号和现场限制 |
| 待确认 | 保留问题清单，不混入稳定流程 |

相关仓库可参考 [3-开发流程](/wiki/sdv/development-workflow) 中的 RFID 能力线说明。具体协议、服务端口、设备调试和部署方法后续应放到系统架构、调试或交付文档中，不在本页展开。

## 后续拆页建议

```text
RFID
├─ RFID 总览
├─ RFID 标签
├─ 标签打印
├─ 馆员工作站
├─ 门口机
├─ 手持机
├─ 盘点车
├─ 协议厂家
├─ 盘点与异常处理
└─ 设备接入与调试
```

---

---
url: /wiki/sdv/other.md
---

# 其他

其他页面用于放置不适合归入档案管理、数字化、环境控制、RFID 四个主板块，但又属于智档宝产品视角的能力。

## 能力清单

| 能力 | 说明 | 关联方向 |
| --- | --- | --- |
| 授权管理 | 系统授权、离线授权、授权审批和授权校验 | 授权服务、部署交付 |
| 大屏展示 | 新大屏、定制大屏、库房状态展示 | 大屏前端、后端接口、数据可视化 |
| 密集架 / 回转柜 | 作为档案架具和库位管理能力维护，详细内容见档案管理 | 档案管理、系统架构、设备接入 |
| 打印服务 | 普通打印、标签打印、模板打印 | 打印服务、本地服务、RFID 打印机 |
| 人脸识别 | 身份识别、门禁或现场操作辅助 | 人脸服务、门口机、项目定制 |
| 服务监控 | Windows 服务、本地服务、现场程序状态监控 | 本地服务、运维工具 |
| 项目定制 | 面向客户项目的差异功能和交付形态 | 项目分支、定制仓库、交付文档 |
| 打包交付 | zip 软件包、安装脚本、注册服务、Docker 或离线包 | 交付文档、部署脚本、运维说明 |

## 放入原则

* 如果能力围绕档案业务对象流转，或围绕档案架具、库位、密集架、回转柜展开，优先放入档案管理。
* 如果能力围绕文件上传、预览、解析、搜索，优先放入数字化。
* 如果能力围绕环境监测、门禁、摄像头、库房现场状态，优先放入环境控制。
* 如果能力围绕 RFID 标签、读写设备、盘点车、手持机，优先放入 RFID。
* 如果能力跨多个方向，且目前还没有独立产品页，先放入其他。

## 项目定制记录方式

项目定制不要把所有细节都写在产品视图里，建议只维护摘要和入口。

```text
项目名称
客户场景
涉及能力
差异说明
关联仓库
部署方式
验收口径
```

## 后续拆页建议

```text
其他
├─ 授权管理
├─ 大屏展示
├─ 打印服务
├─ 人脸识别
├─ 服务监控
├─ 项目定制
└─ 打包交付
```

---

---
url: /wiki/sdv/system-architecture.md
---

# 2-系统架构

系统架构用于从研发视角理解智档宝。它回答三个问题：系统由哪些层组成、各层之间怎么协作、出问题时应该先看哪里。

智档宝不是单个 Web 项目。一次完整交付通常包含 Web 前端、后端服务、本地服务、中间件、文件与搜索服务、设备接入程序、现场硬件、固件控制程序和离线安装包。产品视图描述“用户能做什么”，本章描述“这些能力由什么承载”。

![智档宝系统架构分层](/illustrations/smart-doc-vault-system-architecture.png)

## 阅读目标

* 先建立智档宝的系统地图，知道前端、后端、本地服务、设备和中间件的边界。
* 理解档案管理、数字化、RFID、环境控制、打印等能力在系统里的协作方式。
* 遇到问题时能判断优先排查前端、后端、依赖服务、现场程序还是设备链路。

## 总体架构

```mermaid
flowchart TB
  user["用户 / 实施 / 运维"]
  browser["Web 前端<br/>fit-archive-ng"]
  client["桌面客户端 / 本地工具<br/>Electron / 监控 / 打印"]
  api["后端主服务<br/>smart-doc-vault"]

  db["MySQL<br/>业务数据"]
  cache["Redis<br/>缓存 / 临时状态"]
  object["Minio / 文件目录<br/>附件与扫描件"]
  search["Elasticsearch<br/>全文搜索"]
  parser["Tika / DocumentConvert<br/>解析与预览"]
  tsdb["InfluxDB<br/>时序数据"]
  mq["EMQX / MQTT<br/>设备消息"]

  local["本地服务<br/>打印 / 客户端 / 监控"]
  access["设备接入层<br/>RFID / 环境控制 / 架体 / 门口机"]
  firmware["固件 / 控制板<br/>网关 / 传感器 / 移动列 / 固定列"]
  devices["现场设备<br/>密集架 / 回转柜 / RFID / 环控 / 打印机"]

  user --> browser
  user --> client
  browser --> api
  client --> api
  api --> db
  api --> cache
  api --> object
  api --> search
  api --> parser
  api --> tsdb
  api --> mq
  api --> local
  api --> access
  access --> mq
  access --> firmware
  firmware --> devices
  local --> devices
```

从上往下看，智档宝可以理解为四条主线：

| 主线 | 说明 | 典型问题 |
| --- | --- | --- |
| 业务主线 | 前端页面调用后端接口，后端维护档案、库房、权限、流程和配置 | 页面报错、接口失败、数据不一致 |
| 文件主线 | 上传文件进入对象存储或文件目录，再由解析、预览、搜索链路消费 | 上传失败、预览失败、全文搜不到 |
| 设备主线 | 后端通过设备接入层、MQTT、本地服务或协议程序联动现场设备 | RFID 不识别、架体不动、环境控制数据不上报 |
| 交付主线 | Linux Docker 离线包或 Windows 离线包把上述组件装到现场环境 | 服务起不来、端口占用、版本对不上 |

## 系统分层

| 层级 | 主要职责 | 常见载体 |
| --- | --- | --- |
| 展示层 | 提供业务入口、状态展示、表单操作、大屏和客户端界面 | Web 前端、Electron 客户端、大屏、手持机页面 |
| 业务服务层 | 承载档案规则、权限、流程、接口、设备能力封装 | `smart-doc-vault` 及版本线后端 |
| 数据与中间件层 | 保存业务数据、文件、搜索索引、时序数据、消息和缓存 | MySQL、Redis、Minio、Elasticsearch、InfluxDB、EMQX、Tika |
| 本地服务层 | 处理必须靠现场机器完成的能力 | 打印服务、文档转换、Windows 监控、客户端本地能力 |
| 设备接入层 | 把现场协议、设备状态和业务系统连接起来 | RFID 服务、环境控制网关、架体控制、门口机、调试工具 |
| 固件 / 控制层 | 直接面对硬件输入输出和设备控制 | 网关、传感器、控制板、移动列、固定列、读写器 |
| 部署交付层 | 把代码和依赖打成可安装、可回滚、可追溯的现场包 | Linux Docker 离线包、Windows 离线包、更新服务 |

这一章只维护稳定边界和关键流向。版本线和仓库演进看 [3-开发流程](/wiki/sdv/development-workflow)，打包脚本、端口、默认账号和发布目录看 [4-打包分发](/wiki/sdv/packaging-distribution)。

## 展示层

展示层负责用户看到的入口，不负责最终业务一致性。

| 入口 | 作用 | 依赖 |
| --- | --- | --- |
| Web 前端 | 档案管理、数字化、库房、权限、配置、设备状态展示 | 后端接口、静态资源、浏览器缓存 |
| 大屏 | 库房态势、设备状态、统计数据和可视化展示 | 后端统计接口、设备状态数据 |
| Electron 客户端 | 桌面场景、客户端分发、本地能力整合 | 前端构建、后端接口、本地服务 |
| 手持机 / 门口机页面 | RFID、盘点、现场操作入口 | RFID 服务、设备接口、后端业务接口 |

前端问题先判断三件事：页面版本是否正确、接口是否返回正常、浏览器缓存是否拿到旧资源。版本识别规则看 [3-开发流程](/wiki/sdv/development-workflow#版本号规则)。

## 业务服务层

业务服务层是智档宝的核心。它不应该把所有现场差异直接写进业务流程，而是把差异沉淀到配置、设备接入层或项目定制线。

| 能力 | 后端职责 | 典型依赖 |
| --- | --- | --- |
| 档案管理 | 档案对象、库房位置、借阅归还、盘点、状态流转 | MySQL、Redis、设备状态 |
| 数字化 | 文件元数据、上传记录、预览入口、搜索关联 | Minio、Tika、DocumentConvert、Elasticsearch |
| 权限认证 | 用户、角色、库房权限、功能权限、接口鉴权 | 用户体系、权限表、登录配置 |
| 设备联动 | 把业务动作转换为设备命令或设备状态判断 | MQTT、设备接入服务、现场协议 |
| 系统配置 | 现场参数、开关、路径、端口、设备地址 | 配置文件、数据库配置、部署环境 |

排查后端问题时，优先确认：接口返回、日志、数据库连接、中间件连接、当前前后端 hash 是否匹配。

## 数据与中间件层

数据层不是单一数据库。智档宝会按数据类型使用不同组件。

| 组件 | 保存什么 | 常见影响 |
| --- | --- | --- |
| MySQL | 档案、库房、权限、配置、业务流程数据 | 业务查询、登录、状态流转 |
| Redis | 缓存、临时状态、会话或任务状态 | 登录状态、接口性能、临时任务 |
| Minio / 文件目录 | 附件、扫描件、图片、预览源文件 | 上传、下载、预览、电子档案 |
| Elasticsearch | 全文索引和检索数据 | 全文搜索、关键字查询 |
| Tika / DocumentConvert | 文档内容解析和格式转换 | Office/PDF 预览、内容抽取 |
| InfluxDB | 温湿度、设备状态等时序数据 | 环境控制曲线、历史趋势 |
| EMQX / MQTT | 设备事件、设备命令和状态消息 | RFID、环境控制、设备联动 |

如果业务数据能查到，但文件打不开，优先查 Minio / 文件目录和预览链路。如果文件能打开但搜不到，优先查解析和 Elasticsearch。不要把所有问题都归到后端接口。

## 关键链路

### 档案业务链路

```mermaid
sequenceDiagram
  participant U as 用户
  participant F as Web 前端
  participant B as 后端主服务
  participant D as MySQL
  participant E as 设备接入层
  participant M as MQTT / 现场设备

  U->>F: 查询 / 建档 / 借阅 / 盘点
  F->>B: 调用业务接口
  B->>D: 读取或写入档案、库房、权限数据
  alt 需要设备联动
    B->>E: 下发业务动作
    E->>M: 转换为设备命令
    M-->>E: 返回状态或事件
    E-->>B: 回写设备结果
    B->>D: 更新业务状态
  end
  B-->>F: 返回操作结果
  F-->>U: 展示状态
```

档案业务链路的关键是“业务状态”和“设备状态”不要混淆。设备动作成功不等于业务一定完成；业务状态更新也需要能追溯对应设备结果。

### 数字化文件链路

```mermaid
flowchart LR
  upload["上传文件"]
  api["后端记录元数据"]
  object["对象存储 / 文件目录"]
  parser["Tika / DocumentConvert"]
  search["Elasticsearch"]
  preview["在线预览"]
  query["全文搜索"]

  upload --> api
  api --> object
  object --> parser
  parser --> preview
  parser --> search
  search --> query
  api --> query
```

数字化链路常见故障要按阶段拆开看：上传是否成功、元数据是否写入、文件是否存在、解析服务是否可用、索引是否建立、前端预览地址是否正确。

### 设备接入链路

```mermaid
flowchart TB
  api["后端主服务"]
  mqtt["MQTT / 消息层"]
  rfid["RFID 服务<br/>门口机 / 手持机 / 盘点车"]
  env["环境控制接入<br/>温湿度 / 空调 / 漏水 / 报警"]
  rack["架体接入<br/>密集架 / 回转柜 / 固定列"]
  print["本地打印服务<br/>普通打印 / 标签打印"]
  firmware["固件 / 控制板 / 网关"]
  physical["现场设备"]

  api --> mqtt
  mqtt --> rfid
  mqtt --> env
  api --> rack
  api --> print
  rfid --> firmware
  env --> firmware
  rack --> firmware
  firmware --> physical
  print --> physical
```

设备接入层的职责是消化现场差异。协议、串口、网口、网关、设备厂商、项目定制都不应该直接污染核心档案流程。

## 本地服务和现场程序

本地服务通常运行在 Windows 主机、Linux 服务器、边缘网关或设备控制机上。它们和主系统相比更依赖现场环境。

| 服务类型 | 为什么需要本地服务 | 排查入口 |
| --- | --- | --- |
| 打印服务 | 浏览器不能直接稳定控制所有打印机和标签机 | 打印服务进程、打印机驱动、模板、端口 |
| 文档转换 | Office/PDF 等预览需要额外解析或转换能力 | Tika、DocumentConvert、文件路径 |
| Windows 监控 | 现场 Windows 离线包包含多个服务，需要统一查看状态 | serviceMonitor、Windows 服务列表 |
| RFID / 门口机 | 读写器、门口机和手持设备需要常驻接入程序 | RFID 服务日志、MQTT、设备网络 |
| 架体 / 环境控制接入 | 现场协议和硬件状态需要适配 | 网关、串口/网口、控制程序日志 |

写本地服务文档时必须说明运行位置、启动方式、监听端口、配置文件、日志位置、主系统调用方式和重启方法。

## 部署形态

智档宝目前常见两类稳定交付形态。

| 形态 | 说明 | 适合场景 |
| --- | --- | --- |
| Linux Docker 离线包 | 后端和依赖服务以容器方式交付，适配 x86\_64、arm64、loongarch 等 | 国产化 Linux、服务器部署、离线环境 |
| Windows 离线包 | 后端和依赖服务以 Windows 服务或本地目录方式交付 | Windows 主机、一体化本地部署、现场工具集成 |

部署形态不改变系统分层，只改变组件运行位置和守护方式。同一个逻辑组件，在 Linux 可能是 Docker 容器，在 Windows 可能是系统服务或本地进程。

## 排障入口

遇到问题时，先按现象定位层级。

| 现象 | 优先判断 | 下一步 |
| --- | --- | --- |
| 页面白屏或按钮没反应 | 前端资源、浏览器缓存、接口地址 | 看控制台、Network、前端 hash |
| 接口 500 或业务失败 | 后端日志、数据库、中间件连接 | 看后端日志和接口返回 |
| 登录或权限异常 | 登录配置、用户信息、角色和库房权限 | 看认证接口、权限表、当前用户 |
| 文件上传失败 | 后端上传接口、对象存储、磁盘空间 | 看 Minio / 文件目录和后端日志 |
| 文件能上传但不能预览 | 解析转换服务、文件格式、预览地址 | 看 Tika / DocumentConvert |
| 全文搜索搜不到 | 解析结果、索引任务、Elasticsearch | 看解析日志和 ES 索引 |
| RFID 不识别 | RFID 服务、读写器、MQTT、标签 | 看 RFID 服务日志和设备连接 |
| 环境控制没有数据 | 网关、传感器、MQTT、InfluxDB | 看网关和消息链路 |
| 架体不动作 | 控制程序、串口/网口、固件、供电 | 先验证设备侧，再看业务命令 |
| Windows 服务启动失败 | 服务注册、路径、端口占用、权限 | 看 serviceMonitor、services.msc、事件日志 |

排障记录至少写清楚：现场版本、前端 hash、后端 hash、部署形态、问题时间、操作路径、接口或服务日志、是否涉及设备。

## 架构维护原则

* 主线架构只写稳定共识，客户差异放到项目定制或现场记录。
* 架构图优先表达边界和流向，不追求把所有仓库、端口和服务名一次画全。
* 设备差异优先沉淀到设备接入层、协议层或配置层，不直接散落在业务逻辑里。
* 本地服务必须标清运行位置和守护方式，否则后续现场排障会失去入口。
* 版本、打包和发布信息要能追溯到 Git hash，不用“最新版”“现场版”这类无法定位的说法。

---

---
url: /wiki/sdv/development-workflow.md
---

# 智档宝开发流程

这篇文档用于说明智档宝研发代码在 GitLab 中的组织方式，以及主线、大版本线、能力线和项目定制线之间的关系。

智档宝不是一个单仓库项目。早期平台开发主要集中在 `fit-archive` 组下，前端、后端、设备接入、安装脚本和交付工具逐步沉淀。后续随着密集架、回转柜、新大屏、RFID、项目定制等方向扩展，GitLab 中出现了长期子分组、阶段性分组和个人/临时 fork。

![智档宝开发流程版本树](/illustrations/sdv-development-workflow-xiaohei.png)

## 总体口径

| 口径 | GitLab 表现 | 用途 |
| --- | --- | --- |
| 主线平台 | `fit-archive/fit-archive-ng`、`fit-archive/smart-doc-vault` 等 | 承载智档宝通用前后端能力 |
| 历史版本线 | 基础版本、`fit-archive/2024-new-screen`、`fit-archive/hzg` | 承载从基础平台到新大屏、回转柜阶段的历史演进 |
| 稳定版本线 | `fit-archive/fdmjj` | 承载当前稳定版本和交付能力 |
| 当前开发版 | `fit-archive/rfid` | 承载目前仍在开发中的最新版本 |
| 项目定制线 | `fit-archive/adqrmfy`、`fit-archive/gdjy`、`fit-archive/yd`、`fit-archive/gansu` 等 | 承载客户项目差异、阶段性交付和现场版本 |
| 个人 / 临时 fork | `icepie/*`、`lxr/*`、`Jeff/*`、`zks/*` 等 | 承载个人开发、验证、临时分支或迁移过程 |

这里的“分支”不是只指 Git branch。历史上很多“大版本分支”实际表现为子分组或独立仓库副本。看代码来源时，要同时看 GitLab 分组路径、项目名、默认分支、最近活动和提交历史。

## GitLab 组织演化

```mermaid
flowchart TB
  root["fit-archive<br/>智档宝主组"]

  main["主线平台<br/>fit-archive-ng<br/>smart-doc-vault"]
  tools["基础工具 / 安装交付<br/>windows-install<br/>xc-install<br/>electron-hiprint<br/>device-*"]

  base["基础版本<br/>早期平台主线"]
  screen["2024-new-screen<br/>新大屏历史版本"]
  hzg["hzg<br/>回转柜历史版本"]
  fdmjj["fdmjj<br/>稳定版本"]
  rfid["rfid<br/>当前开发版"]

  custom["项目定制子分组<br/>adqrmfy / gdjy / yd / gansu / ..."]
  personal["个人或临时 fork<br/>icepie / lxr / Jeff / zks / ..."]

  root --> main
  root --> tools
  main --> base
  base --> screen
  screen --> hzg
  hzg --> fdmjj
  fdmjj --> rfid
  main -.阶段性交付 / 客户差异.-> custom
  base -.历史项目 / 阶段版本.-> custom
  screen -.新大屏项目 / 定制大屏.-> custom
  hzg -.回转柜项目 / 现场版本.-> custom
  fdmjj -.项目版本 / 现场版本.-> custom
  main -.个人开发 / 临时验证.-> personal
  base -.个人开发 / 临时验证.-> personal
  screen -.个人开发 / 临时验证.-> personal
  hzg -.个人开发 / 临时验证.-> personal
  fdmjj -.个人开发 / 临时验证.-> personal
  rfid -.个人开发 / 临时验证.-> personal
```

理解这个图时要注意：版本演进口径按“基础版本 -> 新大屏 -> hzg -> fdmjj 稳定版 -> rfid 开发版”理解。`fdmjj` 是当前稳定版本，`rfid` 是目前的开发版本，`fdmjj` 之前的基础、新大屏、`hzg` 都按历史版本看。中间创建的子分组通常是从主线或某条版本线 fork / 复制出来，用于项目交付、客户定制或阶段性稳定版本。

## 版本线说明

| 版本线 | 大致定位 | 什么时候看它 |
| --- | --- | --- |
| 基础版本 | 智档宝最早的平台基础，沉淀通用前后端、安装交付和基础工具 | 查早期平台结构、通用能力来源、历史项目来源 |
| `2024-new-screen` | 基础版本之后的新大屏历史版本，重点是大屏展示和可视化交互 | 查新大屏、定制大屏、库房态势展示相关历史实现 |
| `hzg` | 新大屏之后的回转柜历史版本，重点是回转柜业务、库位和设备联动 | 查回转柜项目、判断回转柜和其他架具体系的差异 |
| `fdmjj` | 当前稳定版本线，围绕飞度密集架交付沉淀，包含平台侧、更新服务等 | 做稳定版本维护、现场交付、密集架相关问题回归 |
| `rfid` | 目前的开发版本，沉淀 RFID、手持机、门口机、打印和相关后端能力 | 做 RFID 新能力开发、手持机/标签/打印联调、验证当前最新方向 |
| 项目定制分组 | 从主线或某条版本线 fork / 复制出来，服务某个客户或阶段性交付 | 查客户差异、现场版本、临时补丁和是否需要回流 |

判断一个项目应该基于哪条线，不要只看项目名。优先看它所处阶段：历史问题按基础版本、新大屏、`hzg` 追溯；稳定交付优先看 `fdmjj`；新能力开发看 `rfid`。如果只是客户字段、页面或部署差异，应放在项目定制线并记录来源。

## 版本号规则

智档宝前后端版本主要用 Git commit hash 识别，不依赖 `package.json` 的语义版本号。以 `fdmjj/fit-archive-ng` 和 `fdmjj/smart-doc-vault` 为例：

| 项目 | 规则 | 说明 |
| --- | --- | --- |
| 前端 `fit-archive-ng` | 构建时取 `git rev-parse --short HEAD` 注入 `__COMMIT_HASH__` | Vite 配置会把当前前端提交短 hash 注入页面；Git 不可用时回退到 `CI_COMMIT_SHORT_SHA`、`COMMIT_HASH` 或 `unknown` |
| 后端 `smart-doc-vault` | 编译时通过 `-ldflags` 注入 `Version`、`BuildTime`、`BuildHash` | Makefile / Windows build 脚本里 `BuildHash` 来自 `git rev-parse --short HEAD` |
| 系统信息接口 | 后端返回 `v<Version>_<后端hash>` | `/sys/getSysSWInfo` 中 `Version` 形如 `v1.0_<后端hash>` |
| 前端展示 | 前端再追加 `_<前端hash>` | 页面拿到后端 `Version` 后追加 `__COMMIT_HASH__`，最终用于区分前后端是否都是预期提交 |

现场核对版本时，优先记录完整显示值，而不是只写“1.0”或“最新版”。推荐格式：

```text
后端：smart-doc-vault <后端短 hash>
前端：fit-archive-ng <前端短 hash>
页面显示：v1.0_<后端短 hash>_<前端短 hash>
编译时间：系统信息页显示的编译时间
```

拿到 hash 后，可以打开 [飞度一体化平台](https://fd-one.singzer.cn) 的“版本搜索”，输入前端 hash、后端 hash 或完整版本号。平台会按提交、标签和版本信息搜索对应项目，用来定位这个版本来自哪个仓库、哪次提交以及应该找哪条版本线排查。

![飞度一体化平台版本搜索](/illustrations/sdv/version-search-fd-one.png)

如果前端页面显示的版本 hash 和 GitLab 当前提交不一致，先判断是否浏览器缓存、部署目录未覆盖、服务未重启或前后端来自不同版本线。

## 代表性仓库

| 路径 | 定位 | 默认分支 | 最近活动 |
| --- | --- | --- | --- |
| [`fit-archive/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/fit-archive-ng) | 智档宝主线前端 | `main` | 2025-01-01 |
| [`fit-archive/smart-doc-vault`](https://gitlab.singzer.cn/fit-archive/smart-doc-vault) | 智档宝主线后端 | `main` | 2025-01-10 |
| [`fit-archive/fdmjj/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/fdmjj/fit-archive-ng) | 密集架前端 / 平台侧 | `main` | 2026-06-09 |
| [`fit-archive/fdmjj/smart-doc-vault`](https://gitlab.singzer.cn/fit-archive/fdmjj/smart-doc-vault) | 密集架后端 / 平台侧 | `main` | 2026-06-14 |
| [`fit-archive/hzg/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/hzg/fit-archive-ng) | 回转柜前端开发线 | `main` | 2025-04-10 |
| [`fit-archive/hzg/smart-doc-vault`](https://gitlab.singzer.cn/fit-archive/hzg/smart-doc-vault) | 回转柜后端开发线 | `main` | 2026-03-05 |
| [`fit-archive/2024-new-screen/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/2024-new-screen/fit-archive-ng) | 新大屏前端开发线 | `main` | 2024-10-22 |
| [`fit-archive/2024-new-screen/smart-doc-vault`](https://gitlab.singzer.cn/fit-archive/2024-new-screen/smart-doc-vault) | 新大屏后端开发线 | `main` | 2025-12-15 |
| [`fit-archive/rfid/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/rfid/fit-archive-ng) | RFID 前端能力线 | `main` | 2026-06-14 |
| [`fit-archive/rfid/smart-doc-vault-rfid`](https://gitlab.singzer.cn/fit-archive/rfid/smart-doc-vault-rfid) | RFID 后端能力线 | `main` | 2026-06-15 |

这张表只列代表性入口，不是完整项目清单。完整 GitLab 清单应通过脚本重新采集，避免文档长期复制过期信息。

## 日常开发流程

```mermaid
flowchart LR
  demand["需求 / 问题"]
  classify{"判断归属"}

  main["主线平台<br/>通用能力"]
  line["大版本 / 能力线<br/>fdmjj / hzg / 新大屏 / RFID"]
  custom["项目定制线<br/>客户差异 / 现场版本"]

  branch["创建 Git 分支<br/>或选择现有子分组"]
  develop["开发 / 联调 / 自测"]
  review["代码评审 / 合并"]
  release["打包 / 发布 / 现场交付"]
  record["记录差异<br/>版本、仓库、部署方式"]
  backport{"是否回流主线"}

  demand --> classify
  classify -->|通用能力| main
  classify -->|长期方向| line
  classify -->|客户差异| custom
  main --> branch
  line --> branch
  custom --> branch
  branch --> develop --> review --> release --> record --> backport
  backport -->|是| main
  backport -->|否| custom
```

开发前先判断归属，不要一上来就新建仓库或复制项目：

| 场景 | 推荐位置 | 原则 |
| --- | --- | --- |
| 多个项目都需要的通用能力 | 主线平台 | 优先进入 `fit-archive` 主线仓库，再由版本线同步 |
| 稳定版本维护 | `fdmjj` | 作为当前稳定版本线维护，优先保障交付和回归稳定 |
| 历史版本问题追溯 | 基础版本 / 新大屏 / `hzg` | 按版本链路追溯来源，不直接在历史线继续扩散新能力 |
| 当前开发 | `rfid` | 作为目前开发版本承载新能力 |
| 客户项目独有字段、页面、设备差异 | 项目定制线 | 放到客户项目分组，并记录来源主线和差异点 |
| 临时验证、个人实验 | 个人 / 临时 fork | 不直接作为交付源，稳定后迁移到主线或能力线 |
| 现场紧急修复 | 当前交付线 | 修复后补记录，并判断是否需要回流主线 |

## 分支和子分组约定

* 版本线要按“基础版本 -> 新大屏 -> `hzg` -> `fdmjj` 稳定版 -> `rfid` 开发版”记录来源。
* 项目定制线要写清楚从哪个主线或能力线 fork / 复制出来。
* 新建子分组时，要在 README 或交付记录中说明客户、用途、来源、前端仓库、后端仓库和部署方式。
* 同名仓库在不同分组下可能含义不同，例如 `fit-archive-ng` 在主线、密集架、回转柜、新大屏、项目定制中都可能存在。
* 如果定制能力已经被多个项目复用，应考虑回流主线或沉淀为能力线，而不是继续在客户仓库里复制。

---

---
url: /wiki/sdv/packaging-distribution.md
---

# 打包分发

智档宝的交付包不是单一程序。一次正式分发通常同时包含前端页面、后端服务、桌面客户端、打印服务、数据库、中间件、搜索服务、文档解析服务和运行监控工具。

这篇文档用于说明当前稳定版本 `fdmjj` 的打包方式、参考仓库、推荐构建环境和发布检查项。

![智档宝打包分发](/illustrations/sdv-packaging-distribution-xiaohei.png)

## 1. 这篇文档解决什么

打包分发文档面向研发、测试、实施和运维，重点回答四个问题：

| 问题 | 说明 |
| --- | --- |
| 包从哪里来 | 对应哪些 GitLab 仓库和脚本 |
| 包怎么命名 | 如何从包名判断前后端版本 |
| 用什么机器打 | Linux 离线 Docker 包和 Windows 离线包分别需要什么环境 |
| 发出去前查什么 | 如何确认包能安装、能启动、能追溯版本 |

## 2. GitLab 参考仓库

| 仓库 | 用途 |
| --- | --- |
| [`fit-archive/fdmjj/docker-install`](https://gitlab.singzer.cn/fit-archive/fdmjj/docker-install) | Linux Docker 离线包构建脚本、离线 Docker 组件、各架构安装目录模板 |
| [`fit-archive/xc-install`](https://gitlab.singzer.cn/fit-archive/xc-install) | 国产化 Linux 老手动安装方式，已弃用，仅作历史参考；之前由 `zks` 负责 |
| [`fit-archive/fdmjj/sdv-windows`](https://gitlab.singzer.cn/fit-archive/fdmjj/sdv-windows) | Windows 离线包打包脚本、`sdv-test` 运行目录模板、Windows 部署说明 |
| [`fit-archive/fdmjj/fit-archive-ng`](https://gitlab.singzer.cn/fit-archive/fdmjj/fit-archive-ng) | 智档宝前端、Web dist、Electron 客户端、Linux 客户端包 |
| [`fit-archive/fdmjj/smart-doc-vault`](https://gitlab.singzer.cn/fit-archive/fdmjj/smart-doc-vault) | 智档宝后端、SQL、Windows / Linux 可执行文件 |
| [`fit-archive/windows-service-monitor`](https://gitlab.singzer.cn/fit-archive/windows-service-monitor) | Windows 运行监控工具 |

这些仓库是打包时的来源，不代表所有定制线都应该从这里发版。历史线、新大屏、`hzg`、`rfid` 等版本关系见 [3-开发流程](/wiki/sdv/development-workflow)。

## 3. 产物类型和命名规则

当前常见分发包分三类：

| 产物 | 命名规则 | 主要场景 |
| --- | --- | --- |
| Linux Docker 离线包 | `sdv-linux-<arch>-<backend_hash>-<frontend_hash>-<timestamp>.tar.gz` | Linux 服务器、国产化设备、内网离线部署 |
| Windows 离线包 | `sdv-windows-<backend_hash>-<frontend_hash>-<timestamp>.zip` | Windows 主机一键安装本地服务 |
| Windows 独立离线包 | `fit-archive-ng-<frontend_hash>-<timestamp>.zip`、`smart-doc-vault-<backend_hash>-<timestamp>.zip` | 只更新前端或只更新后端 |

包名中的 `backend_hash` 来自 `smart-doc-vault`，`frontend_hash` 来自 `fit-archive-ng`。这两个值都是 Git short hash，用于定位代码版本。

发布后需要在 [`https://fd-one.singzer.cn`](https://fd-one.singzer.cn) 的版本搜索里确认版本能反查到对应仓库和提交，避免现场只有压缩包但无法判断来源。

## 4. 最终发布地址

正式发布后的离线包放在公司网盘对应目录。现场实施和运维优先从这里取包，不直接从构建机临时目录取包。

| 版本 | 适配范围 | 下载地址 |
| --- | --- | --- |
| 智档宝 Windows 版 | Windows 主机、本地服务一体安装 | [智档宝 windows](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E6%99%BA%E6%A1%A3%E5%AE%9Dwindows) |
| 智档宝 Linux 版 | 麒麟、UOS、统信、国产化、龙芯、arm64 等 | [智档宝 linux](https://pan.feidu.fit/%E5%BC%80%E5%8F%91/%E6%99%BA%E6%A1%A3%E5%AE%9Dlinux) |

发布目录按版本线和架构分层，不把临时包、测试包直接放在根目录。

```text
智档宝windows/
└─ fdmjj/
   ├─ README.md
   ├─ sdv-windows-<backend_hash>-<frontend_hash>-<timestamp>.zip
   ├─ fit-archive-ng-<frontend_hash>-<timestamp>.zip
   └─ smart-doc-vault-<backend_hash>-<timestamp>.zip

智档宝linux/
└─ fdmjj/
   ├─ x86_64/
   │  ├─ README.md
   │  └─ sdv-linux-x86_64-<backend_hash>-<frontend_hash>-<timestamp>.tar.gz
   ├─ arm64/
   │  ├─ README.md
   │  └─ sdv-linux-arm64-<backend_hash>-<frontend_hash>-<timestamp>.tar.gz
   └─ loongarch/
      ├─ README.md
      └─ sdv-linux-loongarch-<backend_hash>-<frontend_hash>-<timestamp>.tar.gz
```

目录规范：

* `fdmjj` 是当前稳定版本线，正式稳定包默认进入这个目录。
* Linux 包必须进入对应架构目录，不同架构不要混放。
* `README.md` 放在对应发布目录内，记录包名、构建时间、前端 hash、后端 hash 和更新说明。
* 临时测试包需要单独建 `test`、`temp` 或日期目录，验证通过后再移动到正式目录。

## 5. 推荐打包系统

| 包类型 | 推荐系统 | 说明 |
| --- | --- | --- |
| Linux `x86_64` | 专用 Linux 构建机 | 最常用，适合构建 Docker 镜像和离线包 |
| Linux `arm64` | 原生 ARM Linux 或配置好的 buildx 构建机 | 原生环境更容易发现架构相关问题 |
| Linux `loongarch` | 原生龙芯 / LoongArch Linux | 不建议完全依赖跨架构构建，现场兼容风险更高 |
| Windows 离线包 | Linux + Wine 构建机 | 推荐方式，客户端交叉编译最方便，适合统一拉代码、构建 Web、构建 Electron Windows 客户端和压缩上传 |
| Windows 验收 | Windows 10 / Windows Server 2019 及以上 | 用于验证 bat 服务注册、客户端 exe、运行监控和本地安装目录 |

建议把构建机和验收机分开。构建机负责拉代码、编译、压缩、上传；验收机只拿最终包安装，避免构建缓存、旧目录或本机环境掩盖缺文件问题。

## 6. Linux / Docker 离线包

Linux 离线包以 `docker-install` 仓库为准。主要脚本如下：

| 脚本 | 作用 |
| --- | --- |
| `download-docker-offline.sh` | 下载离线 Docker 和 Compose 组件 |
| `setup-buildx.sh` | 配置 Docker buildx 和镜像源 |
| `build-linux-fdmjj.sh` | 拉取前后端、编译、构建镜像、打包、上传 |

支持架构：

| 架构 | 说明 |
| --- | --- |
| `x86_64` | 常规 Intel / AMD 服务器 |
| `arm64` | ARM 服务器、部分国产化硬件 |
| `loongarch` | 龙芯平台 |
| `all` | 顺序构建全部架构 |

构建机建议准备：

* Git SSH 访问 GitLab。
* Node.js、pnpm，用于构建 `fit-archive-ng`。
* Go、just，用于构建 `smart-doc-vault`。
* Docker、Docker Compose、buildx，用于构建和导出镜像。
* `aliyunpan-go` 或公司当前发布工具，用于上传发布产物。
* 足够磁盘空间，离线镜像和最终包会明显大于源码目录。

Linux 包构建流程：

```bash
./download-docker-offline.sh
./setup-buildx.sh
./build-linux-fdmjj.sh x86_64
```

实际构建中 `build-linux-fdmjj.sh` 会执行这些动作：

1. 从 `fit-archive/fdmjj` 拉取 `fit-archive-ng` 和 `smart-doc-vault`。
2. 前端执行依赖安装和生产构建，产出 Web dist。
3. 后端按目标架构交叉或原生编译，产出 Linux 可执行文件。
4. 构建 `sdv-app:latest` 等 Docker 镜像。
5. 将后端二进制、前端 dist、Docker 镜像、安装脚本和 compose 文件放入对应架构目录。
6. 生成 `sdv-linux-<arch>-<backend_hash>-<frontend_hash>-<timestamp>.tar.gz`。
7. 上传到智档宝 Linux 发布目录，并更新版本记录。

Linux 离线包主要服务、端口和默认账号 / Token：

| 服务 | Compose 服务 / 容器名 | 常见端口 | 运行形态 | 默认账号 / Token |
| --- | --- | --- | --- | --- |
| 智档宝主服务 | `app` / `sdv-app` | 80 / 8888 | 常驻，host 网络 | `DOCKER_P=true`；安装脚本创建 `authorized` 空文件 |
| MySQL | `mysql` / `sdv-mysql` | 3307 | 常驻 | `root` / `123456`；默认库 `tdpub` |
| Redis | `redis` / `sdv-redis` | 6379 | 常驻 | password 为空 |
| Minio | `minio` / `sdv-minio` | 9000 / 9001 | 常驻 | `admin` / `admin123456`；bucket `fit` |
| InfluxDB | `influxdb` / `sdv-influxdb` | 8086 | 常驻 | `admin` / `admin123456`；token `abc123123123abc`；org/bucket `fit` / `sdv` |
| EMQX | `emqx` / `sdv-emqx` | 1883 / 8083 / 8084 / 18083 | 常驻 | Dashboard `admin` / `public`；MQTT 匿名连接 |
| Tika | `tika` / `sdv-tika` | 9998 | 常驻 | 无 |
| DocumentConvert | `document-convert` / `sdv-document-convert` | 7010 | 常驻，host 网络 | 无 |
| Elasticsearch | `elasticsearch` / `sdv-es` | 9200 / 9300 | 常驻 | security `disabled` |
| ES 权限初始化 | `es-chown` / `sdv-es-chown` | - | 初始化任务 | 无 |
| ES 索引初始化 | `es-init` / `sdv-es-init` | - | 初始化任务 | 无 |

安装验证至少要做：

1. 目标机器以 root 权限执行安装脚本。
2. 确认 Docker 服务正常启动。
3. 确认镜像已 `docker load`。
4. 确认 `docker compose ps` 中主要服务为运行状态。
5. 访问 Web 页面和管理端。
6. 新建或查询一条档案数据，确认数据库、对象存储、搜索和后端接口协作正常。

::: details 历史方式：国产化 Linux 手动安装

[`fit-archive/xc-install`](https://gitlab.singzer.cn/fit-archive/xc-install) 是早期国产化 Linux 手动安装方式，之前由 `zks` 负责维护，已弃用。

这套方式主要用于 Docker 离线包成熟前的国产化环境交付，更多依赖人工准备系统环境、安装依赖服务、复制程序文件和调整配置。它的问题是步骤分散、环境差异大、可重复性弱，现场升级和问题回滚成本也更高。

老手动方式的服务、端口和默认账号 / Token：

| 服务 | 旧容器 / 服务名 | 管理方式 | 常见端口 | 默认账号 / Token |
| --- | --- | --- | --- | --- |
| 后端主服务 | `smart-doc-vault.service` | systemd | 8888 / 80 | 后端不是容器，由 systemd 直接拉起 |
| Docker | `docker.service` | systemd | - | 手动安装 Docker 二进制并写入 systemd unit |
| MySQL | `gg-mysql-1` | `docker run` | 3306 | `root` / `123456`；默认库 `tdpub` |
| Redis | `gg-redis-1` | `docker run` | 6379 | password 为空 |
| Minio | `gg-minio-1` | `docker run` | 9000 / 9001 | `admin` / `admin12345678` |
| InfluxDB | `gg-infulxdb` | `docker run` | 8086 | `admin` / `admin@123`；token `abc123123123abc`；org/bucket `fit` / `sdv` |
| Elasticsearch | `gg-es` | `docker run` | 9201 | security `disabled` |
| Tika | `gg-tika` | `docker run` | 9998 | 无 |
| OnlyOffice | `gg-onlyoffice-hack` | `docker run` | 8991 | `JWT_ENABLED=false` |
| Meilisearch | `gg-meilisearch-1` | `docker run` | 7700 | `MEILI_MASTER_KEY=meilisearch1234567` |
| MQTT | `gmqtt` | 手动安装 / 进程服务 | 1883 | 历史文档只记录依赖来源，现场形态可能不同 |

排查老现场时，后端优先看 `systemctl status smart-doc-vault.service` 和 `journalctl -u smart-doc-vault.service`；依赖服务优先用 `docker ps`、`docker logs <容器名>` 查看。

当前推荐新项目统一使用 [Linux / Docker 离线包](#_6-linux-docker-离线包)。只有在追溯老现场、对比旧配置、查历史安装脚本或迁移旧项目时，才需要参考 `xc-install`。

:::

## 7. Windows 离线包

Windows 离线包以 `sdv-windows` 仓库为准。稳定线使用 `build-windows-sdv-fdmjj.sh`，产物后缀为 `.zip`，内部主要是 `sdv-test` 运行目录。

Windows 离线包也推荐在 Linux 构建机上打，配合 Wine 做 Electron Windows 客户端交叉编译。这样前端 Web、Electron Windows 客户端、Electron Linux 客户端、Go Windows 后端和压缩上传都能在同一台构建机完成。Windows 机器主要用于最终安装验收，不建议把它作为唯一构建环境。

包内常见内容：

| 内容 | 说明 |
| --- | --- |
| `SDV/smart-doc-vault.exe` | 后端主程序 |
| `SDV/config/dist/` | 前端 Web 静态文件和客户端下载文件 |
| `serviceMonitor.exe` | 智档宝运行监控 |
| `install.bat` / `uninstall.bat` | 一键安装和卸载脚本 |
| `*.bat` 服务脚本 | MySQL、Redis、Minio、EMQX、Tika、ES、主程序等服务注册脚本 |
| `DEPLOY.md` | Windows 部署说明 |
| `Mysql`、`Redis`、`Minio`、`Influxdb`、`Emqx`、`es`、`tika` | 本地依赖服务目录 |
| 客户端 exe、打印服务安装包 | 现场客户端和打印能力分发 |

Linux + Wine 构建 Windows 离线包流程：

1. 从 `fit-archive/fdmjj` 拉取 `fit-archive-ng`。
2. 准备 Node.js、pnpm、Go、just、Wine、7z/zip、upx 和发布上传工具。
3. 执行 Web 构建，并执行 Electron Windows / Linux 客户端构建。
4. 从 `fit-archive/fdmjj` 拉取 `smart-doc-vault`。
5. 设置 `GOOS=windows` 构建后端 exe。
6. 拉取并构建 `windows-service-monitor`。
7. 将后端 exe、SQL、前端 dist、客户端安装包、打印服务和监控工具复制到 `sdv-test`。
8. 压缩为 `sdv-windows-<backend_hash>-<frontend_hash>-<timestamp>.zip`。
9. 上传主包、README、前端独立包和后端独立包。

Windows 验收机建议：

| 项目 | 建议 |
| --- | --- |
| 操作系统 | Windows 10 / Windows Server 2019 及以上 |
| 权限 | 管理员权限 |
| 内存 | 最低 8GB，推荐 16GB |
| 磁盘 | 至少 50GB 可用空间 |
| 网络 | 能访问现场内网设备和本机服务端口 |

Windows 安装验证：

1. 解压 Windows 离线包到纯英文或现场约定目录。
2. 以管理员权限运行 `install.bat`。
3. 通过 `services.msc` 或 `sc query` 确认服务已注册并启动。
4. 打开 `serviceMonitor.exe`，确认基础服务状态。
5. 访问智档宝页面，执行登录、查询、新建或现场核心业务动作。
6. 验证客户端 exe、打印服务、文档预览和全文搜索。

Windows 主要服务、端口和默认账号 / Token：

| 服务 | Windows 服务名 | 常见端口 | 作用 | 默认账号 / Token |
| --- | --- | --- | --- | --- |
| 主应用服务 | `SDV` | 8080 | 智档宝后端 | 无 |
| MySQL | `SDVMysql` | 3306 | 关系数据库 | `root` / `123456` |
| Redis | `SDVRedis` | 6379 | 缓存 | password 为空 |
| Minio | `SDVMinio` | 9000 / 9001 | 对象存储 | `admin` / `admin123456`；bucket `fit` |
| EMQX | `SDVEmqx` | 1883 / 8083 / 8084 | MQTT 消息服务 | Dashboard `admin` / `public`；Management API `admin` / `public`；MQTT 匿名连接 |
| InfluxDB | `SDVInfluxDB` | 8086 | 时序数据库 | `admin` / `12345678`；token `abc123123123abc`；org/bucket `fit` / `sdv` |
| Tika | `SDVTika` | 9998 | 文档解析 | 无 |
| DocumentConvert | `SDVDocumentConvert` | 7010 | 文档格式转换 | 无 |
| Elasticsearch | `elasticsearch-service-x64` | 9200 | 全文搜索 | 按包内配置 |
| Face | `SDVFace` | 按现场配置 | 离线人脸识别 | 无 |

## 8. 环境配置细节

打包和分发要区分三类配置：

| 类型 | 示例 | 处理方式 |
| --- | --- | --- |
| 构建配置 | GitLab SSH 地址、目标架构、构建脚本参数 | 可以写入脚本或 README |
| 运行配置 | 服务端口、数据目录、JVM 内存、Docker Compose 服务 | 可以写入部署文档，发布前按现场调整 |
| 密钥配置 | GitLab token、钉钉 webhook、AI API key、数据库初始口令、对象存储口令 | 不写入文档和仓库，使用环境变量、CI Secret 或现场密钥表 |

Linux 数据目录通常由安装脚本创建，至少包括数据库、缓存、对象存储、时序数据库、搜索引擎和业务文件存储目录。Windows 数据目录在 `sdv-test` 下随服务目录组织，例如 `Mysql\data`、`Redis\data`、`Minio\data`、`Influxdb\data`、`Emqx\data`、`es\...\data`。

生产或客户现场需要检查：

* 不需要外部访问的端口不要暴露到公网或客户办公网。
* Windows 服务安装路径要固定，避免解压目录移动后服务路径失效。
* Elasticsearch、JVM、MySQL、Redis 的内存配置要按机器规格调整。
* 离线包 README 要记录包名、构建时间、前端 hash、后端 hash、目标架构和更新说明。

## 9. 发布前检查清单

| 检查项 | Linux | Windows |
| --- | --- | --- |
| 包名包含前后端 hash | 是 | 是 |
| README 写入版本记录 | 是 | 是 |
| 能从版本搜索反查仓库 | 是 | 是 |
| 能在干净机器安装 | 是 | 是 |
| 主要服务能启动 | `docker compose ps` | `sc query` / 运行监控 |
| Web 能登录 | 是 | 是 |
| 核心业务能执行 | 是 | 是 |
| 默认密钥已替换或已标注内网限制 | 是 | 是 |
| 上传发布目录 | 智档宝 Linux 发布目录 | 智档宝 Windows 发布目录 |

发布记录至少包含：

* 包名。
* 架构或操作系统。
* 构建时间。
* `fit-archive-ng` hash。
* `smart-doc-vault` hash。
* 构建人。
* 验收机器。
* 验收结果。

## 10. 常见问题

**包能启动，但现场不知道是哪版代码**

先看包名中的两个 hash，再到版本搜索里查 `飞度一体化平台` 或对应版本号。如果搜索不到，回到发布 README 和 GitLab 仓库确认是否漏写版本记录。

**Linux 上某个架构能打包，另一个架构失败**

先确认后端 Go 目标架构、Docker 基础镜像、前端依赖和离线 Docker 组件是否都支持该架构。`loongarch` 优先使用原生构建和原生验收。

**Windows 安装后服务启动失败**

优先检查管理员权限、端口占用、解压路径、服务路径和数据目录。MySQL、Elasticsearch、InfluxDB 首次启动时间较长，不能只看脚本瞬时返回。

**只需要更新前端或后端**

优先使用独立包，但必须记录对应 hash。只替换前端时要确认后端 API 兼容；只替换后端时要确认数据库迁移、配置文件和前端页面兼容。

---

---
url: /wiki/sdv/backup-migration.md
---

# 5-备份迁移

智档宝的备份迁移不是复制一个程序目录。一次可回滚的迁移至少要同时处理业务数据库、对象文件、搜索索引、配置文件、版本信息和服务清单。

这篇文档面向实施、运维和研发，用于现场升级、换机、系统重装、Windows / Linux 形态切换和老现场迁移。

![智档宝备份迁移](/illustrations/sdv-backup-migration-xiaohei.png)

## 1. 这篇文档解决什么

| 场景 | 目标 |
| --- | --- |
| 升级前 | 保留升级前数据和版本，升级失败时能回退 |
| 换机前 | 把旧机器上的业务数据、文件、配置和版本迁到新机器 |
| 磁盘风险操作前 | 避免分区、扩容、重装、杀毒误删导致数据不可恢复 |
| Windows / Linux 形态切换 | 确认数据对象、服务组件和路径差异 |
| 现场重装前 | 先拿到可验证备份，再处理系统环境 |

备份迁移的核心判断是：新环境能否复现旧环境的业务状态，并且旧环境还能在回滚窗口内重新接管。

## 2. 备份对象

| 对象 | 常见位置 / 组件 | 备份方式 | 影响 |
| --- | --- | --- | --- |
| 业务数据库 | MySQL，默认库 `tdpub` | `mysqldump` 导出 SQL | 登录、档案、库房、权限、流程、配置 |
| 对象文件 | Minio bucket `fit` 或本地文件目录 | Minio mirror / 停写后复制数据目录 | 附件、扫描件、图片、电子档案 |
| 搜索索引 | Elasticsearch | 快照或重建前保留原索引数据 | 全文搜索、关键字检索 |
| 时序数据 | InfluxDB | 导出或复制数据目录 | 温湿度、环境控制和设备历史曲线 |
| 消息与设备配置 | EMQX 配置、用户、规则、topic 约定 | 复制配置和数据目录 | RFID、环境控制、设备联动 |
| 运行配置 | `config.yaml`、`.env`、`docker-compose.yml`、服务脚本 | 复制配置文件和安装目录 | 端口、路径、数据库连接、现场参数 |
| 程序版本 | 前端 hash、后端 hash、包名、README、安装脚本 | 记录包名和 `git hash` | 追溯代码、定位问题、复现版本 |
| 本地服务 | 打印、客户端、监控、门口机、设备接入程序 | 复制配置、安装包和服务信息 | 打印、预览、RFID、现场设备 |

只备份程序目录通常不够。程序可以从发布包恢复，业务数据和现场文件丢失后很难重建。

## 3. 备份原则

1. 先进入维护窗口，停止新增写入，至少要避免用户继续上传、修改档案或执行设备业务。
2. 先备份数据，再动程序和环境。
3. 记录旧环境的包名、前端 hash、后端 hash、部署形态、操作系统、CPU 架构和主要端口。
4. 保留旧发布包和安装脚本，不只保留运行目录。
5. 备份完成后必须抽样验证可读性，例如 SQL 能导入、文件能列出、压缩包能解压。
6. 不把截图当备份。截图只能辅助说明现场状态，不能恢复系统。

## 4. 通用命令

下面命令参考 [常用维护命令](/wiki/maintenance-commands) 的写法。默认值按智档宝常见现场编写，执行前先确认实际账号、端口、容器名、安装目录和部署形态。

常见默认值：

| 服务 | 常见默认值 |
| --- | --- |
| MySQL | 用户 `root`，密码 `123456`，库名 `tdpub`，Linux Docker 端口常见 `3307`，Windows 常见 `3306` 或现场配置端口 |
| Minio | endpoint `http://127.0.0.1:9000`，用户 `admin`，密码 `admin123456`，bucket `fit` |
| InfluxDB | org `fit`，bucket `sdv`，token `abc123123123abc`，端口 `8086` |
| EMQX | Dashboard `admin` / `public`，MQTT 常见匿名连接 |

先创建带时间戳的备份目录：

::: code-group

```bash [Linux]
TS=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="$PWD/sdv-backup-$TS"
mkdir -p "$BACKUP_DIR"/{mysql,minio,influxdb,config,versions,logs}
```

```powershell [Windows PowerShell]
$TS = Get-Date -Format 'yyyyMMdd-HHmmss'
$BACKUP_DIR = Join-Path (Get-Location) "sdv-backup-$TS"
New-Item -ItemType Directory -Force `
  "$BACKUP_DIR\mysql", "$BACKUP_DIR\minio", "$BACKUP_DIR\influxdb", "$BACKUP_DIR\config", "$BACKUP_DIR\versions", "$BACKUP_DIR\logs" | Out-Null
```

:::

备份 MySQL：

::: code-group

```bash [Linux]
mysqldump \
  -h 127.0.0.1 \
  -P 3307 \
  -uroot \
  -p123456 \
  --single-transaction \
  --routines \
  --triggers \
  --events \
  --default-character-set=utf8mb4 \
  tdpub > "$BACKUP_DIR/mysql/tdpub.sql"
```

```powershell [Windows PowerShell]
.\mysqldump.exe `
  -h 127.0.0.1 `
  -P 3306 `
  -uroot `
  -p123456 `
  --single-transaction `
  --routines `
  --triggers `
  --events `
  --default-character-set=utf8mb4 `
  tdpub | Out-File -Encoding utf8 "$BACKUP_DIR\mysql\tdpub.sql"
```

:::

恢复 MySQL：

::: code-group

```bash [Linux]
mysql \
  -h 127.0.0.1 \
  -P 3307 \
  -uroot \
  -p123456 \
  --default-character-set=utf8mb4 \
  tdpub < "$BACKUP_DIR/mysql/tdpub.sql"
```

```powershell [Windows PowerShell]
Get-Content "$BACKUP_DIR\mysql\tdpub.sql" `
  | .\mysql.exe -h 127.0.0.1 -P 3306 -uroot -p123456 --default-character-set=utf8mb4 tdpub
```

:::

备份 Minio bucket：

::: code-group

```bash [Linux]
mc alias set sdv-minio http://127.0.0.1:9000 admin admin123456
mc mirror --overwrite sdv-minio/fit "$BACKUP_DIR/minio/fit"
```

```powershell [Windows PowerShell]
.\mc.exe alias set sdv-minio http://127.0.0.1:9000 admin admin123456
.\mc.exe mirror --overwrite sdv-minio/fit "$BACKUP_DIR\minio\fit"
```

:::

恢复 Minio bucket：

::: code-group

```bash [Linux]
mc mirror --overwrite "$BACKUP_DIR/minio/fit" sdv-minio/fit
```

```powershell [Windows PowerShell]
.\mc.exe mirror --overwrite "$BACKUP_DIR\minio\fit" sdv-minio/fit
```

:::

备份 InfluxDB：

::: code-group

```bash [Linux]
influx backup \
  --host http://127.0.0.1:8086 \
  --bucket sdv \
  --org fit \
  --token abc123123123abc \
  "$BACKUP_DIR/influxdb"
```

```powershell [Windows PowerShell]
.\influx.exe backup `
  --host http://127.0.0.1:8086 `
  --bucket sdv `
  --org fit `
  --token abc123123123abc `
  "$BACKUP_DIR\influxdb"
```

:::

压缩备份目录：

::: code-group

```bash [Linux]
tar -czf "${BACKUP_DIR}.tar.gz" -C "$(dirname "$BACKUP_DIR")" "$(basename "$BACKUP_DIR")"
sha256sum "${BACKUP_DIR}.tar.gz" > "${BACKUP_DIR}.tar.gz.sha256"
```

```powershell [Windows PowerShell]
Compress-Archive -Path "$BACKUP_DIR" -DestinationPath "$BACKUP_DIR.zip" -Force
Get-FileHash "$BACKUP_DIR.zip" -Algorithm SHA256 | Out-File "$BACKUP_DIR.zip.sha256.txt"
```

:::

恢复类命令会覆盖目标数据。恢复前先停止业务写入，并再次备份当前新环境数据。

## 5. Linux 专用

Linux Docker 形态优先参考 [4-打包分发](/wiki/sdv/packaging-distribution#_6-linux-docker-离线包) 里的服务表。容器名按现场调整，常见为 `sdv-mysql`、`sdv-minio`、`sdv-influxdb`、`sdv-emqx`、`sdv-es`。

记录 Docker 状态和版本：

```bash
docker compose ps > "$BACKUP_DIR/versions/docker-compose-ps.txt"
docker images > "$BACKUP_DIR/versions/docker-images.txt"
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}' > "$BACKUP_DIR/versions/docker-ps.txt"
cp docker-compose.yml "$BACKUP_DIR/config/" 2>/dev/null || true
cp .env "$BACKUP_DIR/config/" 2>/dev/null || true
```

容器内执行 MySQL 备份：

```bash
docker exec sdv-mysql sh -c 'mysqldump -uroot -p123456 --single-transaction --routines --triggers --events --default-character-set=utf8mb4 tdpub' \
  > "$BACKUP_DIR/mysql/tdpub.sql"
```

容器内恢复 MySQL：

```bash
docker exec -i sdv-mysql sh -c 'mysql -uroot -p123456 --default-character-set=utf8mb4 tdpub' \
  < "$BACKUP_DIR/mysql/tdpub.sql"
```

如果宿主机没有 `influx` 命令，但容器内有，可以在容器内备份后复制出来：

```bash
docker exec sdv-influxdb influx backup \
  --bucket sdv \
  --org fit \
  --token abc123123123abc \
  /tmp/influx-backup

docker cp sdv-influxdb:/tmp/influx-backup "$BACKUP_DIR/influxdb"
docker exec sdv-influxdb rm -rf /tmp/influx-backup
```

备份配置和安装脚本：

```bash
cp -a ./config "$BACKUP_DIR/config/" 2>/dev/null || true
cp -a ./scripts "$BACKUP_DIR/config/" 2>/dev/null || true
cp -a ./install*.sh "$BACKUP_DIR/config/" 2>/dev/null || true
cp -a ./README* "$BACKUP_DIR/versions/" 2>/dev/null || true
```

如果现场没有配置 `mc`，Minio、Elasticsearch、InfluxDB、EMQX 这类数据目录只能在维护窗口复制实际 volume 目录。不要在业务持续上传时直接复制对象目录，否则容易出现数据库记录和文件不一致。

## 6. Windows 专用

Windows 形态优先参考 [4-打包分发](/wiki/sdv/packaging-distribution#_7-windows-离线包) 里的服务表。备份前先通过 `serviceMonitor.exe`、`services.msc` 或安装脚本停止智档宝和依赖服务，避免文件复制过程中仍在写入。

建议先进入运行目录，常见为 `sdv-test`：

```powershell
cd C:\Users\pc\Documents\sdv-test
```

记录 Windows 服务列表：

```powershell
sc.exe query state= all > "$BACKUP_DIR\versions\service-list.txt"
Get-Service | Out-File "$BACKUP_DIR\versions\powershell-service-list.txt"
```

备份运行目录里的配置、脚本和本地工具：

```powershell
Copy-Item .\SDV\config -Destination "$BACKUP_DIR\config\SDV-config" -Recurse -Force -ErrorAction SilentlyContinue
Copy-Item .\*.bat -Destination "$BACKUP_DIR\config\" -Force -ErrorAction SilentlyContinue
Copy-Item .\DEPLOY.md -Destination "$BACKUP_DIR\versions\" -Force -ErrorAction SilentlyContinue
Copy-Item .\serviceMonitor.exe -Destination "$BACKUP_DIR\versions\" -Force -ErrorAction SilentlyContinue
```

需要整体保留现场运行目录时，可以复制或压缩整个安装目录。目录体积通常较大，里面可能包含数据库和对象文件，复制前必须停止服务。

```powershell
Compress-Archive -Path .\* -DestinationPath "$BACKUP_DIR\windows-runtime.zip" -Force
```

Windows 迁移时要特别注意服务路径。新机器上的盘符、目录名、空格和权限变化，都会导致服务注册成功但实际启动失败。

## 7. 迁移流程

1. 盘点旧现场：记录部署形态、操作系统、CPU 架构、包名、前后端 hash、服务端口和数据规模。
2. 做完整备份：数据库、文件、索引、配置、版本信息和本地服务一起备份。
3. 准备新环境：按目标形态安装同版本或目标版本离线包。
4. 停止新环境服务：避免空库启动后写入初始化数据干扰恢复。
5. 恢复数据：先恢复 MySQL，再恢复文件、索引、时序数据、设备配置和运行配置。
6. 启动依赖服务：数据库、缓存、对象存储、搜索、解析、消息服务先稳定。
7. 启动后端和前端：确认后端能连接所有依赖，前端能正常登录。
8. 做业务验证：登录、档案查询、文件预览、上传、全文搜索、设备联动逐项验证。
9. 切换访问入口：切换 IP、域名、网关、浏览器收藏或现场大屏入口。
10. 保留旧环境：旧机器在回滚窗口内只读保留，不立即删除数据。

迁移不是“复制完成就上线”，而是“验证通过后切换”。切换前必须明确旧环境能否快速恢复接管。

## 8. 验证清单

| 能力 | 验证动作 | 通过标准 |
| --- | --- | --- |
| 登录和权限 | 使用管理员和普通用户登录 | 能登录，菜单和库房权限符合旧环境 |
| 档案查询 | 查询旧档案、库房、位置和借阅状态 | 关键数据数量和状态一致 |
| 文件预览 | 打开历史附件、扫描件和图片 | 能预览、下载，路径不报错 |
| 文件上传 | 新上传一个测试文件 | 数据库有记录，对象存储有文件 |
| 全文搜索 | 搜索历史关键字和新文件 | 旧索引可用或重建后可搜到 |
| 环境控制历史 | 查看温湿度或设备历史曲线 | 历史数据连续，时间范围正确 |
| RFID / 设备 | 执行读卡、盘点、门口机或设备联动 | MQTT、设备程序和业务状态一致 |
| 打印 | 打印测试单据或标签 | 模板、打印机和本地服务正常 |
| 版本追溯 | 核对前端 hash、后端 hash 和包名 | 能反查到对应仓库和提交 |

验证结果建议写进现场记录。失败项要记录时间、现象、日志位置和当时使用的备份包。

## 9. 回滚原则

* 新环境未验证完成前，不删除旧环境数据。
* 回滚时先停止新环境服务，再把访问入口切回旧环境。
* 如果新环境已经产生新业务数据，要记录新旧环境的数据时间差，不要直接覆盖。
* 回滚后保留失败现场的日志、配置和导入记录，方便研发定位。

## 10. 常见问题

| 问题 | 常见原因 | 处理方向 |
| --- | --- | --- |
| 复制了程序但登录后没有数据 | 只复制了前后端程序，没有恢复 MySQL | 导入 `tdpub` 数据库并核对配置 |
| 档案能查到但文件打不开 | Minio / 文件目录未迁移，或 bucket / 路径不一致 | 核对对象文件、bucket、后端文件配置 |
| 文件能打开但搜不到 | Elasticsearch 未恢复或未重建索引 | 恢复索引或执行重建 |
| Windows 服务注册后启动失败 | 服务路径、权限、端口或依赖目录变化 | 查 `services.msc`、事件查看器和服务脚本 |
| Linux 容器启动但数据是空的 | volume 没挂到旧数据目录，或恢复到了错误路径 | 查 `docker inspect`、compose volume 和实际目录 |
| 设备业务正常页面不刷新 | MQTT / EMQX、设备接入程序或前端缓存异常 | 查 EMQX、设备日志、浏览器缓存和接口返回 |

备份迁移的文档粒度应该比安装文档更细，因为它处理的是现场已有数据。新装失败可以重装，迁移失败可能直接影响业务连续性。

---

---
url: /wiki/product-denserack.md
---

# 飞度密集架

飞度密集架产品线指带屏幕的智能密集架，用于沉淀屏幕端、固定列 / 移动列、更新服务、镜像、设备联动和智档宝集成相关资料。

## 图例

## 当前定位

| 方向 | 说明 |
| --- | --- |
| 屏幕端主程序 | 固定列大屏、移动列小屏、Electron / Web 前端、设备状态展示和本地交互 |
| 更新与分发 | 固定列主程序更新服务、更新中心、安装镜像和交付脚本 |
| 平台交互 | 智档宝向屏幕端下发开架、取档、盘点等任务，移动列屏幕端回传状态、执行结果和异常信息 |
| 业务集成 | 智档宝前后端中的飞度密集架库区、架体、开架、状态回传和任务联动 |
| 设备控制 | TCP Client、USB Serial、HTTP / WS 等协议接入与现场联调 |

## 核心仓库

| 仓库 | 作用 | 结构观察 |
| --- | --- | --- |
| `fit-archive/fdmjj/fit-denserack` | 固定列主程序 | `electron`、`src`、`resources`、`docs`、`public`，偏终端应用 |
| `fit-archive/fdmjj/fit-denserack-updater` | 固定列更新服务 | `main.go`、`system`、`dist`，偏本地更新进程 |
| `fit-archive/fdmjj/fit-denserack-update-center` | 更新中心 | 用于固定列程序版本管理和更新发布 |
| `fit-archive/fdmjj/fit-mjj-iso` | 固定列镜像 | `airootfs`、`packages.x86_64`、`profiledef.sh`，偏系统镜像构建 |
| `fit-archive/fdmjj/smart-doc-vault` | 智档宝密集架后端集成 | `mjj`、`mjjs`、`iot`、`iot_plugin`、`wsocket`、`service` |
| `fit-archive/fdmjj/fit-archive-ng` | 智档宝密集架前端 / 桌面侧 | `src`、`src-tauri`、`electron`、`docs` |

## 建议目录

```text
飞度密集架
├─ 0-总览
├─ 1-产品视图
├─ 2-终端主程序
├─ 3-设备协议
├─ 4-更新与镜像
├─ 5-智档宝集成
├─ 6-现场部署
└─ 7-调试排障
```

## 先补哪些

| 优先级 | 文档 | 内容 |
| --- | --- | --- |
| P0 | 设备协议 | FD-01、FD-06、TCP Client、USB Serial、HTTP / WS 的统一口径 |
| P0 | 终端主程序 | 固定列程序启动、配置、更新、日志和常见问题 |
| P1 | 更新与镜像 | ISO 构建、更新服务、版本发布流程 |
| P1 | 智档宝集成 | 库区、架体、开架、任务、状态回传的边界 |

## 图形化概念

### XORG （X11，X Server） -> Wayland

* 客户端 - 服务端（渲染） 分离 -> 基于SSH协议的 X11 转发
* XWayalnd
  -> 性能开销 历史bug 驱动问题 xorg config
* https://wiki.archlinuxcn.org/wiki/Xorg
* https://wiki.archlinuxcn.org/wiki/Wayland
* DISPLAY=:0 / WAYLNAD\_DISPLAY=wayland-1

为什么不用XORG ？ -> 显卡驱动兼容 老机器...屏幕撕裂（intel -> xrog-intel / mesa）

### DISPLAY ENV/ DISPLAY Manager / Window Manager / Compoister

* https://wiki.archlinux.org/title/Desktop\_environment
* https://wiki.archlinux.org/title/Display\_manager
* https://wiki.archlinux.org/title/Greetd
* OpenBOX/i3/XFCE/KDE/KYLINDE/GNOME/META/SWAY/
* SDDM/GDM/LigthDM.... greet
* box,KWM, KWIN Mutter，i3

### 客户端

* Electron Wayland

### 输入法

* 多文 商业 https://www.dwinput.com/

* 麒麟 FCITX5 https://gitee.com/openkylin/kylin-virtual-keyboard

* https://gitlab.singzer.cn/fit-archive/fdmjj/dwime-wayland-bridge

### 虚拟显示屏/显示屏配置/显卡...

### 网络设置

```bash
nm-connection-editor
```

### 触摸

* sway -> 屏幕旋转后触摸没旋转 -> 改配置ok 但是容易失效 -> 改sway 源码.. -> 上游修复了
* 网络设置工具 -> gtk 写的， 触摸不友好 -> 修改了 Ipv4代理配置的方法 （下拉框改列表）

### PulseAudio -> Pipewire (声音)

* https://wiki.archlinuxcn.org/zh-mo/PulseAudio
* https://wiki.archlinuxcn.org/wiki/PipeWire

```bash
pavucontrol
```

### 与固定列主板通讯

* 账号系统
* 架体信息
* WOL 网络唤醒

### 与平台通讯 （选配）

> 见智档宝-档案管理-库区章节

### TTS / ASR

#### TTS 合成

* MPV -> 播放服务
* https://github.com/xeden3/MSSpeechServer / https://gitlab.singzer.cn/fit-archive/fdmjj/msspeechserver - 弃用 - wine/docker -> msiEXE ... -> HTTP-SERVER -> 性能差 开销大 不稳定 日志文件大
* https://github.com/huakunyang/SummerTTS  -> http://172.16.146.138:8080/
* 其他语言 预合成 HK -> 讯飞的...

#### ASR 识别

* https://github.com/huakunyang/SummerASR - WAV一段一段 无法流式
* https://gitlab.singzer.cn/fit-archive/fdmjj/asr-service / https://gitlab.singzer.cn/fit-archive/fdmjj/asr-onnx-service -> ws ... http://172.16.146.138:8777/
* 文本判断 （研究nlp 语义分析 https://gitlab.singzer.cn/fit-archive/fdmjj/nlu-service）
* 硬件方案 -> 交互

### 网页远程 （8520）

* swayvnc （wayland） -> vnc协议 -> novnc -> web

```bash
?
```

* reframe （kms） -> vnc协议 -> novnc -> web (gpu)

```bash
sudo systemctl enable --now reframe-server@example.service reframe@example.socket
```

### 人脸识别

* https://github.com/icepie/FaceSimilarityService.git - 5000 端口

## 镜像打包

> 基于 archiso 工具打包

* https://gitlab.singzer.cn/fit-archive/fdmjj/fit-mjj-iso

https://wiki.archlinuxcn.org/wiki/Archiso -> https://github.com/gsanhueza/ArchISOMaker -> https://gitlab.singzer.cn/fit-archive/fdmjj/fit-mjj-iso

* 滚动： 注意上游的变化 - 考虑版本兼容
* 固定： https://archive.archlinux.org/repos/  archiso 固定 - 国内镜像源丢
* 自建源（运维）

## 镜像安装

* install.sh (.bashrc 默认检测到 tty1)
* install.log (报错)
* 安装过程 右边显示日志 -> tmux

## 架构

* ArchLinux Base
* 两个网口
  * 局域网
  * 板子通讯 - 172.16.10.10/24(固定列) - 172.16.10.11/24（板子）
* 默认账号密码
  * gg / 10010
  * root / 10086

---

---
url: /wiki/product-dust-table.md
---

# 除尘台

除尘台产品线用于沉淀除尘台主控板、LED 板、固件烧录、指令协议、标签数据和现场调试资料。

## 当前定位

| 方向 | 说明 |
| --- | --- |
| 主控板 | 负责除尘台核心控制逻辑、设备状态和外设联动 |
| LED 板 | 负责灯光、提示、显示或局部交互能力 |
| 固件工程 | 以 PlatformIO 工程为主，包含 `include`、`lib`、`src`、`test` |
| 指令与标签 | 指令手册、层架标签、数据表等交付资料需要单独归档 |

## 核心仓库

| 仓库 | 作用 | 结构观察 |
| --- | --- | --- |
| `file-cabinet/feidu_dust_main_board` | 除尘台主控板早期工程 | `include`、`lib`、`src`、`test`、`platformio.ini`、除尘台指令手册 |
| `file-cabinet/feidu_dust_main_board_ng1` | 主控板 NG1 | PlatformIO 工程，偏新版本主控固件 |
| `file-cabinet/feidu_dust_main_board_ng1.1` | 主控板 NG1.1 | PlatformIO 工程，含标签表和数据表 |
| `file-cabinet/feidu_dust_led` | 除尘台 LED 板 | `image`、`include`、`lib`、`src`、`README.pdf`、指令手册 |
| `file-cabinet/test` | 除尘台项目测试 | 用于项目测试或临时验证 |

## 建议目录

```text
除尘台
├─ 0-总览
├─ 1-硬件组成
├─ 2-主控板固件
├─ 3-LED 板固件
├─ 4-指令协议
├─ 5-烧录与升级
├─ 6-标签与数据
└─ 7-现场调试
```

## 先补哪些

| 优先级 | 文档 | 内容 |
| --- | --- | --- |
| P0 | 指令协议 | 除尘台指令手册、控制命令、状态返回和异常码 |
| P0 | 烧录与升级 | PlatformIO 环境、固件编译、串口烧录、版本确认 |
| P1 | 主控板固件 | 主控板版本差异、配置项、常见接线 |
| P1 | LED 板固件 | LED 板通信、显示状态和联调步骤 |

---

---
url: /wiki/product-iot-devices.md
---

# 物联网设备

物联网设备产品线用于沉淀网关、传感器、LoRaWAN、485 设备、软网关、设备发现、OTA 和现场联调资料。

## 当前定位

| 方向 | 说明 |
| --- | --- |
| 网关 | POE 网关、RK3506 网关、软网关等设备接入入口 |
| 传感器 | 空气质量、温湿度、漏水、LoRaWAN 传感器等 |
| 设备协议 | 485、UDP、HTTP、MQTT、LoRaWAN、设备发现和数据解析 |

## 核心仓库

| 仓库 | 作用 | 结构观察 |
| --- | --- | --- |
| `IOT-FIRMWARE/feidu-poe-gateway-lite-2` | POE 网关 Lite2 | PlatformIO 工程，含 485、OTA、设备发现和调试脚本 |
| `IOT-FIRMWARE/feidu-poe-gateway-pro` | POE 网关 Pro | 偏除湿机控制 |
| `IOT-FIRMWARE/feidu_poe_air_sensor_dev0.1` | 空气传感器 | PlatformIO 工程，含 OTA、设备发现、位置信息 |
| `IOT-FIRMWARE/esp-32-lorawan-sensors` | LoRaWAN 传感器 | 含烧录包、设备批量添加、OTA、环境报告 |
| `IOT-FIRMWARE/gateway-screen` | 网关屏 / 复合设备 | 驱鼠、空气质量、空调控制、温湿度选择器 |
| `IOT-FIRMWARE/rk3506_gateway` | RK3506 网关 | `cmd`、`docs`、`hardware`、`internal`、`tools`，偏 Linux 网关 |
| `fit-archive/yd/soft-gateway` | 软网关 | Python / Go / TS 多实现，用于数据解析和转发 |
| `fit-archive/dcvm-device-bridge` | 设备桥接 | 设备与业务系统之间的桥接层 |
| `fit-archive/device-debug-web` | 设备调试 Web | 现场设备协议和接口调试 |
| `fit-archive/virtual-device-builder` | 虚拟设备 | 用于模拟设备和联调验证 |

## 建议目录

```text
物联网设备
├─ 0-总览
├─ 1-网关
├─ 2-传感器
├─ 3-设备协议
├─ 4-软网关
├─ 5-OTA 与烧录
├─ 6-设备调试
└─ 7-虚拟设备
```

## 先补哪些

| 优先级 | 文档 | 内容 |
| --- | --- | --- |
| P0 | 网关总览 | POE 网关、RK3506、软网关的适用场景和差异 |
| P0 | 设备协议 | 485、UDP、HTTP、MQTT、LoRaWAN 的统一入口和调试方式 |
| P1 | OTA 与烧录 | PlatformIO、烧录包、批量升级和版本确认 |
| P1 | 设备调试 | device-debug-web、虚拟设备、现场联调流程 |

---

---
url: /wiki/dev-debug.md
---

# 开发调试

开发调试涵盖远程访问、环境搭建和工具配置，帮助研发不在现场时也能高效工作。

## 章节

| 章节 | 说明 |
| --- | --- |
| [概念入门](/wiki/concepts-basics/) | 软件运行原理、操作系统与处理器架构、网络和常见协议 |
| [远程调试](/wiki/remote-debugging) | 远程访问现场服务器、工控机、Web 控制台 |
| [远程控制](/wiki/remote-control) | 远程桌面（向日葵/ToDesk/AnyDesk/RDP/VNC/RustDesk）+ 远程终端（SSH/ttyd/串口） |
| [端口转发](/wiki/port-forwarding) | 临时暴露指定端口（frpc / GOST / SSH / 系统自带） |
| [设备组网](/wiki/device-networking) | 长期多设备互通（ZeroTier / WireGuard） |
| [USB 映射](/wiki/usb-mapping) | 远程访问 USB 设备（VirtualHere / USB/IP） |
| [虚拟机](/wiki/virtual-machine) | 本地调试和环境模拟（VMware / VirtualBox / KVM / WSL2 / Docker） |

## 快速判断

```mermaid
flowchart LR
  A[开发调试需求] --> M{先了解基础?}
  M -->|概念不清| N[概念入门]
  A --> B{远程访问现场?}
  A --> C{本地环境模拟?}
  B --> D{长期还是临时?}
  D -->|长期| E[设备组网]
  D -->|临时| F{访问什么?}
  F -->|端口/Web| G[端口转发]
  F -->|USB 设备| H[USB 映射]
  F -->|图形界面| L[远程控制]
  C --> I{需要完整 OS?}
  I -->|是| J[虚拟机]
  I -->|否| K[容器 / WSL2]
```

---

---
url: /wiki/remote-debugging.md
---

# 远程调试

远程调试用于不在现场时访问服务器、工控机、边缘设备、Web 控制台、接口服务和远程控制。

![远程调试方案对比](/illustrations/remote-debug-overview.png)

## 怎么选

```mermaid
flowchart LR
  A[远程访问现场环境] --> B{长期使用?}
  B -->|是| C[设备组网]
  B -->|否| D[端口转发]
  C --> E[ZeroTier / WireGuard]
  D --> F[frpc / GOST / SSH]
  A --> G[USB 设备远程访问]
  G --> H[usbip]
  A --> I[远程控制]
  I --> J[远程桌面 / 远程终端]
```

::: tabs

\== 设备组网

适合长期维护、多设备互通、反复 SSH、远程桌面、Web 控制台和接口联调。

[查看设备组网](/wiki/device-networking)

\== 端口转发

适合临时排查，只访问一个端口、一个 Web 页面或一个 SSH 服务。

[查看端口转发](/wiki/port-forwarding)

\== USB 映射

适合远程访问现场 USB 设备（串口、加密狗、打印机等），通过网络转发 USB。

[查看 USB 映射](/wiki/usb-mapping)

\== 远程控制

适合远程操作现场设备：远程桌面（图形界面）和远程终端（命令行）。

[查看远程控制](/wiki/remote-control)

:::

## 快速判断

| 需求 | 推荐 |
| --- | --- |
| 多台设备互通 | 设备组网 |
| 长期维护现场服务器 | 设备组网 |
| 临时打开现场 Web | 端口转发 |
| 临时 SSH 到某台机器 | 端口转发 |
| 远程访问 USB 串口 / 加密狗 | USB 映射 |
| 远程操作设备（桌面/终端） | [远程控制](/wiki/remote-control) |
| 不确定方案 | 先端口转发验证，再决定是否组网 |

---

---
url: /wiki/port-forwarding.md
---

# 端口转发

端口转发只暴露指定端口，适合临时访问现场 SSH、Web、接口服务。

## 方案速查

```mermaid
flowchart LR
  A[需要访问现场端口] --> B{现场能主动连公网?}
  B -->|能| C[frpc / 反向 SSH]
  B -->|不能| D{已有 SSH 跳板?}
  D -->|有| E[SSH -L / -D]
  D -->|没有| F{操作系统?}
  F -->|Linux| G[iptables / socat]
  F -->|Windows| H[netsh portproxy]
  F -->|跨平台| I[GOST]
```

::: tabs

\== frpc / frps

适合现场机器在内网，但能主动连公网服务器的场景。当前 frps：

```text
www.singzer.cn:7001
```

\== GOST

适合本机临时 TCP/UDP 转发、链式代理和快速验证。

\== SSH

适合已经能登录跳板机的临时调试，不需要额外工具。

:::

## 下载

| 工具 | 下载入口 |
| --- | --- |
| frp | https://github.com/fatedier/frp/releases |
| GOST | https://github.com/go-gost/gost/releases |
| OpenSSH | https://learn.microsoft.com/windows-server/administration/openssh/openssh\_install\_firstuse |
| PuTTY | https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html |
| iptables / nftables | 系统自带 |
| socat | 系统包管理器 |
| netsh | Windows 自带 |

::: code-group

```bash [Debian / Ubuntu]
apt install openssh-client socat nginx
```

```bash [RHEL / CentOS]
yum install openssh-clients socat nginx
```

```bash [Arch Linux]
pacman -S openssh socat nginx
```

:::

## frpc

::: tabs

\== SSH

把现场机器 `22` 暴露到 `www.singzer.cn:16022`。

```toml
serverAddr = "www.singzer.cn"
serverPort = 7001

[[proxies]]
name = "ssh-device"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 16022
```

```bash
frpc -c ./frpc.toml
ssh root@www.singzer.cn -p 16022
```

\== Web

把现场机器 `8080` 暴露到 `www.singzer.cn:18080`。

```toml
serverAddr = "www.singzer.cn"
serverPort = 7001

[[proxies]]
name = "web-device"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8080
remotePort = 18080
```

访问：

```text
http://www.singzer.cn:18080/
```

\== 局域网设备

frpc 所在机器能访问 `192.168.10.50:80` 时，可以转发这台局域网设备。

```toml
serverAddr = "www.singzer.cn"
serverPort = 7001

[[proxies]]
name = "camera-web"
type = "tcp"
localIP = "192.168.10.50"
localPort = 80
remotePort = 18050
```

:::

## GOST

::: code-group

```bash [Web]
gost -L tcp://:18080/192.168.10.50:80
```

```bash [SSH]
gost -L tcp://:16022/192.168.10.50:22
```

```bash [UDP]
gost -L udp://:10053/192.168.10.1:53
```

```bash [SSH 链路]
gost -L tcp://:18080/192.168.10.50:80 -F sshd://user:pass@www.singzer.cn:22
```

:::

## SSH 转发

::: code-group

```bash [本地转发 -L]
ssh -N -L 18080:192.168.10.50:80 root@www.singzer.cn
```

```bash [远程转发 -R]
ssh -N -R 18080:127.0.0.1:8080 root@www.singzer.cn
```

```bash [SOCKS5 -D]
ssh -N -D 1080 root@www.singzer.cn
```

:::

`-R` 如果需要让外部访问服务器端口，服务器 sshd 可能需要：

```text
GatewayPorts yes
```

## 系统自带转发

不装任何第三方工具，直接用操作系统内核能力转发端口。

### iptables / nftables（Linux）

内核级 NAT 转发，性能最好，适合长期规则。

::: code-group

```bash [iptables DNAT]
# 开启内核转发
echo 1 > /proc/sys/net/ipv4/ip_forward

# 转发本机 18080 → 192.168.10.50:80
iptables -t nat -A PREROUTING -p tcp --dport 18080 -j DNAT --to-destination 192.168.10.50:80
iptables -t nat -A POSTROUTING -j MASQUERADE
```

```bash [nftables DNAT]
# 开启内核转发
echo 1 > /proc/sys/net/ipv4/ip_forward

# 转发本机 18080 → 192.168.10.50:80
nft add table ip nat
nft add chain ip nat prerouting { type nat hook prerouting priority -100 \; }
nft add chain ip nat postrouting { type nat hook postrouting priority 100 \; }
nft add rule ip nat prerouting tcp dport 18080 dnat to 192.168.10.50:80
nft add rule ip nat postrouting masquerade
```

```bash [本机端口重定向]
# 同机器 8080 → 80（不需要 ip_forward）
iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
```

:::

清除规则：

::: code-group

```bash [iptables]
iptables -t nat -D PREROUTING -p tcp --dport 18080 -j DNAT --to-destination 192.168.10.50:80
iptables -t nat -D POSTROUTING -j MASQUERADE
```

```bash [nftables]
nft delete table ip nat
```

:::

::: code-group

```bash [iptables-persistent (Debian/Ubuntu)]
apt install iptables-persistent
netfilter-persistent save
```

```bash [iptables-services (RHEL/CentOS)]
yum install iptables-services
service iptables save
systemctl enable iptables
```

```bash [nftables (systemd)]
nft list ruleset > /etc/nftables.conf
systemctl enable nftables
```

:::

### socat（Linux/macOS）

单命令 TCP/UDP 转发，适合临时验证，无配置文件。

::: code-group

```bash [TCP 转发]
socat TCP-LISTEN:18080,fork,reuseaddr TCP:192.168.10.50:80
```

```bash [UDP 转发]
socat UDP-LISTEN:10053,fork,reuseaddr UDP:192.168.10.1:53
```

```bash [本地端口映射]
socat TCP-LISTEN:80,fork,reuseaddr TCP:127.0.0.1:8080
```

:::

`Ctrl+C` 停止，后台运行加 `&` 或用 `nohup`。

### netsh（Windows）

Windows 内置端口映射，无需安装任何工具。

::: code-group

```cmd [添加转发]
netsh interface portproxy add v4tov4 listenport=18080 listenaddress=0.0.0.0 connectport=80 connectaddress=192.168.10.50
```

```cmd [查看规则]
netsh interface portproxy show all
```

```cmd [删除规则]
netsh interface portproxy delete v4tov4 listenport=18080 listenaddress=0.0.0.0
```

:::

```cmd
netsh advfirewall firewall add rule name="Port 18080" dir=in action=allow protocol=TCP localport=18080
```

删除规则：

```cmd
netsh advfirewall firewall delete rule name="Port 18080"
```

`netsh portproxy` 规则默认持久化，重启不丢失。

如需确认服务依赖 `IP Helper` 已启动：

```cmd
sc query iphlpsvc
sc config iphlpsvc start=auto
```

### SSH 内置（Windows 10+ / macOS / Linux）

系统自带 OpenSSH 客户端即可，无需 PuTTY 等工具。

::: code-group

```bash [Windows PowerShell]
# 确认 SSH 可用
ssh -V

# 本地转发
ssh -N -L 18080:192.168.10.50:80 root@www.singzer.cn
```

```bash [macOS / Linux]
ssh -N -L 18080:192.168.10.50:80 root@www.singzer.cn
```

:::

Windows 10/11 默认已装 OpenSSH，如未安装：

```powershell
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```

## 排查

::: code-group

```bash [frpc 日志]
journalctl -u frpc -f
```

```bash [本地端口]
ss -ltnp | grep ':8080'
```

```bash [外部验证]
nc -vz www.singzer.cn 16022
curl -I http://www.singzer.cn:18080/
```

:::

## 端口规划

| 用途 | 建议端口 |
| --- | --- |
| SSH | `16000-16999` |
| Web / HTTP | `18000-18999` |
| 数据库 | `19000-19999` |
| 临时调试 | `20000-20999` |

## 注意

* 只转发需要调试的端口。
* 用完及时关闭临时转发。
* `remotePort` 需要登记，避免冲突。
* token、密码、私钥不要提交到仓库。
* `iptables`/`nftables` 规则记得持久化，否则重启丢失。
* `netsh portproxy` 仅支持 TCP，不支持 UDP。

---

---
url: /wiki/device-networking.md
---

# 设备组网

设备组网把研发电脑、现场服务器、工控机和边缘设备接入同一个可控网络，适合长期维护。

```mermaid
flowchart LR
  Dev[研发电脑] --> Net[虚拟组网]
  Server[现场服务器] --> Net
  Device[工控机 / 边缘设备] --> Net
  Net --> SSH[SSH]
  Net --> Web[Web 控制台]
  Net --> API[接口联调]
  Net --> RDP[远程桌面]
```

## 方案

::: tabs

\== ZeroTier

适合多设备互通，体验接近局域网。当前使用自建 planet，需要替换 `planet` 文件后加入网络。

\== WireGuard

适合稳定点对点接入。导入配置即可连接，链路更直接，移动端也好用。

\== 其他方案

已有堡垒机、企业 VPN 或临时代理时按现场条件选用。不作为默认组网方案。

:::

## ZeroTier

### 入口

```text
自建地址：http://www.singzer.cn:3443/
网络 ID：6744f4d5dcf18985
SHA256：36a163d749cf2be879d382ab09aef818346dff98009816d97292e858ee316085
```

下载 planet 文件

软件下载：https://www.zerotier.com/download/

### 客户端

::: tabs

\== Windows

覆盖 `planet` 到：

```text
C:\ProgramData\ZeroTier\One
```

然后重启 `ZeroTier One` 服务。

```powershell
zerotier-cli.bat join 6744f4d5dcf18985
zerotier-cli.bat peers
```

\== Linux

```bash
cp planet /var/lib/zerotier-one/planet
service zerotier-one restart
zerotier-cli join 6744f4d5dcf18985
zerotier-cli peers
```

\== macOS

```bash
sudo cp planet "/Library/Application Support/ZeroTier/One/planet"
cat "/Library/Application Support/ZeroTier/One/zerotier-one.pid" | sudo xargs kill
zerotier-cli join 6744f4d5dcf18985
zerotier-cli peers
```

\== OpenWRT

1. 安装 ZeroTier。
2. 替换 `planet` 文件。
3. 重启 ZeroTier 服务。
4. 加入网络 `6744f4d5dcf18985`。
5. 执行 `zerotier-cli peers`，确认出现 `PLANET`。

:::

Android 可参考 ZerotierFix：https://github.com/kaaass/ZerotierFix

iOS 自定义 planet 支持有限，优先考虑 WireGuard。

#### Agent 提示词

复制下方提示词发给任意终端 Agent（Pi / Cursor / Claude Code / Codex 等），即可自动安装 ZeroTier、替换自建 planet 并加入网络。

```text
请帮我在当前机器安装并配置 ZeroTier，使用自建 planet 加入网络。

目标：
1. 安装 ZeroTier One。
2. 下载 planet 文件：https://wiki.feidu.fit/downloads/remote-debug/planet.bin
3. 校验 planet 文件 SHA256：36a163d749cf2be879d382ab09aef818346dff98009816d97292e858ee316085
4. 将 planet 文件替换到 /var/lib/zerotier-one/planet
5. 重启 zerotier-one 服务。
6. 加入网络：6744f4d5dcf18985
7. 验证 zerotier-cli peers 中存在 PLANET，并输出 zerotier-cli info、zerotier-cli listnetworks。

要求：
- 执行前先判断系统类型，优先支持 Debian / Ubuntu、CentOS / Rocky / Alma、Arch Linux。
- 如果 zerotier-one 已安装，不要重复破坏安装，只更新 planet 并重启服务。
- 替换 planet 前先备份旧文件，例如 /var/lib/zerotier-one/planet.bak.$(date +%Y%m%d%H%M%S)。
- 如果当前不是 root，请使用 sudo；如果 sudo 不可用，请提示需要 root 权限。
- 每一步执行后输出关键结果；失败时停止并说明失败原因。
- 不要修改其他网络配置，不要加入其他 ZeroTier 网络。

Linux 参考命令：

curl -fsSL https://install.zerotier.com | bash
curl -fL https://wiki.feidu.fit/downloads/remote-debug/planet.bin -o /tmp/planet
sha256sum /tmp/planet
systemctl stop zerotier-one || service zerotier-one stop
mkdir -p /var/lib/zerotier-one
test -f /var/lib/zerotier-one/planet && cp /var/lib/zerotier-one/planet /var/lib/zerotier-one/planet.bak.$(date +%Y%m%d%H%M%S)
cp /tmp/planet /var/lib/zerotier-one/planet
systemctl restart zerotier-one || service zerotier-one restart
zerotier-cli join 6744f4d5dcf18985
zerotier-cli peers
zerotier-cli info
zerotier-cli listnetworks
```

### 服务器示例

::: code-group

```text [服务器2]
地址：10.21.21.118
用户名：root
密码：fd123456
```

```text [服务器1（不在线）]
地址：10.21.21.36
用户名：root
密码：fd12345678
```

```bash [显卡检查]
lspci | grep NVIDIA
```

:::

## WireGuard

### 入口

```text
自建地址：http://www.singzer.cn:8000/
```

软件下载：https://www.wireguard.com/install/

### 配置

```ini
[Interface]
PrivateKey = <客户端私钥>
Address = 10.21.21.10/32
DNS = 10.21.21.1

[Peer]
PublicKey = <服务端公钥>
Endpoint = <服务端地址>:<端口>
AllowedIPs = 10.21.21.0/24
PersistentKeepalive = 25
```

`AllowedIPs` 决定哪些流量走 WireGuard：

::: code-group

```ini [访问组网]
AllowedIPs = 10.21.21.0/24
```

```ini [只访问单台]
AllowedIPs = 10.21.21.118/32
```

```ini [多个网段]
AllowedIPs = 10.21.21.0/24, 192.168.10.0/24
```

```ini [全局 IPv4]
AllowedIPs = 0.0.0.0/0
```

:::

日常远程调试优先使用内网网段，例如 `10.21.21.0/24`，不要默认写全局路由。

### 客户端

::: tabs

\== Windows / macOS / 手机

1. 安装 WireGuard 客户端。
2. 导入 `.conf` 文件或扫描二维码。
3. 启用隧道。
4. 访问组网内地址验证。

\== Linux：wg-quick

```bash
sudo apt install wireguard
sudo cp wg0.conf /etc/wireguard/wg0.conf
sudo wg-quick up wg0
sudo wg show
sudo systemctl enable wg-quick@wg0
```

\== Linux：NetworkManager

```bash
nmcli connection import type wireguard file wg0.conf
nmcli connection up wg0
nmcli connection show wg0
nmcli connection down wg0
```

:::

## 验证

::: code-group

```bash [连通性]
ping <目标设备组网地址>
```

```bash [SSH]
ssh root@<目标设备组网地址>
```

```text [Web]
http://<目标设备组网地址>:<端口>/
```

:::

## 参考

* ZeroTier 下载：https://www.zerotier.com/download/
* docker-zerotier-planet 客户端配置：https://github.com/xubiaolin/docker-zerotier-planet?tab=readme-ov-file#4-%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%85%8D%E7%BD%AE
* WireGuard 安装：https://www.wireguard.com/install/
* WireGuard Quick Start：https://www.wireguard.com/quickstart/
* NetworkManager nmcli：https://networkmanager.dev/docs/api/latest/nmcli.html

---

---
url: /wiki/usb-mapping.md
---

# USB 映射

通过网络把远程 USB 设备映射到本地，像插在自己电脑上一样使用。适合远程访问串口设备、加密狗、打印机、摄像头等。

## 方案速查

```mermaid
flowchart LR
  A[远程访问 USB 设备] --> B{设备数量少?}
  B -->|是| C[VirtualHere]
  B -->|否| D{需要开源免费?}
  D -->|是| E[USB/IP]
  D -->|否| C
```

::: tabs

\== VirtualHere

跨平台，开箱即用，有 GUI 和 CLI 两种客户端。免费版无设备数量限制，商业用途需购买授权。少量设备场景最方便。

\== USB/IP

开源内核方案，需要命令行操作，适合无 GUI 的服务器或需要同时映射大量设备的场景。

:::

## 下载

| 工具 | 下载入口 |
| --- | --- |
| VirtualHere 服务端 | https://virtualhere.com/oem\_server\_downloads |
| VirtualHere 客户端 (GUI) | https://virtualhere.com/client\_downloads |
| VirtualHere 客户端 (CLI) | https://virtualhere.com/command\_line\_client |
| USB/IP (Linux) | https://github.com/usbip/implementations |
| USB/IP (Windows) | https://github.com/cezanne/usbip-win/releases |
| USB/IP (macOS 服务端) | https://github.com/beriberikix/usbipd-mac |

## VirtualHere

### 原理

![VirtualHere 架构](/illustrations/usb-mapping/virtualhere-diagram.jpg)

服务端运行 `vhusbd` 自动共享所有 USB 设备 → 客户端选中设备 Use → 本地出现虚拟 USB 设备。

### 服务端

下载对应平台的服务端，直接运行即可，无需安装。

::: code-group

```bash [Linux]
chmod +x vhusbdx86_64
sudo ./vhusbdx86_64 -b
```

```powershell [Windows]
# 双击运行 vhusbd64.exe 即可
# 或命令行
.\vhusbd64.exe -b
```

:::

`-b` 后台运行。默认监听 **TCP 7578**，防火墙需放行。

在服务端同目录创建 `config.ini`：

```ini
ServerName = Fit-USB-Server
Password =   # 客户端连接密码，留空不设密码
MaxConnections = 10
Port = 7578
```

### 客户端

VirtualHere 提供 GUI 和 CLI 两种客户端，功能相同，按场景选用。

**GUI 客户端** — 有界面，右键操作，适合桌面环境。

![VirtualHere 客户端界面](/illustrations/usb-mapping/virtualhere-client-windows.png)

**GUI 客户端** — 有界面，右键操作，适合桌面环境。

::: code-group

```bash [Linux]
chmod +x vhui64
./vhui64
```

```powershell [Windows]
# 双击运行 vhui64.exe 即可
```

```bash [macOS]
chmod +x vhui64.app/Contents/MacOS/vhui64
./vhui64.app/Contents/MacOS/vhui64
```

:::

GUI 操作步骤：

1. 左侧列出发现的 USB 服务器。
2. 展开服务器，看到所有 USB 设备。
3. 右键要使用的设备 → **Use this device**。
4. 本地出现虚拟 USB 设备，可直接使用。
5. 不再使用时右键 → **Stop using this device**。

**CLI 客户端** — 无界面，命令行操作，适合无 GUI 的服务器或脚本自动化。

::: code-group

```bash [Linux]
chmod +x vhuc
./vhuc
```

```powershell [Windows]
.\vhuc.exe
```

:::

CLI 操作：

```bash
# 列出服务端设备
./vhuc <服务端IP>

# 使用指定设备（序号从 0 开始）
./vhuc <服务端IP> use 0

# 断开设备
./vhuc <服务端IP> stop 0

# 查看帮助
./vhuc help
```

### 串口设备示例

```bash
# 客户端 Use 设备后，本地出现串口设备
dmesg | grep ttyUSB
# [  xxx] usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB0

# 直接使用
minicom -D /dev/ttyUSB0 -b 115200
# 或
picocom /dev/ttyUSB0 -b 115200
# 或
python3 -c "import serial; s=serial.Serial('/dev/ttyUSB0',115200); print(s.read(100))"
```

### 持久化

**Linux 服务端** — systemd service：

```bash
# /etc/systemd/system/virtualhere.service
[Unit]
Description=VirtualHere USB Server
After=network.target

[Service]
ExecStart=/usr/local/bin/vhusbdx86_64 -b -c /etc/virtualhere/config.ini
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```bash
sudo cp vhusbdx86_64 /usr/local/bin/
sudo mkdir -p /etc/virtualhere
sudo cp config.ini /etc/virtualhere/
sudo systemctl daemon-reload
sudo systemctl enable --now virtualhere
```

**Linux 客户端** — 同理写 systemd service 或放 `~/.config/autostart/`。

**Windows** — 服务端/客户端快捷方式放入启动文件夹 `shell:startup`。

### 授权

| 用途 | 说明 |
| --- | --- |
| 个人/非商业 | 免费，无设备数量限制 |
| 商业用途 | 需购买授权，约 $29 起 |

少量设备（1~2 个串口/加密狗）用免费版足够，开箱即用不需要折腾内核模块。

## USB/IP

### 原理

```mermaid
flowchart LR
  Local[本地机器] -->|USB/IP 协议| Server[远程服务器]
  Server -->|USB 设备| Device[串口 / 加密狗 / 打印机]
```

内核级 USB 设备转发，开源免费，支持同时映射多个设备。

### 安装

::: code-group

```bash [服务端 (Debian/Ubuntu)]
apt install usbip
modprobe usbip-core
modprobe usbip-host
```

```bash [服务端 (RHEL/CentOS)]
yum install usbip
modprobe usbip-core
modprobe usbip-host
```

```bash [客户端 (Debian/Ubuntu)]
apt install usbip
modprobe vhci-hcd
```

```bash [客户端 (RHEL/CentOS)]
yum install usbip
modprobe vhci-hcd
```

```bash [客户端 (Arch Linux)]
pacman -S linux-tools-usbip
modprobe vhci-hcd
```

```powershell [客户端 (Windows)]
# 下载 USB/IP Windows 客户端
# https://github.com/cezanne/usbip-win/releases
# 安装驱动后重启
```

```bash [服务端 (macOS)]
# 下载 usbipd-mac
# https://github.com/beriberikix/usbipd-mac
make
sudo ./usbipd
```

:::

Linux 和 Windows 的 USB/IP 由内核原生支持，macOS 没有内核级实现。[usbipd-mac](https://github.com/beriberikix/usbipd-mac) 是社区实现的 macOS USB/IP 服务端，可用于从 Mac 导出 USB 设备。

**限制**：

* 仅支持服务端（导出设备），macOS 作为客户端导入设备仍无成熟方案。
* 需要从源码编译。
* 稳定性不如 Linux 内核方案，建议优先用 VirtualHere 替代。

如果 macOS 只需**使用**远程 USB 设备，推荐直接用 VirtualHere 客户端。

### 服务端操作

```bash
# 查看可用的 USB 设备
usbip list -l

# 绑定要导出的设备（例如 1-1）
usbip bind -b 1-1

# 启动 usbip 守护进程
usbipd -D

# 查看已导出的设备
usbip list -l
```

设备编号 `1-1` 通过 `usbip list -l` 或 `lsusb -t` 查看。

解除绑定（不再导出）：

```bash
usbip unbind -b 1-1
```

### 客户端操作

```bash
# 查看服务端导出的设备
usbip list -r <服务端IP>

# 导入设备
usbip attach -r <服务端IP> -b 1-1

# 查看已导入的设备
usbip port

# 本地验证
dmesg | tail
lsusb
```

断开映射：

```bash
# 查看端口编号
usbip port

# 断开
usbip detach -p 0
```

```powershell
# 安装 USB/IP Windows 客户端后
# 查看服务端设备
usbip.exe list -r <服务端IP>

# 导入设备
usbip.exe attach -r <服务端IP> -b 1-1

# 断开
usbip.exe detach -p 0
```

### 串口设备示例

```bash
# 服务端绑定串口 USB 设备
usbip list -l
usbip bind -b 1-2
usbipd -D

# 客户端导入
usbip attach -r 10.21.21.118 -b 1-2

# 导入成功后本地出现 /dev/ttyUSB0
dmesg | grep ttyUSB
# [  xxx] usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB0

# 直接使用
minicom -D /dev/ttyUSB0 -b 115200
# 或
picocom /dev/ttyUSB0 -b 115200
# 或
python3 -c "import serial; s=serial.Serial('/dev/ttyUSB0',115200); print(s.read(100))"
```

### 持久化

**服务端** — 开机自动加载内核模块并导出设备：

```bash
# /etc/modules-load.d/usbip.conf
usbip-core
usbip-host
```

```bash
# /etc/rc.local 或 systemd service
usbip bind -b 1-1
usbipd -D
```

**客户端** — 开机自动加载内核模块并导入：

```bash
# /etc/modules-load.d/vhci-hcd.conf
vhci-hcd
```

```bash
# /etc/rc.local 或 systemd service
usbip attach -r <服务端IP> -b 1-1
```

## 注意

* 映射期间设备**不能在服务端本地使用**。
* 延迟取决于网络质量，高延迟网络下 USB 设备可能不稳定（尤其是存储设备）。
* 大容量存储（U盘、硬盘）不建议走 USB 映射，优先用 NFS/SMB/SSHFS。
* VirtualHere 个人/非商业免费，商业用途需购买授权。
* USB/IP 默认使用 **TCP 3240** 端口，VirtualHere 默认 **TCP 7578**，防火墙需放行。
* USB/IP `usbip bind` 后重启服务端需重新绑定，除非做了持久化。
* USB/IP Windows 客户端需要安装签名驱动，部分版本可能需禁用驱动签名强制。

---

---
url: /wiki/remote-control.md
---

# 远程控制

远程控制分为两大类：**远程桌面**（操作图形界面）和**远程终端**（命令行访问）。

## 怎么选

| 需求 | 推荐 |
| --- | --- |
| 不想折腾、开箱即用 | 向日葵 / ToDesk / AnyDesk |
| 海外免费、极简 | AnyDesk |
| 国内远程运维 | 向日葵 |
| 国内远程办公 | ToDesk |
| 国内游戏串流 | UU远程加速 |
| 想完全免费无限制 | RustDesk（开源自建） |
| Windows 远程桌面 | RDP（系统自带） |
| Linux 远程桌面 | VNC / RustDesk |
| 轻量、内网临时使用 | VNC |
| 高性能、低延迟 | RDP / Sunshine + Moonlight |
| macOS 远程桌面 | VNC / RustDesk |
| 命令行远程管理 | SSH |
| 浏览器远程终端 | ttyd |
| 串口调试（嵌入式） | Serial / SSH 串口网关 |

```mermaid
flowchart LR
  A[远程控制] --> B[远程桌面]
  A --> C[远程终端]
  B --> D{想折腾?}
  D -->|不想| E[向日葵 / ToDesk / AnyDesk]
  D -->|想| F{有公网 IP?}
  F -->|有| G[RDP / VNC]
  F -->|没有| H[RustDesk]
  C --> I{有 SSH?}
  I -->|有| J[SSH 直连]
  I -->|只有浏览器| K[ttyd]
  I -->|串口设备| L[Serial / 串口网关]
```

## 远程桌面

操作目标设备的图形界面，适合排障 GUI 软件、调试桌面应用、远程配置系统。

### 方案对比

| | AnyDesk | 向日葵 | ToDesk | UU远程加速 | RDP | VNC | RustDesk | Sunshine + Moonlight |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 开源 | ✗ | ✗ | ✗ | ✗ | ✗（微软协议） | ✓（多数实现） | ✓ | ✓ |
| 费用 | 免费基础版 | 免费基础版 | 免费基础版 | 付费 | Windows 自带 | 免费 | 免费 | 免费 |
| 平台 | 全平台 | 全平台 | Win / macOS / Android | Win | Win 服务端 / 全平台客户端 | 全平台 | 全平台 | Win/Linux 服务端 / 全平台客户端 |
| 需要公网 IP | 不需要 | 不需要 | 不需要 | 不需要 | 需要（或 VPN） | 需要（或 VPN） | 不需要 | 需要（或 VPN） |
| 延迟 | 低 | 中 | 低 | 极低 | 低 | 中 | 中 | 极低 |
| 画质 | 高 | 高 | 高 | 高 | 高 | 一般 | 高 | 极高 |
| 传输加密 | ✓ | ✓ | ✓ | ✓ | ✓ | 多数默认无 | ✓ | ✓ |
| 安装复杂度 | 极低 | 极低 | 极低 | 极低 | Windows 自带 | 低 | 低 | 中 |
| 典型场景 | 海外免费远程 | 国内远程运维 | 国内远程办公 | 国内游戏串流 | 远程管 Win 服务器 | Linux 临时桌面 | 自建远程支持 | GPU 串流 |

### 商业远程桌面

无需自建服务器、开箱即用，通过厂商中继穿透内网，适合不想折腾的用户。

| 工具 | 定位 | 特色 |
| --- | --- | --- |
| [AnyDesk](https://anydesk.com/) | 海外免费远程桌面 | 极简、低延迟，免费版够用，无广告 |
| [向日葵](https://sunlogin.oray.com/) | 国内远程运维 | 远程开机（需硬件）、CMD 命令行、手机控电脑 |
| [ToDesk](https://www.todesk.com/) | 国内远程办公 | 免费版 1080P、文件传输、多屏 |
| [UU远程加速](https://uu.163.com/remote/) | 国内游戏串流 | 网易出品，专攻游戏低延迟 |

::: code-group

```text [AnyDesk]
下载：https://anydesk.com/downloads

- 安装后自动生成 ID
- 输入对方 ID → 对方确认 → 连接
- 免费个人版无功能限制
- 无需注册账号
- 注意：商业使用需购买许可证
```

```text [向日葵]
下载：https://sunlogin.oray.com/download

- 安装后登录账号自动绑定设备
- 支持远程开机（需购买开机棒/开机插座）
- 免费版限速，专业版不限
- 适合长期运维现场设备
- 提供命令行版（sunloginclient），适合无界面 Linux
```

```text [ToDesk]
下载：https://www.todesk.com/download

- 安装后输入对方设备代码连接
- 免费版支持 1080P
- 支持文件传输、剪贴板共享
- 适合日常远程办公
```

```text [UU远程加速]
下载：https://uu.163.com/remote/

- 网易出品，专注游戏场景
- 极低延迟，适合远程打游戏
- 基于网易加速线路
- 仅 Windows
```

:::

| | AnyDesk | 向日葵 | ToDesk | UU远程加速 |
| --- | --- | --- | --- | --- |
| 免费版限速 | 不限（但会弹提示） | 限速 ~1Mbps | 不限 | 不限 |
| 免费版分辨率 | 不限 | 不限 | 1080P | 不限 |
| 免费版设备数 | 不限 | 限制 | 多设备 | 不限 |
| 商业使用 | 需购买许可证 | 需购买 | 需购买 | 免费 |
| 广告 | 无 | 有 | 有 | 有 |
| 远程开机 | ✗ | ✓（需硬件） | ✗ | ✗ |
| 命令行版 | ✗ | ✓ | ✗ | ✗ |

**选择建议**：

* 海外 / 不想看广告 → AnyDesk
* 国内远程运维设备 → 向日葵（支持远程开机 + 命令行）
* 国内远程办公 → ToDesk
* 远程打游戏 → UU远程加速
* 想完全免费无限制 → RustDesk（开源自建）

### RDP

Windows 自带远程桌面协议，性能最好，延迟最低。

::: code-group

```text [Windows 服务端启用]
设置 → 系统 → 远程桌面 → 启用远程桌面

或 PowerShell（管理员）：
Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -name "fDenyTSConnections" -value 0
```

```bash [Linux 服务端（xrdp）]
apt install xrdp       # Debian/Ubuntu
yum install xrdp       # RHEL/CentOS
systemctl enable --now xrdp

# 连接后如果黑屏，编辑 /etc/xrdp/startwm.sh
# 确保 exec 后面指向正确的桌面会话
```

```text [客户端连接]
Windows：自带"远程桌面连接"（mstsc.exe）
macOS：Microsoft Remote Desktop（App Store）
Linux：remmina / xfreerdp

连接地址：目标机器 IP:3389
```

:::

### VNC

轻量远程桌面协议，全平台支持，内网临时使用首选。

::: code-group

```bash [Linux 服务端（TigerVNC）]
apt install tigervnc-standalone-server tigervnc-common

# 设置 VNC 密码
vncpasswd

# 启动虚拟桌面（分辨率可调）
vncserver :1 -geometry 1920x1080 -depth 24

# 停止
vncserver -kill :1
```

```bash [Linux 服务端（x11vnc — 共享真实物理屏幕）]
apt install x11vnc

# 共享当前物理显示器（适合现场有人操作时远程围观）
x11vnc -display :0 -passwd yourpassword -forever

# 默认端口 5900
```

```text [macOS 服务端]
系统设置 → 通用 → 共享 → 屏幕共享 → 开启

或命令行：
sudo /System/Library/CoreServices/Menu\ Extras/User.menu/Contents/Resources/CGSession -enableVNC

默认端口 5900
```

```text [客户端连接]
全平台：RealVNC Viewer / TigerVNC Viewer
macOS：自带"屏幕共享"

连接地址：IP:5901（TigerVNC 虚拟桌面）
连接地址：IP:5900（x11vnc 物理屏幕）
```

:::

飞度现场设备常运行麒麟（Kylin）OS，开启 VNC 方法：

```bash
# 方法一：系统设置
# 系统设置 → 网络 → 远程桌面 → 开启

# 方法二：命令行
sudo apt install vnc4server tigervnc-standalone-server
vncserver :1 -geometry 1920x1080

# 方法三：x11vnc 共享物理屏幕
sudo apt install x11vnc
x11vnc -display :0 -passwd feidu2024 -forever &
```

### RustDesk

开源远程桌面，自带中继服务器，**不需要公网 IP**，最适合跨网远程支持。

::: code-group

```bash [Linux 服务端]
# Docker 一键部署中继服务器
docker run -d --name rustdesk-server \
  -p 21115:21115 -p 21116:21116 -p 21116:21116/udp \
  -p 21117:21117 -p 21118:21118 -p 21119:21119 \
  -v /opt/rustdesk-server:/root \
  rustdesk/rustdesk-server-sbb

# 或直接下载二进制
# https://github.com/rustdesk/rustdesk-server/releases
```

```bash [Linux 客户端]
# 下载
# https://github.com/rustdesk/rustdesk/releases

# Ubuntu/Debian
dpkg -i rustdesk-*.deb

# 运行
rustdesk
```

```text [Windows / macOS 客户端]
下载：https://github.com/rustdesk/rustdesk/releases

安装后输入对方 ID + 密码即可连接
可配置自建中继服务器地址
```

:::

RustDesk 默认用官方中继，延迟可能较高。自建中继服务器可降低延迟：

**1. 部署中继服务**

```bash
docker run -d --name hbbs \
  -p 21115:21115 -p 21116:21116 -p 21116:21116/udp \
  -v /opt/rustdesk-server:/root \
  rustdesk/rustdesk-server-sbb hbbs

docker run -d --name hbbr \
  -p 21117:21117 -p 21119:21119 \
  -v /opt/rustdesk-server:/root \
  rustdesk/rustdesk-server-sbb hbbr
```

**2. 客户端配置**

设置 → 网络 → ID 服务器 / 中继服务器 → 填入自建服务器地址（默认端口 21115/21117）

**3. 密钥配对**（可选，防未授权连接）

```bash
# 服务端生成密钥
cat /opt/rustdesk-server/id_ed25519.pub
# 将公钥填入客户端 → 设置 → 网络 → Key
```

### Sunshine + Moonlight

开源高画质串流方案，GPU 硬件编码，延迟极低，适合 GPU 密集场景。

```bash
# 服务端（Sunshine）
# https://github.com/LizardByte/Sunshine/releases
apt install sunshine   # 或下载 deb/rpm

# 首次启动后访问 Web 管理界面配置
# https://localhost:47990

# 客户端（Moonlight）
# https://moonlight-stream.org/
# 全平台客户端，输入服务端 IP 即可连接
```

> **适合场景**：GPU 直通虚拟机远程看画面、远程 3D 渲染、高帧率串流。日常远程管理用 RDP / VNC / RustDesk 即可。

## 远程终端

命令行远程访问，适合服务器管理、日志查看、服务运维，资源占用远低于远程桌面。

### 方案对比

| | SSH | ttyd | Cockpit | 串口终端 |
| --- | --- | --- | --- | --- |
| 全称 | Secure Shell | TTYd — 浏览器终端 | Web 系统管理面板 | Serial Console |
| 访问方式 | SSH 客户端 | 浏览器 | 浏览器 | 串口客户端 |
| 需要安装客户端 | 是 | 否（浏览器即可） | 否（浏览器即可） | 是 |
| 需要公网 IP | 需要（或 VPN） | 需要（或 VPN） | 需要（或 VPN） | 不需要（物理连接） |
| 传输加密 | ✓ | ✓（可配置） | ✓ | ✗ |
| 认证方式 | 密钥 / 密码 | 密码 / Token | 系统账号 | 无 / 简单密码 |
| 资源占用 | 极低 | 极低 | 中 | 无 |
| 适合场景 | 服务器管理 | 浏览器临时终端 | 系统管理面板 | 嵌入式调试 / 无网络设备 |

### SSH

最常用的远程终端协议，几乎所有 Linux/Unix 系统自带。

::: code-group

```bash [Linux 服务端]
# 安装（多数系统自带）
apt install openssh-server   # Debian/Ubuntu
yum install openssh-server   # RHEL/CentOS

systemctl enable --now sshd
```

```text [Windows 服务端]
设置 → 系统 → 可选功能 → 添加"OpenSSH 服务器"

或 PowerShell（管理员）：
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
```

```text [客户端连接]
# Linux / macOS / WSL
ssh user@192.168.1.100

# Windows
ssh user@192.168.1.100
# 或 PuTTY / MobaXterm

# 指定端口
ssh -p 2222 user@192.168.1.100

# 密钥认证（推荐）
ssh-keygen -t ed25519
ssh-copy-id user@192.168.1.100
```

:::

**跳板机穿透**：

```bash
# 通过跳板机访问内网机器
ssh -J jumpuser@jumphost targetuser@targethost

# 或配置 ~/.ssh/config
Host target
  HostName 192.168.1.100
  User root
  ProxyJump jumpuser@jumphost
```

**SSH 隧道**（临时端口转发）：

```bash
# 本地端口转发：访问内网 Web 服务
ssh -L 8080:192.168.1.100:80 user@jumphost
# 浏览器访问 localhost:8080

# 远程端口转发：让外部访问本机服务
ssh -R 9090:localhost:3000 user@public-server
# 外部通过 public-server:9090 访问

# SOCKS 代理
ssh -D 1080 user@jumphost
# 浏览器设置 SOCKS5 代理 localhost:1080
```

**保持连接**：

```bash
# ~/.ssh/config
Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3
  TCPKeepAlive yes
```

**免密登录**：

```bash
ssh-keygen -t ed25519
ssh-copy-id user@host
# 之后 ssh user@host 直接登录
```

### ttyd

浏览器内终端，不需要 SSH 客户端，打开网页就能操作命令行，适合临时排查。

::: code-group

```bash [安装]
# 下载
# https://github.com/tsl0922/ttyd/releases

# 或 Docker
docker run -d --name ttyd \
  -p 7681:7681 \
  tsl0922/ttyd bash
```

```bash [基本用法]
# 启动终端（监听 7681 端口）
ttyd bash

# 指定端口和认证
ttyd -p 8080 -c user:password bash

# 用指定 shell
ttyd -c admin:feidu2024 zsh

# 浏览器访问
# http://IP:8080
```

```bash [Docker 自启动]
# 现场设备长期部署 ttyd
docker run -d --name ttyd --restart always \
  -p 7681:7681 \
  -e TZ=Asia/Shanghai \
  tsl0922/ttyd -c admin:feidu2024 bash
```

:::

ttyd 默认无加密，公网部署需加 HTTPS 或限制访问：

```bash
# SSL/TLS 加密
ttyd -c user:password -S cert.pem:key.pem bash

# 配合 Nginx 反向代理 + Basic Auth
# Nginx 配置
server {
    listen 443 ssl;
    location /ttyd/ {
        proxy_pass http://127.0.0.1:7681/;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        auth_basic "Restricted";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}
```

### Cockpit

Red Hat 出品的 Web 系统管理面板，图形化管理 Linux 服务器，比纯终端更直观。

```bash
# 安装
apt install cockpit       # Debian/Ubuntu
yum install cockpit       # RHEL/CentOS

systemctl enable --now cockpit.socket

# 浏览器访问
# https://IP:9090
# 用系统账号登录
```

功能：系统监控、服务管理、终端、存储管理、网络配置、日志查看、容器管理。

### 串口终端

嵌入式设备调试常用串口（Serial）直接连接，不依赖网络。

::: code-group

```bash [Linux — minicom / picocom]
# 安装
apt install minicom picocom

# picocom（最简单）
picocom -b 115200 /dev/ttyUSB0

# minicom（功能更多）
minicom -D /dev/ttyUSB0 -b 115200

# 退出 picocom：Ctrl+A Ctrl+X
# 退出 minicom：Ctrl+A X
```

```text [Windows — PuTTY / MobaXterm]
PuTTY：
  Connection type: Serial
  Serial line: COM3
  Speed: 115200

MobaXterm：
  Sessions → Serial → 选端口和波特率
```

```text [macOS — screen / minicom]
# screen（最简单）
screen /dev/tty.usbserial-110 115200

# 退出 screen：Ctrl+A Ctrl+\

# minicom
brew install minicom
minicom -D /dev/tty.usbserial-110 -b 115200
```

:::

嵌入式设备只有串口，但人在远程，可以通过串口网关把串口转成 TCP/SSH：

**ser2net**（串口转 TCP）：

```bash
apt install ser2net

# /etc/ser2net.conf
# 把 /dev/ttyUSB0 转发到 TCP 7000 端口
7000:raw:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT

systemctl enable --now ser2net

# 远程连接
telnet 192.168.1.100 7000
# 或
socat - TCP:192.168.1.100:7000
```

**ssh2tty**（串口转 SSH）：

```bash
# Docker 部署
docker run -d --name ssh2tty \
  -p 2222:22 \
  --device /dev/ttyUSB0 \
  -e SERIAL_PORT=/dev/ttyUSB0 \
  -e SERIAL_BAUD=115200 \
  ghcr.io/zhaojh319/ssh2tty

# 远程通过 SSH 访问串口
ssh -p 2222 serial@192.168.1.100
```

---

---
url: /wiki/virtual-machine.md
---

# 虚拟机

虚拟机用于本地调试、环境模拟和固件验证，不需要真实硬件即可运行和测试目标系统。

## 怎么选

```mermaid
flowchart LR
  A[需要虚拟化] --> B{用途?}
  B -->|运行完整 OS| C{需要设备直通?}
  B -->|跑命令/容器| D{宿主系统?}
  C -->|是| E[KVM / PVE / ESXi]
  C -->|否| F{需要跨平台?}
  F -->|是| G[VMware / VirtualBox / Hyper-V]
  F -->|否| H[KVM / QEMU]
  D -->|Windows| I[WSL2 / Docker Desktop]
  D -->|Linux / macOS| J[Docker / Podman]
  B -->|生产集群| K[PVE / ESXi]
  B -->|异构调试| L[QEMU]
```

::: tabs

\== VMware Workstation / Player

图形界面，Windows/Linux 日常开发最常用，开箱即用。Player 免费版够用。

\== VMware Fusion

VMware 的 macOS 版虚拟机，功能对应 Workstation，个人版免费。

\== Parallels Desktop

macOS 上最流畅的虚拟机，与 macOS 深度集成（Coherence 模式窗口融合），付费软件。

\== VirtualBox

开源免费，跨平台（Windows/macOS/Linux），适合轻量测试。

\== Hyper-V

Windows 内置 Type 1 虚拟机，Pro/Enterprise 版自带，不需要额外安装。

\== WSL2

Windows Subsystem for Linux 2，在 Windows 内原生跑 Linux 命令，秒启动，适合开发调试。

\== KVM / QEMU

Linux 内核级虚拟化，性能最好。QEMU 可模拟 ARM/MIPS 等异构架构，适合嵌入式调试。

\== Docker / Podman

容器方案，秒启动隔离环境，适合跑服务、编译、测试。Podman 无需 daemon，支持 rootless。

\== Docker / Podman

容器方案，秒启动隔离环境，适合跑服务、编译、测试。

\== OrbStack

macOS 上最轻量最快的 Docker/Linux 运行环境，替代 Docker Desktop，资源占用极低。

\== Proxmox VE

基于 KVM 的企业级管理平台，Web 界面管理集群、快照、直通。适合现场服务器部署。

\== ESXi

VMware 裸机虚拟化，商业方案，适合现有 VMware 生态的环境。

:::

## 快速判断

| 需求 | 推荐 |
| --- | --- |
| Windows 日常开发测试 | VMware Workstation Player |
| Windows 跑 Linux 命令 | WSL2 |
| Windows 跑容器 | Docker Desktop |
| macOS 日常开发测试 | Parallels Desktop / VMware Fusion |
| macOS 跑容器 | OrbStack / Docker Desktop / Podman |
| 需要模拟 ARM / MIPS 设备 | QEMU |
| Linux 本机最高性能 | KVM |
| Linux 跑容器 | Docker / Podman |
| 现场 Linux 服务器多虚机管理 | Proxmox VE |
| 企业 VMware 生态 | ESXi |
| Windows 内置虚拟机 | Hyper-V |
| 需要 GPU / USB / PCIe 直通 | KVM / PVE / ESXi |
| 快速跑个 Linux 测试命令 | QEMU user mode |
| 秒启动隔离环境跑服务 | Docker / Podman |

## 对比

### 完整虚拟机

| | 类型 | 宿主系统 | 设备直通 | 异构模拟 | Web 管理 | 费用 |
| --- | --- | --- | --- | --- | --- | --- |
| VMware Workstation | Type 2 | Win / Linux | 有限（USB） | ✗ | ✗ | Player 免费 / Pro 付费 |
| VMware Fusion | Type 2 | macOS | 有限（USB） | ✗ | ✗ | 个人免费 / Pro 付费 |
| Parallels Desktop | Type 2 | macOS | USB | ✗ | ✗ | 付费 |
| VirtualBox | Type 2 | Win / macOS / Linux | USB | ✗ | ✗ | 免费 |
| Hyper-V | Type 1 | Win (Pro/Ent) | PCIe / GPU / USB | ✗ | ✗ | 系统自带 |
| KVM | Type 1 | Linux | PCIe / GPU / USB | ✗ | ✗ | 免费 |
| QEMU | 模拟器 | 全平台 | 可配合 KVM | ✓（ARM/MIPS/...） | ✗ | 免费 |
| Proxmox VE | Type 1 | 裸机 | PCIe / GPU / USB | ✗ | ✓ | 免费 |
| ESXi | Type 1 | 裸机 | PCIe / GPU / USB | ✗ | ✓ | 免费基础版 |

### 轻量虚拟化 & 容器

| | 类型 | 宿主系统 | 启动速度 | 隔离级别 | GUI | 典型场景 |
| --- | --- | --- | --- | --- | --- | --- |
| WSL2 | 轻量 VM | Win 10+ | 秒级 | 内核隔离 | ✗ | Linux 命令行开发 |
| Docker | 容器 | Win / macOS / Linux | 秒级 | 进程隔离 | ✗ | 跑服务、编译、CI |
| Podman | 容器 | Win / macOS / Linux | 秒级 | 进程隔离（rootless） | ✗ | 安全容器、Docker 替代 |
| OrbStack | 轻量 VM | macOS | USB | ✗ | ✗ | 个人免费 / 商业付费 |

> **容器 vs 虚拟机**：容器共享宿主内核，启动快、开销小，但不支持内核级调试（驱动开发、内核模块测试）。需要完整内核隔离时用虚拟机。

## 下载

| 工具 | 下载入口 |
| --- | --- |
| VMware Workstation Pro | https://www.vmware.com/products/workstation-pro.html |
| VMware Workstation Player | https://www.vmware.com/products/workstation-player.html |
| VMware Fusion | https://www.vmware.com/products/fusion.html |
| Parallels Desktop | https://www.parallels.com/products/desktop/ |
| VirtualBox | https://www.virtualbox.org/wiki/Downloads |
| VirtualBox Extension Pack | https://www.virtualbox.org/wiki/Downloads (页面底部) |
| Hyper-V | Windows 功能自带（启用方法见下方） |
| WSL2 | https://learn.microsoft.com/windows/wsl/install |
| QEMU | https://www.qemu.org/download/ |
| KVM (Linux) | 系统包管理器自带 |
| libvirt / virt-manager | https://virt-manager.org/download/ |
| OVMF (UEFI 固件) | 系统包管理器自带 (`apt install ovmf`) |
| Docker Desktop | https://www.docker.com/products/docker-desktop/ |
| Docker Engine (Linux) | https://docs.docker.com/engine/install/ |
| OrbStack | https://orbstack.dev/ |
| Podman | https://podman.io/getting-started/installation |
| Podman Desktop | https://podman-desktop.io/downloads |
| LXC / LXD | https://linuxcontainers.org/lxd/getting-started-cli/ |
| Proxmox VE | https://www.proxmox.com/en/downloads |
| ESXi | https://www.vmware.com/products/esxi-and-esx.html |
| ESXi Customizer (打包驱动) | https://www.v-front.de/p/esxi-customizer.html |

## WSL2

Windows Subsystem for Linux 2，在 Windows 内跑真实 Linux 内核，秒启动，文件互通。

### 安装

::: code-group

```powershell [一键安装]
wsl --install
# 默认安装 Ubuntu，重启后可用
```

```powershell [指定发行版]
wsl --install -d Debian
wsl --install -d Ubuntu-24.04
wsl --list --online   # 查看可用发行版
```

```powershell [手动启用（离线环境）]
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 重启后设置 WSL2 为默认
wsl --set-default-version 2
```

:::

### 常用操作

```bash
# 进入 WSL
wsl

# 指定发行版
wsl -d Debian

# Windows ↔ WSL 文件互访
# WSL 中访问 Windows：/mnt/c/Users/xxx
# Windows 中访问 WSL：\\wsl$\Ubuntu\home

# 网络端口互通
# WSL 中启动的服务，Windows 可直接通过 localhost 访问
```

**网络**：WSL2 默认 NAT 模式，Windows 通过 `localhost` 访问 WSL 服务。从 WSL 访问 Windows 局域网设备直接可用。

**USB 设备**：WSL2 默认不能直接访问 USB 设备，需要 [usbipd-win](https://github.com/dorssel/usbipd-win)：

```powershell
# Windows 端安装 usbipd
winget install usbipd

# 列出 USB 设备
usbipd list

# 绑定设备（需要管理员）
usbipd bind --busid 1-1

# 挂载到 WSL
usbipd attach --wsl --busid 1-1
```

```bash
# WSL 内验证
lsusb
dmesg | grep ttyUSB
```

WSL2 底层使用 Hyper-V 的轻量虚拟机（Utility VM），但**不需要完整开启 Hyper-V 功能**。

* WSL2 只启用 `VirtualMachinePlatform`，不要求 `Hyper-V` 功能
* 开启 Hyper-V 后 WSL2 也能正常工作
* Hyper-V 和 VMware / VirtualBox 可能冲突（新版已兼容）

## Docker & Podman

容器方案，秒启动隔离环境，适合跑服务、编译、测试、CI。

### Docker 引擎后端

Docker 在不同平台上的底层实现不同，影响性能和资源占用。

| 后端 | 平台 | 底层 | 资源占用 | 说明 |
| --- | --- | --- | --- | --- |
| Docker Engine | Linux | 原生内核 | 最低 | 直接跑在宿主内核，无虚拟化开销 |
| Docker Desktop (WSL2) | Windows | WSL2 轻量 VM | 中 | 默认后端，用 WSL2 跑 Linux 内核 |
| Docker Desktop (Hyper-V) | Windows | Hyper-V VM | 高 | 旧版后端，现已被 WSL2 替代 |
| Docker Desktop (Apple VM) | macOS | Apple 虚拟化框架 | 中 | macOS 专属后端 |
| OrbStack | macOS | Apple 虚拟化框架 | 极低 | 替代 Docker Desktop，CPU/内存占用远低 |

> **选择建议**：Linux 直接用 Docker Engine；macOS 优先 OrbStack；Windows 用 Docker Desktop (WSL2 后端)。

### Docker

::: code-group

```bash [Linux]
# 安装 Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 运行容器
docker run -it ubuntu bash
docker run -d -p 8080:80 nginx
```

```powershell [Windows / macOS]
# 安装 Docker Desktop
# https://www.docker.com/products/docker-desktop/

# 运行容器
docker run -it ubuntu bash
docker run -d -p 8080:80 nginx
```

:::

### Podman

Docker 的开源替代，无需 daemon，支持 rootless 运行，更安全。

::: code-group

```bash [Linux]
# 安装
apt install podman       # Debian/Ubuntu
dnf install podman       # RHEL/CentOS/Fedora

# 用法和 Docker 几乎一样（可以 alias docker=podman）
podman run -it ubuntu bash
podman run -d -p 8080:80 nginx
```

```powershell [Windows / macOS]
# 安装 Podman Desktop
# https://podman-desktop.io/downloads

# 或命令行
podman machine init
podman machine start
podman run -it ubuntu bash
```

:::

| | Docker | Podman |
| --- | --- | --- |
| Daemon | 需要 dockerd | 无 daemon |
| Root 权限 | 默认 root | 支持 rootless |
| Docker Compose | ✓ | ✓（podman-compose） |
| GUI | Docker Desktop | Podman Desktop |
| 企业支持 | Docker Inc. | Red Hat |
| 兼容性 | 最广泛 | Docker CLI 兼容 |

**选择建议**：

* 个人开发 / CI：Docker，生态最成熟
* 安全敏感 / 企业 Linux：Podman，rootless 更安全
* 已经在用 Docker：不用换，两者 CLI 几乎兼容

容器内使用 GPU，适合 AI 推理、CUDA 编译、图形渲染等场景。

#### NVIDIA GPU

Docker 官方支持 NVIDIA GPU 直通，需要 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)。

**1. 安装 NVIDIA 驱动（宿主机）**

```bash
# 确认驱动和 GPU
nvidia-smi
```

**2. 安装 NVIDIA Container Toolkit**

::: code-group

```bash [Debian/Ubuntu]
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -sL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
apt update
apt install -y nvidia-container-toolkit
systemctl restart docker
```

```bash [RHEL/CentOS]
curl -sL https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo | \
  tee /etc/yum.repos.d/nvidia-container-toolkit.repo
yum install -y nvidia-container-toolkit
systemctl restart docker
```

:::

**3. 运行 GPU 容器**

```bash
# 验证 GPU 可用
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

# 指定 GPU（只用第 0 张）
docker run --rm --gpus device=0 nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

# 指定多张 GPU
docker run --rm --gpus device=0,1 nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

# 限制 GPU 显存（实验性）
docker run --rm --gpus all \
  -e NVIDIA_VISIBLE_DEVICES=0 \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
```

**4. Docker Compose 中使用 GPU**

```yaml
services:
  ai:
    image: nvidia/cuda:12.4.0-base-ubuntu22.04
    command: nvidia-smi
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
```

Podman 也支持 NVIDIA GPU，通过 `--device` 和环境变量：

```bash
# Podman 使用 NVIDIA GPU
podman run --rm \
  --device /dev/dri \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
```

也可使用 nvidia-container-toolkit 提供的 `nvidia-container-runtime`：

```bash
podman run --rm --runtime nvidia \
  -e NVIDIA_VISIBLE_DEVICES=all \
  nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
```

#### AMD GPU

AMD GPU 通过 ROCm 和 `/dev/dri` 设备映射实现容器内使用。

```bash
# 暴露 DRI 设备
docker run --rm \
  --device /dev/dri \
  -e HSA_OVERRIDE_GFX_VERSION=10.3.0 \
  rocm/pytorch:latest \
  python -c "import torch; print(torch.cuda.is_available())"

# 或使用 ROCm 官方镜像
docker run --rm \
  --device /dev/dri \
  --group-add=video \
  --cap-add=SYS_PTRACE \
  rocm/pytorch:latest rocm-smi
```

`HSA_OVERRIDE_GFX_VERSION` 需要根据实际 GPU 架构设置，常见值：

| GPU | GFX\_VERSION |
| --- | --- |
| RX 6800/6900 | 10.3.0 |
| RX 7600/7700/7800/7900 | 11.0.0 |
| RX 9070 | 12.0.1 |

#### Intel GPU

Intel GPU 通过 `/dev/dri` 设备映射 + Compute Runtime 实现。

```bash
# Intel Arc / 集显
docker run --rm \
  --device /dev/dri \
  --group-add=video \
  intel/oneapi-hpckit:latest \
  /opt/intel/oneapi/compiler/latest/bin/icpx --version

# SYCL / oneAPI 推理
docker run --rm \
  --device /dev/dri \
  intel/intel-extension-for-pytorch:latest \
  python -c "import torch; print(torch.xpu.is_available())"
```

| | NVIDIA | AMD | Intel |
| --- | --- | --- | --- |
| 方案 | NVIDIA Container Toolkit | ROCm + /dev/dri | Compute Runtime + /dev/dri |
| 安装复杂度 | 低（一行安装 toolkit） | 中（需配置环境变量） | 中 |
| 生态 | 最成熟 | ROCm 生态 | oneAPI 生态 |
| 典型场景 | CUDA 推理/训练 | ROCm 推理/训练 | SYCL / OpenVINO 推理 |
| Podman 支持 | ✓ | ✓ | ✓ |

## OrbStack

macOS 上替代 Docker Desktop 的轻量方案，基于 Apple 虚拟化框架，CPU 和内存占用远低于 Docker Desktop。

### 安装

```bash
# 下载安装
# https://orbstack.dev/

# 或 Homebrew
brew install orbstack
```

### 功能

* **Docker 引擎**：完全兼容 Docker CLI，直接 `docker run`
* **Linux 虚拟机**：秒启动 Linux 发行版（Ubuntu / Debian / Fedora 等），SSH 直连
* **文件共享**：macOS ↔ Linux 双向文件访问
* **网络互通**：容器服务通过 `localhost` 直接访问

### OrbStack vs Docker Desktop

| | OrbStack | Docker Desktop |
| --- | --- | --- |
| CPU 占用 | 极低（空闲几乎 0%） | 较高（常驻 1-5%） |
| 内存占用 | 最低 ~50MB | 最低 ~500MB |
| 启动速度 | < 2 秒 | 5-10 秒 |
| Docker CLI | ✓ | ✓ |
| Docker Compose | ✓ | ✓ |
| Linux VM | ✓ | ✗（只有 Docker） |
| 费用 | 个人免费 / 商业付费 | 个人免费 / 商业付费 |

```bash
# 安装后直接使用 docker 命令
orb start          # 启动（秒启动）
docker run -it ubuntu bash
docker compose up -d

# 管理 Linux VM
orb list            # 列出 VM
orb create ubuntu    # 创建 Ubuntu VM
orb ssh ubuntu      # SSH 连接
orb stop --all      # 停止全部
```

## Hyper-V

Windows Pro/Enterprise 内置的 Type 1 虚拟机管理程序，不需要额外安装软件。

### 启用

::: code-group

```powershell [PowerShell（管理员）]
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
# 重启后生效
```

```text [控制面板]
控制面板 → 程序 → 启用或关闭 Windows 功能 → 勾选 Hyper-V → 确定 → 重启
```

:::

### 常用操作

```powershell
# 创建虚拟机
New-VM -Name "test" -MemoryStartupBytes 2GB -NewVHDPath "C:\VM\test.vhdx" -NewVHDSizeBytes 20GB

# 启动 / 停止
Start-VM -Name "test"
Stop-VM -Name "test"

# 快照
Checkpoint-VM -Name "test" -SnapshotName "snap1"

# 连接控制台（GUI）
vmconnect.exe localhost test
```

Hyper-V 和 VMware / VirtualBox 共存可能出问题：

* **VMware Workstation 15.5.5+**：已兼容 Hyper-V，可共存
* **VirtualBox 6.1+**：官方说兼容，但实际不稳定
* **WSL2**：可和 Hyper-V 共存

如果 VMware/VirtualBox 运行异常，尝试关闭 Hyper-V：

```powershell
Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
# 重启
```

## VMware (Workstation / Fusion / ESXi)

VMware Workstation（Windows/Linux）和 VMware Fusion（macOS）是同一产品线，功能对应，操作方式一致。

### VMware Tools

VMware Tools 是 VMware 官方提供的增强工具包，安装后获得：

* 高分辨率显示 + 自动调整窗口大小
* 鼠标无缝移入移出（不需要 Ctrl+Alt 释放）
* 剪贴板共享（宿主 ↔ 虚拟机复制粘贴）
* 文件拖放
* 共享文件夹（宿主目录映射到虚拟机）
* 时间同步
* 更好的网络和存储驱动性能

**不装 VMware Tools**：只能用低分辨率，鼠标需手动释放，不能复制粘贴，体验很差。

### open-vm-tools vs VMware Tools

| | VMware Tools（官方闭源） | open-vm-tools（开源） |
| --- | --- | --- |
| 来源 | VMware 官方打包 | 社区维护，各大发行版官方仓库 |
| 安装方式 | 菜单安装 → 挂载 ISO → 手动编译 | `apt install open-vm-tools` |
| 更新方式 | 手动重新安装 | 包管理器自动更新 |
| 功能 | 全部功能 | 核心功能齐全，缺少数次要特性 |
| 推荐 | 仅当开源版本不工作时 | **优先选择** |

> **结论**：Linux 虚拟机优先装 `open-vm-tools`，省心且自动更新。只有遇到兼容性问题时才回退到官方闭源版本。Windows 虚拟机只能用官方 VMware Tools。

### 安装

::: code-group

```bash [open-vm-tools (Debian/Ubuntu)]
apt install open-vm-tools open-vm-tools-desktop
systemctl enable --now open-vm-tools
```

```bash [open-vm-tools (RHEL/CentOS)]
yum install open-vm-tools open-vm-tools-desktop
systemctl enable --now open-vm-tools
```

```bash [open-vm-tools (Arch Linux)]
pacman -S open-vm-tools
systemctl enable --now vmtoolsd
```

```text [官方 VMware Tools (Linux)]
1. VMware 菜单 → VM → Install VMware Tools
2. 虚拟机内挂载 ISO：
   mount /dev/cdrom /mnt
   tar xzf /mnt/VMwareTools-*.tar.gz -C /tmp
   sudo /tmp/vmware-tools-distrib/vmware-install.pl
3. 重启
```

```text [官方 VMware Tools (Windows)]
1. VMware 菜单 → VM → Install VMware Tools
2. 虚拟机内打开"此电脑"，双击光驱运行安装程序
3. 选择 Typical → 安装完成 → 重启
```

```text [官方 VMware Tools (Windows 7 x64)]
# Win7 需要旧版 VMware Tools，新版不兼容
# 下载 ISO：
# https://pan.feidu.fit/开发/常用工具/vmware_tools_w7_x64.iso
1. 下载 ISO 后挂载到虚拟机光驱
2. 虚拟机内打开光驱运行安装程序
3. 安装完成 → 重启
```

:::

安装后逐项验证：

| 功能 | 验证方法 |
| --- | --- |
| 高分辨率 | 调整窗口大小，分辨率自动跟随 |
| 鼠标释放 | 鼠标直接移出窗口，不需要 Ctrl+Alt |
| 剪贴板 | 宿主复制文本，虚拟机粘贴 |
| 拖放 | 从宿主桌面拖文件到虚拟机 |
| 共享文件夹 | `ls /mnt/hgfs/` （Linux）或资源管理器网络位置（Windows） |
| 时间同步 | `date` 对比宿主时间 |

共享文件夹不生效时手动挂载：

```bash
vmhgfs-fuse .host:/ /mnt/hgfs -o allow_other
```

**3D 加速不可用**：

open-vm-tools 默认不包含 3D 驱动，如需 3D 加速（桌面特效、GUI 渲染），安装官方 VMware Tools 或在 `.vmx` 中加 `mks.enable3d = "TRUE"`。

**共享文件夹为空**：

确保 VMware 设置中启用了共享文件夹，且虚拟机内 `vmhgfs-fuse` 可用：

```bash
# 检查模块
modprobe vmhgfs
lsmod | grep vmhgfs

# 手动挂载
vmhgfs-fuse .host:/shared /mnt/hgfs -o allow_other
```

**剪贴板不工作**：

需要同时安装 `open-vm-tools-desktop`（包含剪贴板和拖放组件）：

```bash
apt install open-vm-tools-desktop
```

**升级内核后工具失效**：

DKMS 模块在内核更新后自动重新编译，如果没装 DKMS：

```bash
apt install dkms
# 或重装
apt install --reinstall open-vm-tools-dkms
```

## VirtualBox Guest Additions

VirtualBox Guest Additions 是 VirtualBox 官方增强工具包，功能类似 VMware Tools。

### 功能

* 高分辨率 + 自动调整窗口大小
* 鼠标无缝移入移出
* 剪贴板共享
* 文件拖放
* 共享文件夹
* 时间同步
* 3D 加速（实验性）

**不装 Guest Additions**：低分辨率、鼠标需手动释放、不能复制粘贴。

### 安装

::: code-group

```text [Linux（推荐 vboxadditions 仓库版）]
# Debian/Ubuntu — 官方仓库版本，自动更新
apt install virtualbox-guest-additions-iso virtualbox-guest-dkms
modprobe vboxguest
```

```text [Linux（ISO 安装）]
1. VirtualBox 菜单 → 设备 → 安装增强功能
2. 虚拟机内挂载 ISO：
   mount /dev/cdrom /mnt
   sudo /mnt/VBoxLinuxAdditions.run
3. 重启
```

```text [Windows]
1. VirtualBox 菜单 → 设备 → 安装增强功能
2. 虚拟机内打开"此电脑"，双击光驱运行 VBoxWindowsAdditions.exe
3. 安装完成 → 重启
```

:::

| 功能 | 验证方法 |
| --- | --- |
| 高分辨率 | 调整窗口大小，分辨率自动跟随 |
| 鼠标释放 | 鼠标直接移出窗口 |
| 剪贴板 | 宿主复制文本，虚拟机粘贴 |
| 拖放 | 从宿主桌面拖文件到虚拟机 |
| 共享文件夹 | `ls /mnt/shared/` （Linux）或网络位置（Windows） |
| 时间同步 | `date` 对比宿主时间 |

共享文件夹手动挂载：

```bash
mount -t vboxsf shared /mnt/shared
```

**内核更新后失效**：

需要 DKMS 自动重编译，确保安装了 DKMS：

```bash
apt install dkms
# 或重装
dpkg-reconfigure virtualbox-guest-dkms
```

**共享文件夹权限不足**：

```bash
# 将当前用户加入 vboxsf 组
sudo usermod -aG vboxsf $USER
# 重新登录生效
```

**3D 加速不可用**：

1. 虚拟机设置 → 显示 → 勾选"启用 3D 加速"
2. Guest Additions 中需安装 3D 组件
3. Linux 下 3D 支持有限，仅作实验用途

**剪贴板不工作**：

```bash
# 重启剪贴板服务
pkill VBoxClient
VBoxClient --clipboard
```

## KVM / QEMU / PVE Guest Tools

KVM 系虚拟机没有像 VMware/VirtualBox 那样的单一增强工具包，而是由多个独立组件组合提供等效功能。

### 组件总览

| 组件 | 功能 | 替代 VMware Tools 中的 |
| --- | --- | --- |
| virtio 驱动 | 高性能磁盘/网络/内存气球 | vmxnet / pvscsi 驱动 |
| QEMU Guest Agent | 关机/快照/信息查询 | VMware Tools 服务 |
| SPICE vdagent | 剪贴板/自适应分辨率/鼠标 | 剪贴板 + 自动调整 |
| rngd | 宿主熵源注入虚拟机 | 时间同步（部分） |
| acpid | 虚拟机响应关机信号 | 电源管理 |

### 安装

::: code-group

```bash [Debian/Ubuntu]
apt install qemu-guest-agent spice-vdagent virtio-dkms acpid rng-tools
systemctl enable --now qemu-guest-agent
systemctl enable --now spice-vdagentd
```

```bash [RHEL/CentOS]
yum install qemu-guest-agent spice-vdagent virtio-drivers acpid rng-tools
systemctl enable --now qemu-guest-agent
systemctl enable --now spice-vdagentd
```

```bash [Arch Linux]
pacman -S qemu-guest-agent spice-vdagent virtio-dkms acpid rng-tools
systemctl enable --now qemu-guest-agent
systemctl enable --now spice-vdagentd
```

```text [Windows]
1. 下载 VirtIO 驱动 ISO
   https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso
2. 安装驱动：
   - Balloon → vioserial → viostor → NetKVM → QEMU Guest Agent
3. PVE/ESXi：在虚拟机选项中启用 QEMU Guest Agent
```

:::

**virtio 驱动** — 半虚拟化驱动，性能远超模拟设备：

```bash
# 确认 virtio 磁盘在用
lsblk -o NAME,ROTA,TYPE | grep virtio
# 确认 virtio 网卡
ethtool -i eth0 | grep driver
# driver: virtio_net
```

| 模拟设备 | virtio 设备 | 性能差距 |
| --- | --- | --- |
| IDE / SATA | virtio-blk / virtio-scsi | 3~5 倍 |
| e1000 / rtl8139 | virtio-net | 2~3 倍 |
| VGA | virtio-gpu | 显著 |

**QEMU Guest Agent (qga)** — 宿主通过 virtio-serial 通道与虚拟机通信：

```bash
# 宿主侧查询虚拟机 IP
virsh domifaddr vm1
# 或
qm agent network-get-interfaces   # PVE

# 宿主侧正常关机
virsh shutdown vm1   # 需要 qga，否则只能强制断电
```

PVE 中创建虚拟机时勾选 "QEMU Guest Agent"，否则关机按钮等于断电。

**SPICE vdagent** — SPICE 协议的增强代理：

* 剪贴板双向共享
* 窗口大小自适应
* 鼠标无缝移入
* 需要显示协议为 SPICE（PVE 默认），VNC 下不生效

**acpid** — 让虚拟机响应 ACPI 电源按钮：

```bash
# 没有 acpid 时，宿主发 shutdown 信号虚拟机无反应
# 有 acpid 后，虚拟机正常关机
systemctl enable --now acpid
```

PVE 创建虚拟机时建议在"选项"中启用：

1. **QEMU Guest Agent** — 勾选启用
2. **SPICE** — 显示选 SPICE（而非 VNC），自动支持剪贴板和自适应分辨率
3. **virtio** — 磁盘总线选 VirtIO，网卡模型选 VirtIO
4. **acpid** — PVE 默认已启用 ACPI

Windows 虚拟机额外步骤：

1. 挂载 VirtIO 驱动 ISO
2. 安装所有 VirtIO 驱动 + QEMU Guest Agent (MSI)
3. 安装 SPICE Guest Tools：https://www.spice-space.org/download/windows-spice-guest-tools/

## 网络模式

虚拟机的网络连接方式决定了虚拟机能否被外部访问、能否和宿主互通、能否上网。

### 四种模式对比

| | NAT | 桥接（Bridged） | Host-Only | Mirror / 镜像 |
| --- | --- | --- | --- | --- |
| 虚拟机能否上网 | ✓（通过宿主 NAT） | ✓（直接用物理网络） | ✗（和宿主互通，不能上网） | ✓ |
| 宿主能否访问虚拟机 | ✗（默认不可） | ✓（同一网段直连） | ✓（虚拟内网互通） | ✓ |
| 外部能否访问虚拟机 | ✗ | ✓（和物理机平等） | ✗ | 看配置 |
| 虚拟机 IP | 虚拟内网 IP（VMnet8 / vboxnet0） | 物理网络真实 IP | 虚拟内网 IP（VMnet1 / vboxnet1） | 和宿主同 IP 或自定义 |
| IP 是否会变 | 不会（虚拟内网固定网段） | 可能变（DHCP 分配） | 不会 | 不会 |
| 典型场景 | 日常开发（只需上网） | 需要被外部访问（服务部署） | 宿主和虚拟机互通，不需要上网 | macOS 虚拟机与宿主共享网络 |

```mermaid
flowchart TB
  subgraph NAT["NAT 模式"]
    direction LR
    H1[宿主] --> R1[虚拟 NAT 路由器]
    R1 --> VM1[虚拟机\n192.168.xxx.xxx]
    EXT1[外部] -.->|不可达| VM1
  end

  subgraph Bridged["桥接模式"]
    direction LR
    H2[宿主\n192.168.1.10] --- SW[物理交换机]
    SW --- VM2[虚拟机\n192.168.1.20]
    EXT2[外部] -->|可达| VM2
  end

  subgraph HostOnly["Host-Only 模式"]
    direction LR
    H3[宿主\n192.168.56.1] --- VSW[虚拟交换机]
    VSW --- VM3[虚拟机\n192.168.56.101]
    NET3[互联网] -.->|不可达| VM3
  end

  subgraph Mirror["Mirror 模式"]
    direction LR
    H4[宿主] <--> VM4[虚拟机\n共享宿主网络栈]
  end
```

### 快速判断

| 需求 | 推荐 |
| --- | --- |
| 虚拟机只要能上网 | NAT |
| 虚拟机要被局域网其他设备访问 | 桥接 |
| 虚拟机要和宿主互通但不需要上网 | Host-Only |
| 宿主 + 虚拟机互通 + 都能上网 | NAT + Host-Only 双网卡 |
| macOS 虚拟机最简配置 | Mirror |
| 调试现场设备（需要真实网络身份） | 桥接 |

### NAT

虚拟机通过宿主 NAT 上网，对外显示宿主的 IP，外部无法主动访问虚拟机。最常用的默认模式。

**特点**：

* 虚拟机可上网，宿主不能直接访问虚拟机
* 多台虚拟机之间互通
* 外部设备无法访问虚拟机
* IP 不会随物理网络变化

::: code-group

```text [VMware]
虚拟机设置 → 网络适配器 → NAT 模式
虚拟网络：VMnet8（NAT）
默认网段：192.168.xxx.0/24
```

```text [VirtualBox]
设置 → 网络 → 网卡 1 → 连接方式：网络地址转换(NAT)
```

```text [Hyper-V]
默认交换机(Default Switch) = NAT 模式
虚拟机 → 设置 → 网络适配器 → 默认交换机
```

```text [KVM / QEMU]
# 默认就是 NAT（user 模式）
qemu-system-x86_64 -m 2G -hda disk.qcow2
# 虚拟机自动 NAT 上网，宿主不能直接访问
```

```text [PVE]
默认网络就是 NAT（通过 vmbr0）
虚拟机 → 硬件 → 网络设备 → 桥接 vmbr0
注意：PVE 默认是桥接，不是 NAT
```

:::

### 桥接（Bridged）

虚拟机直接连接物理网络，获得和宿主同网段的真实 IP，外部设备可以直接访问。

**特点**：

* 虚拟机和宿主在网络上是平等的
* 可被局域网内其他设备访问
* IP 由物理网络 DHCP 分配，可能变化
* 适合部署服务、被外部访问

::: code-group

```text [VMware]
虚拟机设置 → 网络适配器 → 桥接模式
虚拟网络：VMnet0（桥接）
可选自动桥接或指定物理网卡
```

```text [VirtualBox]
设置 → 网络 → 网卡 1 → 连接方式：桥接网卡
选择要桥接的物理网卡名称
```

```text [Hyper-V]
新建外部虚拟交换机：
虚拟交换机管理器 → 新建虚拟交换机 → 外部 → 选择物理网卡
虚拟机 → 设置 → 网络适配器 → 选择外部交换机
```

```bash [KVM / QEMU]
# 需要创建桥接网卡（宿主端）
ip link add name br0 type bridge
ip link set br0 up
ip link set eth0 master br0   # 把物理网卡加入桥

# QEMU 使用桥接
qemu-system-x86_64 -m 2G \
  -netdev bridge,id=net0,br=br0 \
  -device virtio-net-pci,netdev=net0 \
  -hda disk.qcow2
```

```text [PVE]
默认就是桥接模式（vmbr0 桥接物理网卡）
虚拟机 → 硬件 → 网络设备 → 桥接 vmbr0
如需多网卡：创建多个桥接（vmbr1, vmbr2 ...）
```

:::

WiFi 网卡做桥接有限制：

* **VMware**：WiFi 桥接可能不稳定，建议用有线
* **VirtualBox**：WiFi 桥接可用，但需选对网卡名
* **Hyper-V**：WiFi 外部交换机可用
* **KVM / QEMU**：WiFi 桥接需要 `iw` 设置 4addr，否则不能用 bridge

```bash
# KVM WiFi 桥接（需要无线驱动支持 4addr）
iw dev wlan0 set 4addr on
ip link set wlan0 master br0
```

如果 WiFi 桥接不行，改用 NAT + 端口转发，或用 Host-Only。

### Host-Only

虚拟机和宿主组成一个隔离的虚拟内网，不能上网，但宿主和虚拟机可以互相访问。

**特点**：

* 宿主 ↔ 虚拟机互通
* 虚拟机之间互通
* 不能访问外网
* IP 固定不变

::: code-group

```text [VMware]
虚拟机设置 → 网络适配器 → 仅主机模式
虚拟网络：VMnet1（Host-Only）
默认网段：192.168.xxx.0/24
```

```text [VirtualBox]
设置 → 网络 → 网卡 1 → 连接方式：仅主机(Host-Only)适配器
选择 VirtualBox Host-Only Ethernet Adapter
```

```text [Hyper-V]
新建内部虚拟交换机：
虚拟交换机管理器 → 新建虚拟交换机 → 内部
虚拟机 → 设置 → 网络适配器 → 选择内部交换机
```

```bash [KVM / QEMU]
# 创建 host-only 网络（libvirt）
virsh net-define /dev/stdin <<EOF
<network>
  <name>hostonly</name>
  <forward mode='none'/>
  <ip address='192.168.57.1' netmask='255.255.255.0'>
    <dhcp><range start='192.168.57.100' end='192.168.57.200'/></dhcp>
  </ip>
</network>
EOF
virsh net-start hostonly
virsh net-autostart hostonly

# 虚拟机使用该网络
```

```text [PVE]
PVE 无内置 Host-Only，可手动创建隔离网桥：
创建 vmbr1（不桥接任何物理网卡）→
分配 IP 给 vmbr1 →
虚拟机桥接 vmbr1
```

:::

最常用的组合：一块网卡 NAT 上网，一块网卡 Host-Only 让宿主访问。

**VMware**：

1. 网卡 1 → NAT 模式（上网）
2. 网卡 2 → 仅主机模式（宿主互通）

**VirtualBox**：

1. 网卡 1 → NAT（上网）
2. 网卡 2 → Host-Only 适配器（宿主互通）

```bash
# 虚拟机内确认双网卡
ip addr
# eth0: NAT（如 192.168.111.128）
# eth1: Host-Only（如 192.168.56.101）

# 宿主通过 Host-Only IP 访问
ssh user@192.168.56.101
```

### Mirror（镜像网络）

macOS 虚拟化框架（Apple Virtualization）和部分新方案支持的网络模式，虚拟机和宿主共享网络栈，IP 相同或自动共享。

**特点**：

* 不需要单独配置网络
* 虚拟机自动获得和宿主相同的网络能力
* 适合 macOS 上最简配置

::: code-group

```text [UTM (macOS)]
虚拟机 → 设置 → 网络 → 网络模式：共享(Shared)
等效于 Mirror，自动和宿主共享网络
```

```text [OrbStack]
默认就是 Mirror 模式
容器和 Linux VM 自动和宿主共享网络
localhost 端口互通
```

```text [Apple Virtualization.framework]
NetworkAddress = "shared"
// 虚拟机共享宿主网络栈
// Docker Desktop / OrbStack 底层用的就是这个
```

:::

> **注意**：Mirror 模式下虚拟机没有独立 IP，无法从外部单独访问。如需独立 IP，改用桥接。

## 固件与启动

虚拟机启动需要固件（Firmware），类似物理机的 BIOS/UEFI。

### BIOS vs UEFI

| | Legacy BIOS | UEFI |
| --- | --- | --- |
| 全称 | Basic Input/Output System | Unified Extensible Firmware Interface |
| 启动方式 | INT 13 中断读 MBR | EFI 分区读引导程序 |
| 磁盘限制 | ≤ 2 TB | 无限制 |
| 启动界面 | 文字菜单 | 图形菜单 + 鼠标 |
| 安全启动 | ✗ | Secure Boot |
| 常见场景 | 旧系统 / 兼容模式 | 现代 OS 默认 |

**选择建议**：

* 调试现代 Linux（2015+）→ **UEFI**
* 调试旧系统 / 嵌入式旧镜像 → **BIOS**
* 不确定 → 优先 UEFI，不行再换 BIOS

### 各方案固件配置

::: code-group

```text [VMware]
设置 → 选项 → 高级 → 固件类型
- UEFI：默认（新建向导选 UEFI）
- BIOS：选"传统 BIOS"
```

```text [VirtualBox]
设置 → 系统 → 主板 → 扩展固件
- UEFI：勾选"启用 EFI"
- BIOS：默认（不勾选）
```

```text [Hyper-V]
创建虚拟机 → 安装选项 → 固件
- BIOS：默认（Generation 1）
- UEFI：选 Generation 2
注意：Gen 1 和 Gen 2 创建后不可互转
```

```text [KVM / QEMU]
# UEFI 需要安装 OVMF 固件
apt install ovmf

# BIOS 模式（默认）
qemu-system-x86_64 -m 2G -hda disk.qcow2

# UEFI 模式
qemu-system-x86_64 -m 2G \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
  -drive if=pflash,format=raw,file=/usr/share/OVMF/OVMF_VARS.fd \
  -hda disk.qcow2
```

```text [Proxmox VE]
创建虚拟机 → "OS 类型" 选项卡
- BIOS：SeaBIOS（默认，Legacy BIOS）
- UEFI：OVMF（需勾选"QEMU/Machine"为 q35）
- 注意：UEFI 虚拟机需要 EFI 磁盘（PVE 自动创建）
```

```text [ESXi]
创建虚拟机 → 虚拟机选项 → 引导选项 → 固件
- BIOS：默认
- UEFI：手动选择 EFI
```

:::

Secure Boot 是 UEFI 的安全功能，只允许签名过的引导程序启动。调试环境通常需要**关闭**。

* **VMware**：默认关闭，无需处理
* **VirtualBox**：不支持 Secure Boot
* **Hyper-V**：Gen 2 默认启用，可在虚拟机设置中关闭
* **KVM/QEMU**：OVMF 默认关闭，如需启用加参数 `-global driver=cfi.pflash,secure=on`
* **PVE**：OVMF 模板默认关闭，可在"选项 → 引导顺序"中启用
* **ESXi**：创建 VM 时可选，默认关闭

## 设备直通

设备直通（Passthrough）让虚拟机直接访问物理硬件，性能接近裸机。常见场景：GPU 渲染、USB 串口调试、PCIe 采集卡、加密狗。

### 直通类型

| 类型 | 说明 | 性能 |
| --- | --- | --- |
| USB 直通 | 最简单，大多数方案支持 | 略有延迟 |
| PCIe 直通 | 整卡直通，需要 IOMMU | 接近裸机 |
| GPU 直通 | PCIe 直通的特殊情况，需额外配置 | 接近裸机 |
| 串口直通 | 透传宿主机 /dev/ttyUSBx | 等效直连 |

### 各方案直通支持

::: code-group

```text [VMware Workstation]
USB 直通：✓（菜单 → VM → Removable Devices）
PCIe 直通：✗（Workstation 不支持）
GPU 直通：✗
串口直通：✓（添加串口设备 → 使用主机端口）
```

```text [VirtualBox]
USB 直通：✓（需安装 Extension Pack）
PCIe 直通：✗
GPU 直通：✗
串口直通：✓（设置 → 串口 → 启用）
```

```text [Hyper-V]
USB 直通：✗（需用 Enhanced Session 或 usbipd-win）
PCIe 直通：✓（DDA，需 PowerShell 配置）
GPU 直通：✓（RemoteFX / DDA）
串口直通：✓（命名管道）

启用 DDA 直通：
1. 获取设备 Location Path：Get-PnpDevice | Where-Object {$_.Status -eq "OK"}
2. 解挂设备并分配给 VM
```

```text [KVM / QEMU]
USB 直通：✓（-usb -device usb-host,hostbus=x,hostaddr=y）
PCIe 直通：✓（需要 IOMMU + vfio-pci）
GPU 直通：✓（NVIDIA/AMD 均可）
串口直通：✓（-serial /dev/ttyUSB0）

启用 IOMMU：
1. 宿主内核参数加 intel_iommu=on 或 amd_iommu=on
2. 绑定设备到 vfio-pci 驱动
3. QEMU 启动参数加 -device vfio-pci,host=xx:xx.x
```

```text [Proxmox VE]
USB 直通：✓（Web 界面 → 硬件 → 添加 → USB 设备）
PCIe 直通：✓（Web 界面 → 硬件 → 添加 → PCI 设备）
GPU 直通：✓（Web 界面操作，支持 NVIDIA/AMD）
串口直通：✓（编辑配置文件添加串口）

前提：宿主内核开启 IOMMU
1. GRUB 加参数：intel_iommu=on iommu=pt
2. update-grub && reboot
3. 检查：dmesg | grep -e DMAR -e IOMMU
```

```text [ESXi]
USB 直通：✓（vSphere Client → 添加 USB 设备）
PCIe 直通：✓（需在主机配置 → 硬件 → PCI 设备中标记直通）
GPU 直通：✓（标记直通后需重启）
串口直通：✓（添加串口设备）

前提：标记直通设备后必须重启主机
```

:::

**1. 宿主开启 IOMMU**

```bash
# /etc/default/grub
GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt"
# AMD CPU 用 amd_iommu=on

update-grub   # Debian/Ubuntu
grub2-mkconfig -o /boot/grub2/grub.cfg   # RHEL/CentOS
reboot
```

**2. 验证 IOMMU**

```bash
dmesg | grep -e DMAR -e IOMMU | head
# 应看到 DMAR: Host address width 或 Adding IOMMU device

# 检查 IOMMU 分组
ls /sys/kernel/iommu_groups/
```

**3. 绑定设备到 vfio-pci**

```bash
# 查看设备地址
lspci -nn | grep -i nvidia   # 示例：01:00.0

# 查看设备 vendor:device ID
lspci -n -s 01:00.0
# 示例：10de:1b06

# 绑定 vfio-pci
echo "options vfio-pci ids=10de:1b06" > /etc/modprobe.d/vfio.conf
echo "vfio-pci" >> /etc/initramfs-tools/modules   # Debian/Ubuntu
update-initramfs -u
reboot
```

**4. QEMU 直通启动**

```bash
qemu-system-x86_64 \
  -m 4G \
  -enable-kvm \
  -device vfio-pci,host=01:00.0 \
  -hda disk.qcow2
```

**4a. PVE 直通**

在 PVE Web 界面：虚拟机 → 硬件 → 添加 → PCI 设备 → 选择设备 → 勾选"所有功能"和"ROM-Bar"→ 添加。

**NVIDIA 卡报 Code 43 错误**：NVIDIA 驱动检测到虚拟机后拒绝工作。

解决：对 QEMU 隐藏虚拟机标识：

```bash
# QEMU 参数
-cpu host,kvm=off \
-smbios type=1,manufacturer="LENOVO",product="ThinkPad"
```

PVE：虚拟机 → 硬件 → CPU → 勾选"隐藏 KVM 状态"。

**多 GPU 环境**：宿主机用一个 GPU 显示，另一个直通给虚拟机。需要确保宿主 GPU 不被 vfio-pci 抢走。

**无头（headless）GPU 直通**：不需要显示器接在直通 GPU 上，用 Looking Glass 或 Moonlight 远程看画面。

## 嵌入式调试场景

```bash
# 安装 ARM 交叉编译和 QEMU
apt install qemu-system-arm gcc-arm-linux-gnueabihf

# 模拟 ARM vexpress（常用嵌入式开发板）
qemu-system-arm \
  -M vexpress-a9 \
  -m 512M \
  -kernel zImage \
  -dtb vexpress-v2p-ca9.dtb \
  -drive file=rootfs.ext4,if=sd \
  -append "console=ttyAMA0 root=/dev/mmcblk0" \
  -nographic

# 模拟 ARM64 / AArch64
qemu-system-aarch64 \
  -M virt \
  -m 1G \
  -cpu cortex-a57 \
  -kernel Image \
  -drive file=rootfs.ext4,if=virtio \
  -append "console=ttyAMA0 root=/dev/vda" \
  -nographic
```

将宿主机 USB 串口设备直接透传给虚拟机，在虚拟机内用 minicom/picocom 调试。

```bash
# 宿主机确认串口设备
ls /dev/ttyUSB*

# QEMU 串口直通
qemu-system-x86_64 \
  -m 2G \
  -serial /dev/ttyUSB0 \
  -hda disk.qcow2

# VMware：添加串口 → 使用主机端口 → /dev/ttyUSB0
# PVE：编辑配置加 serial0: /dev/ttyUSB0
```

调试时频繁修改环境，快照可以随时回退到已知状态。

| 方案 | 快照操作 |
| --- | --- |
| VMware | 菜单 → VM → Snapshot → Take Snapshot |
| VirtualBox | 菜单 → 机器 → 拍摄快照 |
| Hyper-V | `Checkpoint-VM -Name "test" -SnapshotName "snap1"` |
| KVM / QEMU | `virsh snapshot-create-as vm1 snap1` |
| PVE | Web 界面 → 虚拟机 → 快照 → 拍摄 |
| ESXi | vSphere Client → 快照 → 生成快照 |
| Docker | `docker commit` / `docker save` |
| Podman | `podman commit` / `podman save` |

## 注意

* 开发调试优先选 VMware / VirtualBox，省时省心。
* macOS 日常用 Parallels Desktop 体验最好（Coherence 窗口融合），Fusion 个人免费。
* Windows 跑 Linux 命令优先 WSL2，比虚拟机轻量很多。
* 性能敏感或需要直通，选 KVM / PVE / Hyper-V。
* QEMU 是唯一支持异构模拟（ARM/MIPS/RISC-V）的方案。
* 容器共享宿主内核，不能做内核级调试（驱动开发、内核模块测试）。
* UEFI 虚拟机磁盘用 GPT 分区表 + FAT32 EFI 分区，BIOS 虚拟机用 MBR。
* Hyper-V Gen 1（BIOS）和 Gen 2（UEFI）创建后不可互转，务必选好。
* 直通设备后宿主机**不能再用**该设备。
* GPU 直通需要 IOMMU 支持，老旧硬件可能不支持。
* PVE 和 ESXi 是裸机安装，不能在已有系统上直接运行。
* Docker Desktop 和 VMware 在 Windows 上可能冲突，WSL2 后端模式可共存。

---

---
url: /wiki/reference-docs.md
---

# 参考文档

研发过程中需要查阅的协议、接口和对接资料统一放在这里。产品视图、功能说明中只保留跳转入口，避免大文件预览打断主线内容。

## FD-01 密集架协议

---

---
url: /wiki/markdown-capabilities.md
---

# Markdown 增强写法

这个页面用于记录当前文档站支持的 Markdown 增强能力，后续写研发文档时可以直接参考。

## Tabs

::: tabs

\== Linux

```bash
pnpm docs:dev --host 127.0.0.1
```

\== Windows

```powershell
pnpm docs:dev --host 127.0.0.1
```

:::

## 代码组

::: code-group

```bash [pnpm]
pnpm docs:build
```

```bash [npm]
npm run docs:build
```

:::

## Mermaid

```mermaid
flowchart LR
  建档 --> 上架
  上架 --> 借阅
  借阅 --> 归还
  归还 --> 盘点
```

---

---
url: /wiki/showdoc-import.md
---
# ShowDoc 导入

本目录下的文档来自旧文档站 <https://doc.feidu.fit/>。

这些内容按原有分类迁入知识库，用于保留历史资料、运维记录、安装说明和研发过程文档。

---

---
url: /wiki/deployment-recommended-config.md
---
# 推荐配置

## 配置要求

| 字段 | 要求 |
| --- | --- |
| CPU | 最低 **4 核**，推荐 **8 核**及以上；单核频率建议 **2.5 GHz** 及以上 |
| 内存 | 最低 **16 GB**，推荐 **32 GB** 及以上 |
| 存储 | 最低 **256 GB**，推荐 **512 GB** 及以上 SSD |
| 网卡 | 无特殊要求；如果使用 Linux 方案，尽量避免 MTK 系列网卡 |
| 显卡 | 无特殊要求 |

## 参考资料

* <https://www.elastic.co/guide/en/cloud-enterprise/current/ece-hardware-prereq.html>

![](/static-file/8149152f-fc98-4585-87af-4c928b10b6e6/6528a0fe-59eb-42e6-950b-f588449ceb9b.png)

* <https://helpcenter.onlyoffice.com/installation/docs-community-sys-reqs-linux.aspx>

![](/static-file/28b651db-ec67-480e-afea-b18a62bedec7/5d04311a-0533-406a-a3bd-d6335fbbbe87.png)

* <https://min.io/product/reference-hardware>

![](/static-file/2e565bd4-1a7d-44f5-983f-de431f8a0845/8d66d14d-c27f-48ea-958c-d210aa3c584a.png)

* <https://docs.influxdata.com/influxdb/v1/guides/hardware_sizing/>

![](/static-file/1fa60b69-30c3-4ffe-b6ee-44cbf750ac87/cc4ae8ac-7792-42e4-87e4-59c76b17bfbe.png)

* <https://dev.mysql.com/doc/mysql-monitor/8.0/en/system-prereqs-reference.html>

![](/static-file/a16a22f6-ddb8-4737-91ee-17673235bf6f/ef78e77e-3509-4aaa-994e-d5a68bb87430.png)

---

---
url: /wiki/linux-system-update.md
---
# Linux 系统更新

## 前置操作

1. 把前后端两个文件放在下载目录下。
2. 在下载目录空白处右键，选择“打开终端”。

![](/static-file/617ac1a1-9f48-4b11-b800-f3e3adf103c5/f676e025-5c08-443f-9574-a1c83dfdf2fa.png)

## 更新后端文件

1. 切换到 root：

```bash
sudo su
```

2. 停止服务：

```bash
systemctl stop smart-doc-vault
```

![](/static-file/94d26ec2-22d5-40d9-99b5-0af2b5c772b8/b4291801-308d-4a5e-a79a-a8ac40860ff2.png)

3. 移动后端文件到 `/usr/bin/`：

```bash
mv 后端文件 /usr/bin/smart-doc-vault
```

4. 赋予执行权限：

```bash
chmod +x /usr/bin/smart-doc-vault
```

5. 启动服务：

```bash
systemctl start smart-doc-vault
```

## 更新前端文件

1. 将前端压缩包中的 `dist` 文件解压到当前目录。

![](/static-file/9215a41b-ecf4-4401-99ae-163aaed891d9/e1877d09-e425-4b25-a6b6-ad1728b9d436.png)

2. 删除原来的 `dist` 文件：

```bash
rm -rf /root/dist
```

3. 将解压后的前端文件移动到 `/root/`：

```bash
mv 前端文件 /root/
```

---

---
url: /wiki/windows-system-update.md
---
# # 更新前端文件

将下载后的前端文件解压后，拿到dist文件替换掉安装目录下的`{dist.zip}`文件

前端更新文件目录：

若是在D盘，则目录位置为 `D:\fit\sdv-test\SDV\config`
![](/static-file/e1719c44-43a5-4bed-82c7-1319b0a5d869/4e6bc69d-6887-4833-8dbe-9124f720a8dd.png)
![](/static-file/d10b8c54-c1ac-49f5-83c7-886873b6d3c7/37e389d4-84ff-4d39-b5e5-affeed61b106.png)

# 更新后端文件

先将服务停止运行

![](/static-file/5db3a9a4-1eb0-495a-9d3b-a6fea95edeb2/407616f1-2297-4db4-aafd-2593aa304370.png)

将下载好的后端文件`smart-doc-vault.exe`直接替换掉目录下的同名文件

若是在D盘，则目录位置为  D:\fit\sdv-test\SDV
![](/static-file/b4168208-012a-4ca2-94cc-4be1eb6e3287/0b1558a6-1e92-425a-bcda-abe73dee8987.png)

替换好后，启动服务运行

![](/static-file/a5ef8bc1-b19b-4139-b78a-f314c2402dca/17475092-7128-46c1-a8fb-9385e7bb8648.png)

等待页面初始化成功即可
![](/static-file/3f5d655e-1dea-4c63-9762-818330ae40da/612baee9-4c65-499c-b3b4-d75ccbe44fe1.png)

---

---
url: /wiki/dingtalk-oa-approval-guide.md
---
# 钉钉OA审批流程

获取地址：[产品授权及OA审批流程](https://pan.feidu.fit/d/%E5%BC%80%E5%8F%91/%E6%99%BA%E6%A1%A3%E5%AE%9D%E6%93%8D%E4%BD%9C%E8%AF%B4%E6%98%8E%E4%B9%A6%EF%BC%88%E7%BD%91%E7%9B%98%EF%BC%89/%E4%BA%A7%E5%93%81%E6%8E%88%E6%9D%83%E5%8F%8A%E5%AE%A1%E6%89%B9%E6%B5%81%E7%A8%8B/%E4%BA%A7%E5%93%81%E6%8E%88%E6%9D%83OA%E5%AE%A1%E6%89%B9%E6%B5%81%E7%A8%8B.pdf?sign=AeimusOO3fObMVeScbfvcmoHx7ZaZCdXPjTgJTG-XsU=:0 "产品授权及OA审批流程")

# 密集架授权说明

获取地址：[密集架授权说明](https://pan.feidu.fit/d/%E5%BC%80%E5%8F%91/%E6%99%BA%E6%A1%A3%E5%AE%9D%E6%93%8D%E4%BD%9C%E8%AF%B4%E6%98%8E%E4%B9%A6%EF%BC%88%E7%BD%91%E7%9B%98%EF%BC%89/%E4%BA%A7%E5%93%81%E6%8E%88%E6%9D%83%E5%8F%8A%E5%AE%A1%E6%89%B9%E6%B5%81%E7%A8%8B/%E5%AF%86%E9%9B%86%E6%9E%B6%E6%8E%88%E6%9D%83%E8%AF%B4%E6%98%8E.pdf?sign=PV5KgUCnu_yqdkI4ChoYOpUJbupClwD4kr55r5BLfqs=:0 "密集架授权说明")

# 智档宝系统授权说明

获取地址：[智档宝授权说明](https://pan.feidu.fit/d/%E5%BC%80%E5%8F%91/%E6%99%BA%E6%A1%A3%E5%AE%9D%E6%93%8D%E4%BD%9C%E8%AF%B4%E6%98%8E%E4%B9%A6%EF%BC%88%E7%BD%91%E7%9B%98%EF%BC%89/%E4%BA%A7%E5%93%81%E6%8E%88%E6%9D%83%E5%8F%8A%E5%AE%A1%E6%89%B9%E6%B5%81%E7%A8%8B/%E7%B3%BB%E7%BB%9F%E6%8E%88%E6%9D%83%E8%AF%B4%E6%98%8E.pdf?sign=ZXIjaqJ_xKkZiMwR3U92e9glYIJFDYlDbrt_lNIeXeQ=:0 "智档宝授权说明")

---

---
url: /wiki/maintenance-commands.md
---
# 常用维护命令

本页收集现场维护时常用的数据库、时序库和文件存储命令。命令默认按智档宝常见部署参数编写，执行前先确认现场实际账号、端口、容器名和安装目录。

## 通用约定

常见默认值：

| 服务 | 默认值 |
| --- | --- |
| MySQL | 用户 `root`，密码 `123456`，库名 `tdpub`，Linux Docker 端口常见 `3307`，老手动环境常见 `3306` |
| InfluxDB | org `fit`，bucket `sdv`，token `abc123123123abc`，端口 `8086` |
| MinIO | endpoint `http://127.0.0.1:9000`，用户 `admin`，密码 `admin123456`，bucket `fit` |
| Redis/KV | 参考 `redis-dump-go`，现场按实际 Redis 连接参数执行 |

建议先统一创建一个带时间戳的备份目录：

::: code-group

```bash [Linux]
TS=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="$PWD/backup-$TS"
mkdir -p "$BACKUP_DIR"/{mysql,influxdb,minio,redis}
```

```powershell [Windows PowerShell]
$TS = Get-Date -Format 'yyyyMMdd-HHmmss'
$BACKUP_DIR = Join-Path (Get-Location) "backup-$TS"
New-Item -ItemType Directory -Force `
  "$BACKUP_DIR\mysql", "$BACKUP_DIR\influxdb", "$BACKUP_DIR\minio", "$BACKUP_DIR\redis" | Out-Null
```

:::

> 恢复类命令会覆盖或删除目标数据。恢复前先停止业务写入，并再次备份当前现场数据。

## 通用命令

### MinIO / 文件存储备份与恢复（mc）

首次使用前配置别名：

::: code-group

```bash [Linux]
mc alias set sdv-minio http://127.0.0.1:9000 admin admin123456
mc ls sdv-minio/fit
```

```powershell [Windows PowerShell]
.\mc.exe alias set sdv-minio http://127.0.0.1:9000 admin admin123456
.\mc.exe ls sdv-minio/fit
```

:::

备份 bucket：

::: code-group

```bash [Linux]
mc mirror --overwrite sdv-minio/fit "$BACKUP_DIR/minio/fit"
```

```powershell [Windows PowerShell]
.\mc.exe mirror --overwrite sdv-minio/fit "$BACKUP_DIR\minio\fit"
```

:::

恢复 bucket：

::: code-group

```bash [Linux]
mc mirror --overwrite "$BACKUP_DIR/minio/fit" sdv-minio/fit
```

```powershell [Windows PowerShell]
.\mc.exe mirror --overwrite "$BACKUP_DIR\minio\fit" sdv-minio/fit
```

:::

如果现场旧文档使用别名 `minio`，也可以继续使用：

::: code-group

```bash [Linux]
mc cp --recursive minio "$BACKUP_DIR/minio/backup"
mc cp --recursive "$BACKUP_DIR/minio/backup" minio
```

```powershell [Windows PowerShell]
.\mc.exe cp --recursive minio "$BACKUP_DIR\minio\backup"
.\mc.exe cp --recursive "$BACKUP_DIR\minio\backup" minio
```

:::

### InfluxDB 时序数据库备份与恢复

备份：

::: code-group

```bash [Linux]
influx backup \
  --host http://127.0.0.1:8086 \
  --bucket sdv \
  --org fit \
  --token abc123123123abc \
  "$BACKUP_DIR/influxdb"
```

```powershell [Windows PowerShell]
.\influx.exe backup `
  --host http://127.0.0.1:8086 `
  --bucket sdv `
  --org fit `
  --token abc123123123abc `
  "$BACKUP_DIR\influxdb"
```

:::

恢复前通常需要删除旧 bucket，再恢复备份。确认无误后执行：

::: code-group

```bash [Linux]
influx bucket delete -n sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086
influx restore --bucket sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086 "$BACKUP_DIR/influxdb"
```

```powershell [Windows PowerShell]
.\influx.exe bucket delete -n sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086
.\influx.exe restore --bucket sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086 "$BACKUP_DIR\influxdb"
```

:::

按时间范围删除时序数据：

::: code-group

```bash [Linux]
influx delete \
  --bucket sdv \
  --start 2020-03-01T00:00:00Z \
  --stop 2024-05-08T00:00:00Z \
  --org fit \
  --token abc123123123abc \
  --host http://127.0.0.1:8086
```

```powershell [Windows PowerShell]
.\influx.exe delete `
  --bucket sdv `
  --start 2020-03-01T00:00:00Z `
  --stop 2024-05-08T00:00:00Z `
  --org fit `
  --token abc123123123abc `
  --host http://127.0.0.1:8086
```

:::

### MySQL 业务库备份与恢复

备份：

::: code-group

```bash [Linux]
mysqldump \
  -h 127.0.0.1 \
  -P 3307 \
  -uroot \
  -p123456 \
  --single-transaction \
  --routines \
  --triggers \
  --events \
  --default-character-set=utf8mb4 \
  tdpub > "$BACKUP_DIR/mysql/tdpub.sql"
```

```powershell [Windows PowerShell]
.\mysqldump.exe `
  -h 127.0.0.1 `
  -P 3307 `
  -uroot `
  -p123456 `
  --single-transaction `
  --routines `
  --triggers `
  --events `
  --default-character-set=utf8mb4 `
  tdpub | Out-File -Encoding utf8 "$BACKUP_DIR\mysql\tdpub.sql"
```

:::

恢复：

::: code-group

```bash [Linux]
mysql -h 127.0.0.1 -P 3307 -uroot -p123456 --default-character-set=utf8mb4 tdpub < "$BACKUP_DIR/mysql/tdpub.sql"
```

```powershell [Windows PowerShell]
Get-Content "$BACKUP_DIR\mysql\tdpub.sql" | .\mysql.exe -h 127.0.0.1 -P 3307 -uroot -p123456 --default-character-set=utf8mb4 tdpub
```

:::

清空全部报警：

```sql
DELETE FROM alarm_models;
```

### Redis / KV 数据库备份与恢复

参考工具：<https://github.com/yannh/redis-dump-go>

::: code-group

```bash [Linux]
redis-dump-go -host 127.0.0.1 -port 6379 > "$BACKUP_DIR/redis/redis.json"
redis-dump-go -host 127.0.0.1 -port 6379 -import "$BACKUP_DIR/redis/redis.json"
```

```powershell [Windows PowerShell]
.\redis-dump-go.exe -host 127.0.0.1 -port 6379 | Out-File -Encoding utf8 "$BACKUP_DIR\redis\redis.json"
.\redis-dump-go.exe -host 127.0.0.1 -port 6379 -import "$BACKUP_DIR\redis\redis.json"
```

:::

## Linux 专用

### Docker 容器内执行 MySQL 备份

适合没有在宿主机安装 `mysql-client` 的 Linux Docker 离线包环境。容器名按现场调整，常见为 `mysql` 或 `sdv-mysql`。

```bash
TS=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="$PWD/backup-$TS"
mkdir -p "$BACKUP_DIR/mysql"

docker exec sdv-mysql sh -c 'mysqldump -uroot -p123456 --single-transaction --routines --triggers --events --default-character-set=utf8mb4 tdpub' \
  > "$BACKUP_DIR/mysql/tdpub.sql"
```

恢复：

```bash
docker exec -i sdv-mysql sh -c 'mysql -uroot -p123456 --default-character-set=utf8mb4 tdpub' \
  < "$BACKUP_DIR/mysql/tdpub.sql"
```

### Docker 容器内执行 InfluxDB 备份

如果宿主机没有 `influx` 命令，但容器内有：

```bash
TS=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="$PWD/backup-$TS"
mkdir -p "$BACKUP_DIR/influxdb"

docker exec sdv-influxdb influx backup \
  --bucket sdv \
  --org fit \
  --token abc123123123abc \
  /tmp/influx-backup

docker cp sdv-influxdb:/tmp/influx-backup "$BACKUP_DIR/influxdb"
docker exec sdv-influxdb rm -rf /tmp/influx-backup
```

恢复：

```bash
docker cp "$BACKUP_DIR/influxdb/influx-backup" sdv-influxdb:/tmp/influx-backup

docker exec sdv-influxdb influx bucket delete -n sdv --org fit --token abc123123123abc

docker exec sdv-influxdb influx restore \
  --bucket sdv \
  --org fit \
  --token abc123123123abc \
  /tmp/influx-backup
```

### 一次性打包所有备份文件

```bash
tar -czf "${BACKUP_DIR}.tar.gz" -C "$(dirname "$BACKUP_DIR")" "$(basename "$BACKUP_DIR")"
sha256sum "${BACKUP_DIR}.tar.gz" > "${BACKUP_DIR}.tar.gz.sha256"
```

### 数据库外网访问

仅临时排查使用，生产环境不建议开放 root 外网访问。

```bash
mysql -uroot -p123456
```

```sql
use mysql;
update user set host='%' where user ='root';
FLUSH PRIVILEGES;
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;
```

## Windows 专用

### Windows 运行目录备份示例

以常见 `sdv-test` 目录为例，先创建备份目录，再分别备份 MySQL、InfluxDB 和 MinIO。

```powershell
$TS = Get-Date -Format 'yyyyMMdd-HHmmss'
$BACKUP_DIR = "C:\Users\pc\Documents\sdv-test\backup-$TS"
New-Item -ItemType Directory -Force `
  "$BACKUP_DIR\mysql", "$BACKUP_DIR\influxdb", "$BACKUP_DIR\minio" | Out-Null
```

如果工具在运行目录下，先进入工具目录：

```powershell
cd C:\Users\pc\Documents\sdv-test
```

### Windows 备份 MinIO 文件内容

```powershell
.\mc.exe alias set sdv-minio http://127.0.0.1:9000 admin admin123456
.\mc.exe mirror --overwrite sdv-minio/fit "$BACKUP_DIR\minio\fit"
Compress-Archive -Path "$BACKUP_DIR" -DestinationPath "$BACKUP_DIR.zip"
```

恢复：

```powershell
Expand-Archive -Path "$BACKUP_DIR.zip" -DestinationPath (Split-Path $BACKUP_DIR) -Force
.\mc.exe mirror --overwrite "$BACKUP_DIR\minio\fit" sdv-minio/fit
```

### Windows 备份 MySQL

```powershell
.\mysqldump.exe -h 127.0.0.1 -P 3307 -uroot -p123456 --single-transaction --routines --triggers --events --default-character-set=utf8mb4 tdpub `
  | Out-File -Encoding utf8 "$BACKUP_DIR\mysql\tdpub.sql"
```

恢复：

```powershell
Get-Content "$BACKUP_DIR\mysql\tdpub.sql" `
  | .\mysql.exe -h 127.0.0.1 -P 3307 -uroot -p123456 --default-character-set=utf8mb4 tdpub
```

### Windows 备份 InfluxDB

```powershell
.\influx.exe backup --bucket sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086 "$BACKUP_DIR\influxdb"
```

恢复：

```powershell
.\influx.exe bucket delete -n sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086
.\influx.exe restore --bucket sdv --org fit --token abc123123123abc --host http://127.0.0.1:8086 "$BACKUP_DIR\influxdb"
```

---

---
url: /wiki/service-dependencies-ports.md
---
# 服务依赖及端口配置

## 服务依赖

* MySQL - 8.0.25
* Redis - 7.2.0
* InfluxDB - v2.7.6
* Minio
* Tika - 2.9.2
* ElasticSearch - 7.5.1
* Emqx - 5.6.1
* OnlyOffice - 7.5.0
* PostgreSQL - 14
* RabbitMQ - 3.13.0
* Erlang

## 端口占用

8888/tcp - 后端端口 - 开放
8991/tcp - office预览 - 老 - 和下面二选一
7001/tcp - office预览 - 新 - 和下面二选一
9998/tcp
6379/tcp
3306/tcp
9000/tcp - minio - 存储服务
9001/tcp - minio - 存储服务
9201/tcp
8086/tcp
7123/tcp - 调试端口
1883/tcp  - 设备通讯
10086/udp - 设备发现
80/tcp (如需另起 `ngnix` `caddy` 服务则修改)

---

---
url: /wiki/dcvm-3d-inspection-install.md
---
# 安装步骤

跳转至GlowJS文档中心查看，点击[安装教程](https://www.glowjs.com/docs/dcvm/start "安装教程")

# 使用手册

点击[跳转](https://www.glowjs.com/docs/dcvm/3d "跳转")查看

---

---
url: /wiki/nodenvr-install.md
---
# 安装步骤

跳转至GlowJS文档中心查看，点击[安装教程](https://www.glowjs.com/docs/nodenvr/ "安装教程")

# 使用手册

点击[跳转](https://www.glowjs.com/docs/nodenvr/guide "跳转")查看

---

---
url: /wiki/camera-interface-integration.md
---
# 监控设备接口

点击[跳转](https://www.glowjs.com/docs/dcvm/http-device "跳转")查看

---

---
url: /wiki/config-yaml-update.md
---
进入到目标目录`../sdv-test/SDV/config`

# 配置文件添加

`只要是需要更改配置文件的情况，都需要先停止后端服务`

## 空调温湿度交换

安装目录下 `config.yaml` 后面添加

```
# 特殊配置集合
dirty:
	isAirConditionerExchange: true       #空调温湿度交换只需增加前两行即可
	deviceOnlineMethod: "udp"
	customProductName: "飞度-CJOS5.0"
	customOSVersion: "测试版本"
```

之后 **重启服务端**

### 详解

#### isAirConditionerExchange

更新时间: 2024-05-23 10:06:33 星期四

作用: 交换空调温湿度

![](/static-file/d3801449-e45a-4678-847f-3274212c8b07/7509b316-c7f6-4e88-bd04-162a1e9e1e54.png)

项目经常会出现这个情况, 具体原因未知...但是每次定制太麻烦, 所以纳入 `特殊配置`

#### deviceOnlineMethod

更新时间: 2024-06-23

作用: 更改设备离线状态判断方法

默认值为 `udp` , 在 `udp` 异常但是 `mqtt` 正常的情况下 (例如网络环境屏蔽了 `udp`)

此时可以 替换为 `time` , 根据最近是否接收到设备消息来进行判断

#### customProductName && customOSVersion

更新时间: 2024-09-19

作用: 自定义软件名称和系统版本
更改对应位置为以下示例图
![](/static-file/dc0b7ad2-98bc-4440-98b7-a1ba058693ed/69b5c96c-74b7-4714-9149-8f408dd56526.png)
留空为默认

## 网卡配置

跳转至旧文档站查看 [网卡配置](https://doc.feidu.fit/web/#/632837618/182730287)。

## CPU占用内核分配

分配使用内和数量时，需先查看该服务器的内核总数量

```
system:
	cpu-cores: "auto" # 使用全部CPU核心(默认)
# 或
	cpu-cores: "4" # 示例：指定使用4个核心
```

---

---
url: /wiki/network-protocol-debug-urls.md
---
# 一些网络协议调试地址

## 调试端口

默认是 `7123`

![](/static-file/566b6ad5-e9cd-4092-b002-fa204a0de9f8/f9359f8a-d36b-4e93-bd4e-f2c01d245b8f.png)

**hzg** -> 回转柜 -> TCP server
**mjj** -> 密集架 -> TCP Client / USB (弃用)
**udp** -> 设备调试 -> UDP
**mqtt** -> 设备通信 -> MQTT

---

---
url: /wiki/smart-rack-integration-types.md
---
# 智能密集架/回转柜接入类型

| 接入类型  | 描述  |
| ------------ | ------------ |
| FD-01     | 方德密集架、中芯回转柜  |
| FD-02  |  北泰密集架 |
| FD-03  | 云档密集架  |
| FD-04  | 天骄密集架  |
|  FD-05 | 华升密集架 |
|  FD-06 | 飞度密集架 |
![](/static-file/493fc4b9-7c68-4935-94c3-977d3d593288/ac22305b-d0fe-43ce-9182-52ae12a2bffc.png)

---

---
url: /wiki/kylin-vnc-remote-desktop.md
---
# 麒麟 VNC 远程桌面

## 服务器

### 1. 启用 vino 服务

通过 UKUI 设置守护进程启用 vino：

```bash
busctl --user call org.ukui.SettingsDaemon.Sharing /org/ukui/SettingsDaemon/Sharing org.ukui.SettingsDaemon.Sharing EnableService s 'vino-server'
```

### 2. 关闭连接确认弹窗

```bash
gsettings set org.gnome.Vino prompt-enabled false
```

### 3. 设置认证方式为密码认证

```bash
gsettings set org.gnome.Vino authentication-methods "['vnc']"
```

### 4. 关闭强制加密

```bash
gsettings set org.gnome.Vino require-encryption false
```

### 5. 设置 VNC 密码

把 `12345678` 换成你想要的密码：

```bash
gsettings set org.gnome.Vino vnc-password $(echo -n '12345678' | base64)
```

### 6. 重启 vino

杀掉已有的 vino 进程：

```bash
pkill vino
```

启动 `vino-server`：

```bash
/usr/lib/vino/vino-server &
```

### 7. 验证服务是否运行

```bash
echo "=== VNC 进程 ==="
ps aux | grep vino | grep -v grep

echo "=== 端口监听状态 ==="
netstat -tlnp | grep 5900

echo "=== VNC 密码设置 ==="
gsettings get org.gnome.Vino vnc-password
```

## 客户端（Windows）

### VNC Viewer

下载地址：https://www.realvnc.com/en/connect/download/viewer/

网盘地址：https://pan.feidu.fit/d/%E5%BC%80%E5%8F%91/%E5%B8%B8%E7%94%A8%E5%B7%A5%E5%85%B7/VNC-Viewer-7.15.1-Windows.exe?sign=vwnj9pPuykCYNZU7YeeMc30h0wIr6cptRpppfZXCrsY=:0

下载后直接运行文件安装。

打开可视化界面，直接输入服务器 IP 并回车。

![](/static-file/a268b81d-27ed-4a07-a5b0-5db98a05aa0a/74d045b3-44cc-4445-bd38-e34472d2f43f.png)

输入密码，点击 OK。

![](/static-file/b2ebcc55-2eff-4db3-877e-92094704e2bb/45d949e5-3511-4005-a2a9-cc111b03b07b.png)

### MobaXterm

下载地址：https://download.mobatek.net/2542025111600034/MobaXterm\_Installer\_v25.4.zip

解压文件后运行 msi 文件进行安装。

![](/static-file/0f457ed6-23e2-41c9-8735-a9611fb8cc90/cdb5c160-92bc-46e8-a840-f3e493ee4138.png)

点击顶部的 “Session” 按钮。

![](/static-file/be2c0a56-63c6-49ea-9c7f-a443ff05e9a6/7863b143-91fa-4f28-b958-355d0b12bf85.png)

填写VNC连接信息：

* Remote hostname or IP address：输入麒麟系统的 IP 地址。
* Port：输入 VNC 服务端口号。
* 如果是桌面版配置的 `vino-server`（共享当前桌面），默认端口通常是 `5900`。
* 如果是服务器版配置的 `tigervnc-server`，`:1` 对应 `5901`，`:2` 对应 `5902`，以此类推。

![](/static-file/7a17c2d7-1358-4c6f-b52a-5504a7648a6f/f6f857e1-a759-4d2f-a698-e0a922096441.png)

填写 VNC 密码，例如 `12345678`。

![](/static-file/f589ba5c-5cc0-4eab-89df-c1abe8301ca2/ae9e227a-ff6f-4f3e-b378-1dc6c9a4f332.png)

选择 yes。

![](/static-file/fae00291-fa62-40da-a93a-4fe0c997550f/272ba778-4417-4aaf-a67b-202f012f8c40.png)

选择 cancel，第二次弹出也一样选择 cancel。

![](/static-file/fe7eca3f-67b8-4957-88b8-4f5a3a1a59e5/27bc57aa-ad82-4b55-96de-3e5d77c2e207.png)

完成。

![](/static-file/638d7dc3-ebfb-4a85-a11b-132feb15bbb1/d431441b-1ddb-488a-ad1a-200600be04cc.png)

---

---
url: /wiki/dev-meeting-2026-04-03.md
---
# 04-03清明前夕

## 会议内容

1. 总结上一阶段

* 整体进度
* 各自总结

2. 安排下一阶段工作

3. 反馈展会情况和销售情况

4. 总结

## 阶段

### 03-04 ~03-15 三合一 修完恶性 BUG

历史**第一次**按照预期完成任务

### 03-15 ~ 04-03

#### 两次展会

* zks:

* 数字化调优

* 参与windows版本修复工作

* 参与windows版本安装文档编写

* ljr:

* 稍微闲

* gl:

* 上传优化

* 一些细节bug优化

* `电子档案` 还有些小问题未处理

* lxr:
  * 代码质量优化
  * 除湿机状态之类的修复
  * 预览代码优化

* zmy
  * 监督bug修复
  * 还剩下一点问题
  * 基本没有恶性bug
  * 写说明书

* lym
  * 展会软件安装和调试
  * 文档编写, 优化软件发布流程

## 后续安排

* zks:
  * 兼容国产化的安装程序
  * 兼容国产化的安装程序对应的文档

* zmy
  * 测试windows版本, 协助漏洞修复和缺失内容
  * 优化测试流程, 记录版本发布

* gl

* 电子档案细节优化

* 其他细节优化

* lxr

* 提升代码质量

* 优化性能

## 意见

lxr 对代码质量评估有思考

对 `需求文档` 的诉求很强烈

对接过程需要优化, 可能也需要 `对接文档`

其他细节讨论

## 总结

展会总体反馈很好

**要做好自己的工作内容**

敢于建言献策

敢于沟通

**工作职责得清晰**

---

---
url: /wiki/remote-debugging-doc.md
---
# 远程调试文档

## 加入网络

### 前期准备

根据 [ZeroTier 官网](http://www.zerotier.com/) 安装 `zerotier`。

参考：<https://github.com/xubiaolin/docker-zerotier-planet?tab=readme-ov-file#4%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%85%8D%E7%BD%AE>

### 准备连接

替换完成 `planet` 文件后（私发），加入网络 ID `6744f4d5dcf18985` 即可。

## 服务器连接

SSH 连接方式如下。

### 服务器 2

地址: `10.21.21.118`
用户名: `root`
密码: `fd123456`

### 服务器 1（不在线）

地址: `10.21.21.36`
用户名: `root`
密码: `fd12345678`

```
[root@localhost ~]# lspci | grep NVIDIA
02:00.0 VGA compatible controller: NVIDIA Corporation Device 2504 (rev a1)
02:00.1 Audio device: NVIDIA Corporation Device 228e (rev a1)
81:00.0 VGA compatible controller: NVIDIA Corporation Device 2504 (rev a1)
81:00.1 Audio device: NVIDIA Corporation Device 228e (rev a1)
```

---

---
url: /wiki/environment-addresses.md
---
# 各环境地址总览

## 已废弃

| 名称 | 运行版本 | 连接方式 | 地址 | 备注 |
| --- | --- | --- | --- | --- |
| 测试环境 1 | Linux 镜像 | 直连 | [192.168.0.191](http://192.168.0.191) | 虚拟机 |
| 测试环境 2 | Linux 镜像 | 直连 | [192.168.0.212](http://192.168.0.212) | 虚拟机；之前测试 ES 用的；时序数据库待更新 |
| win 虚拟机测试环境 | Windows 版本 | 直连 | [192.168.0.211](http://192.168.0.211) | 移植 win 版本时创建 |
| win 物理机测试环境 | Windows 版本 | 直连 | [192.168.0.198](http://192.168.0.198) | 物理机；会议室里面的盒子 |
| 广东厂房环境 | Windows 版本 | 向日葵 | 714846083 / a123456 | MQTT 共享出来给办公室一些环境使用 |
| 演示环境 | Linux 镜像 | 直连 | [192.168.0.225](http://192.168.0.225) / [sdv.singzer.cn](http://sdv.singzer.cn) / [sdv.feidu.cn](http://sdv.feidu.cn) | 用于公网演示和官网演示；用户 `feidu` 的密码每天会自动更新 |

---

---
url: /wiki/sdv/uninstall.md
---
# 智档宝的卸载

\##卸载智档宝
1.停止服务
![](/static-file/91ea47fc-22de-45fe-9102-45c9a9528eda/2dd6129e-e2c6-428c-9aed-68af5adc7b34.png)
2.后台退出【智档宝-运行监控】
![](/static-file/1b52ba47-c348-46bb-b6b7-fe8fc1e61197/33806f50-28fa-47c8-ba52-c3a349067a5e.png)
3.找到软件安装目录，右键以管理员运行【uninstall.bat】文件
![](/static-file/35fec3df-5144-42f1-b4b9-222b17cc6d2b/baee3199-07a4-41e6-83f8-68eccbbf36ee.png)
4.直接删除文件即可
![](/static-file/ddda2d46-038e-4e2d-88f3-c463e80c63bc/17334786-6339-4b84-b609-9f17c0e01fbd.png)

---

---
url: /wiki/dust-table-power-on-boot.md
---
位置也可能在 `boot` 菜单, `G3` 状态改成 `S0` 即可

![](/static-file/9915a42a-e3d9-4acf-a904-832349fa9263/b2c3b8c5-2085-42ae-9d47-9b70c2ce887c.png)

以上是 `Intel` 主板 `BIOS` 的位置

`AMD` 系列的主板, 一般在

【Advanced】选项
![](/static-file/230c8c50-8265-4cf8-837d-0118e7932be4/a7d293ef-5b93-446a-bd97-fc974a903630.png)

【AMD CBS】选项
![](/static-file/66e02ff1-9e29-4499-b99c-9e78e35076f3/fc3c169d-7e05-4441-ab1d-8de617d9f480.png)

【FCH Common Options】选项
![](/static-file/cdb03e6b-65f2-4ac4-8c17-e1e44a4c7b15/b1f1c7e9-8187-4290-bc18-81757820798e.png)

最后在进入【Ac Power Loss Options】设置

![](/static-file/c5e8867b-8813-471b-a4c4-323a594b4ef4/bb58974a-5149-400b-822a-f769c95c61a3.png)

开启来电自启机就选择【Always on】， 关闭就选择【always off】

![](/static-file/7459d751-522f-4dfc-94a4-d61f4f46ffe8/9c8518c7-77fe-4b35-9dd5-8890575a000e.png)

# 最后别忘了 **保存设置** !!!

### ACPI (Advanced Configuration and Power Interface) 简介

ACPI，全名为Advanced Configuration and Power Interface，即进阶组态与电源接口。

基本上分为以下几个状态：

* G0（也称为S0）
* G1（细分为S1、S2、S3、S4）
* G2（也称为S5）
* G3

#### G0 正常开机状态

在此状态下，几乎所有的组件都在供电和运作。但在这个状态下，也允许少部分的组件进入低耗电状态（例如：光驱、硬盘）。

#### G1 睡眠状态

G1 状态进一步细分为S1、S2、S3、S4。

* **S1** 这是一个较高耗电的睡眠状态，CPU和内存都会持续供电，而非使用中的硬件则不供电。较新的主板可能不支持S1睡眠。

* **S2** 比S1省电些，CPU不供电，但内存持续供电。S2模式没有被广泛使用。

* **S3** 这是最常用的睡眠模式。在S3模式下，计算机运行中的数据会挂载到内存中，然后保持内存供电，绝大部分其他设备断电。在Windows XP中称为待机，在Windows Vista和Windows 7中称为睡眠。

* **S4** 在S4模式下，运行中的数据会挂载到硬盘，即使在睡眠中发生断电，数据也不会受影响。

#### G2 一般关机状态

关机后，部分周边设备依然供电，以支持开机唤醒（G2状态等于计算机关机后，但没有关闭电源或拔除插头）。

#### G3 完全断电状态

关闭电源或拔除插头，即一般需要拔插硬件的状态。

---

---
url: /wiki/electron-packaged-images-fix.md
---
# 解决 Electron 打包后部分图片不显示的暂行方案

## 原因

Electron 打包时，Vite 只会把显式 URL 引用到的资源打包进去。隐式 URL 资源不会自动进入构建产物，因此运行后会出现图片路径找不到的问题。

![](/static-file/610528f6-b46b-4edd-8830-d43054ed1c40/7abd9c75-d129-41e9-a729-c22ad18be846.png)

## 示例 1：显式引入背景图

前提：已经把 `public` 文件夹拷贝到了 `assets` 文件夹下。

```javascript
function background() {
  // 显式 URL 引入路径
  const img1 = new URL('@/assets/public/bigscreen/background/img(1).png', import.meta.url).href
  const img2 = new URL('@/assets/public/bigscreen/background/img(2).png', import.meta.url).href
  const img3 = new URL('@/assets/public/bigscreen/background/img(3).png', import.meta.url).href

  // 之前的写法
  // switch (screenInfo.value.backgroundStyle) {
  //   case '1':
  //     return `url('/bigscreen/background/img(1).png') no-repeat`
  //   case '2':
  //     return `url('/bigscreen/background/img(2).png') no-repeat`
  //   case '3':
  //     return `url('/bigscreen/background/img(3).png') no-repeat`
  // }

  switch (screenInfo.value.backgroundStyle) {
    case '1':
      return `url('${img1}') no-repeat`
    case '2':
      return `url('${img2}') no-repeat`
    case '3':
      return `url('${img3}') no-repeat`
  }
}
```

## 示例 2：组件图片改为变量路径

原写法：

```html
<a-image
  width="101"
  height="101"
  :preview="false"
  src="/static/helpImg/m.png"
></a-image>
```

替换为：

```html
<a-image
  width="101"
  height="101"
  :preview="false"
  :src="meImg"
></a-image>
```

```javascript
const meImg = new URL('@/assets/public/static/helpImg/m.png', import.meta.url).href
```