THENG
/
thingsboard
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
thingsboard/summary/07-DEB包说明.md

316 lines
8.7 KiB
Markdown
Raw Permalink Normal View History

first commit
2026-01-19 11:50:37 +08:00
# DEB 包说明
## 1. 什么是 DEB 包
### 1.1 基本概念
**DEB** (Debian Package) 是 Debian 及其衍生 Linux 发行版（如 Ubuntu）使用的软件包格式。类似于 Windows 的 `.exe` 安装程序或 macOS 的 `.pkg` 安装包。
### 1.2 文件格式
- **文件扩展名**: `.deb`
- **内部结构**: 使用 `ar` 归档格式（类似于 tar）
- **包含内容**:
- 控制信息（包的元数据、依赖关系等）
- 数据文件（应用程序文件、配置文件等）
### 1.3 安装方式
```bash
# 安装 DEB 包
sudo dpkg -i package.deb
# 或者使用 apt（会自动处理依赖）
sudo apt install ./package.deb
```
## 2. ThingsBoard 为什么使用 DEB 包
### 2.1 优势
1. **标准化安装**: 统一的安装位置和文件结构
2. **依赖管理**: 自动检查和处理依赖关系（如 Java 17）
3. **系统集成**: 可以注册为系统服务（systemd）
4. **配置管理**: 配置文件会被标记，升级时不会被覆盖
5. **权限管理**: 自动设置正确的文件权限和所有者
### 2.2 在 Docker 中的使用
虽然 Docker 中可以使用其他方式安装，但使用 DEB 包有以下好处：
- **一致性**: 与直接安装在 Linux 系统上的方式一致
- **便利性**: 一键安装，自动配置所有文件和权限
- **可维护性**: 便于卸载和升级
## 3. ThingsBoard DEB 包包含的内容
### 3.1 包结构
根据 `packaging/java/build.gradle` 配置，DEB 包包含以下内容：
```
/usr/share/thingsboard/ # 安装目录（pkgInstallFolder）
├── bin/ # 可执行文件
│ ├── thingsboard.jar # 主 JAR 文件（Spring Boot 打包）
│ └── install/ # 安装脚本（如果启用）
│ ├── install.sh
│ ├── upgrade.sh
│ └── logback.xml
├── conf/ # 配置文件
│ ├── thingsboard.conf # 主配置文件
│ ├── thingsboard.yml # YAML 配置
│ ├── logback.xml # 日志配置
│ └── actor-system.conf # Actor 系统配置
├── data/ # 数据文件
└── extensions/ # 扩展文件
/lib/systemd/system/ # 系统服务目录
└── thingsboard.service # systemd 服务文件
/etc/thingsboard/conf -> /usr/share/thingsboard/conf # 符号链接
```
### 3.2 关键文件说明
#### 3.2.1 JAR 文件
- **位置**: `/usr/share/thingsboard/bin/thingsboard.jar`
- **内容**: Spring Boot 打包的完整应用（包含所有依赖）
- **格式**: Fat JAR（可执行 JAR）
#### 3.2.2 配置文件
- **thingsboard.conf**: 环境变量和系统配置
- **thingsboard.yml**: 应用配置（数据库、队列等）
- **logback.xml**: 日志配置
- **actor-system.conf**: Actor 系统配置
#### 3.2.3 系统服务文件
- **thingsboard.service**: systemd 服务文件
- 允许使用 `systemctl start thingsboard` 管理服务
### 3.3 安装脚本
DEB 包包含以下安装钩子脚本：
- **preinst**: 安装前执行
- **postinst**: 安装后执行（创建用户、启动服务等）
- **prerm**: 卸载前执行
- **postrm**: 卸载后执行（清理文件等）
## 4. DEB 包的构建过程
### 4.1 构建工具
ThingsBoard 使用 **Gradle** 的 `nebula.ospackage` 插件来构建 DEB 包。
**位置**: `packaging/java/build.gradle`
### 4.2 构建步骤
```gradle
buildDeb {
arch = "all" // 架构：all 表示适用于所有架构
archiveFileName = "${pkgName}.deb" // 输出文件名
// 依赖要求：需要 Java 17
requires("openjdk-17-jre")
.or("java17-runtime")
.or("oracle-java17-installer")
.or("openjdk-17-jre-headless")
// 复制配置文件
from("${buildDir}/conf") {
include "${pkgName}.conf"
into "${pkgInstallFolder}/conf"
}
// 复制 JAR 文件
from(mainJar) {
rename { "${pkgName}.jar" }
into "bin"
}
// 安装钩子脚本
preInstall file("${buildDir}/control/deb/preinst")
postInstall file("${buildDir}/control/deb/postinst")
preUninstall file("${buildDir}/control/deb/prerm")
postUninstall file("${buildDir}/control/deb/postrm")
// 系统服务文件
from("${buildDir}/control/template.service") {
into "/lib/systemd/system"
rename { "${pkgName}.service" }
}
}
```
### 4.3 构建命令
```bash
# 在 application 模块目录下
cd application
# 执行 Gradle 构建 DEB 包
gradle buildDeb
# 生成的 DEB 包位置
# application/target/thingsboard-4.2.1.deb
```
### 4.4 Maven 集成
Maven 构建时会自动调用 Gradle 构建 DEB 包：
```xml
<!-- application/pom.xml -->
<plugin>
<groupId>org.thingsboard</groupId>
<artifactId>gradle-maven-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>invoke</goal>
</goals>
<configuration>
<tasks>
<task>buildDeb</task>
</tasks>
</configuration>
</execution>
</executions>
</plugin>
```
## 5. DEB 包在 Docker 构建中的使用
### 5.1 Dockerfile 中的安装
```dockerfile
# msa/tb-node/docker/Dockerfile
FROM thingsboard/openjdk17:bookworm-slim
# 复制 DEB 包到临时目录
COPY ${pkg.name}.deb /tmp/
# 安装 DEB 包
RUN dpkg -i /tmp/${pkg.name}.deb && \
rm /tmp/${pkg.name}.deb
# DEB 包会将应用安装到 /usr/share/thingsboard/
```
### 5.2 安装后的效果
安装 DEB 包后：
1. **文件安装**: 所有文件复制到 `/usr/share/thingsboard/`
2. **用户创建**: 创建 `thingsboard` 用户（如果不存在）
3. **权限设置**: 设置正确的文件权限
4. **服务注册**: 注册 systemd 服务（但在 Docker 中通常不使用）
## 6. DEB 包的内容示例
### 6.1 查看 DEB 包内容
```bash
# 查看 DEB 包信息
dpkg -I thingsboard-4.2.1.deb
# 查看 DEB 包文件列表
dpkg -c thingsboard-4.2.1.deb
# 解压 DEB 包（不安装）
dpkg-deb -x thingsboard-4.2.1.deb /tmp/extract
```
### 6.2 典型输出
```
package: thingsboard
version: 4.2.1-1
architecture: all
maintainer: ThingsBoard Authors
depends: openjdk-17-jre | java17-runtime | ...
description: ThingsBoard IoT Platform
```
## 7. DEB vs RPM vs JAR
### 7.1 包格式对比
| 格式 | 适用系统 | 构建工具 | ThingsBoard 支持 |
|------|---------|---------|-----------------|
| **DEB** | Debian/Ubuntu | Gradle (nebula.ospackage) | ✅ |
| **RPM** | RedHat/CentOS | Gradle (nebula.ospackage) | ✅ |
| **JAR** | 跨平台 | Maven (spring-boot-maven-plugin) | ✅ |
### 7.2 ThingsBoard 的构建
ThingsBoard 同时支持多种打包格式：
- **DEB**: 用于 Debian/Ubuntu 系统安装
- **RPM**: 用于 RedHat/CentOS 系统安装
- **JAR**: 用于 Docker 或直接运行
## 8. 为什么 Docker 中也用 DEB 包
### 8.1 原因
1. **统一构建流程**: 与 Linux 系统安装使用相同的构建产物
2. **自动化安装**: `dpkg -i` 一键安装，自动处理所有文件
3. **权限管理**: DEB 包会自动设置正确的权限和所有者
4. **配置管理**: 配置文件会被正确标记和保护
### 8.2 替代方案
理论上可以直接复制 JAR 文件，但使用 DEB 包有以下优势：
```dockerfile
# 方案1：使用 DEB 包（ThingsBoard 采用）
COPY thingsboard.deb /tmp/
RUN dpkg -i /tmp/thingsboard.deb
# 方案2：直接复制 JAR（更简单但需要手动配置）
COPY thingsboard.jar /usr/share/thingsboard/bin/
RUN mkdir -p /usr/share/thingsboard/conf && \
chown -R thingsboard:thingsboard /usr/share/thingsboard
```
DEB 包方案更标准化，减少了手动配置的工作。
## 9. 总结
### 9.1 DEB 包是什么
- **定义**: Debian/Ubuntu Linux 系统的软件包格式
- **作用**: 标准化软件安装、配置和管理
- **格式**: `.deb` 文件，包含软件文件和控制信息
### 9.2 ThingsBoard 中的 DEB 包
- **包含内容**: JAR 文件、配置文件、启动脚本、系统服务文件
- **构建工具**: Gradle (nebula.ospackage 插件)
- **构建位置**: `application/target/thingsboard-{version}.deb`
- **使用场景**:
- Linux 系统直接安装
- Docker 镜像构建（作为中间产物）
### 9.3 在 Docker 构建中的角色
```
源码编译 → JAR 打包 → DEB 打包 → Dockerfile 安装 DEB → Docker 镜像
```
DEB 包是连接 Maven/Gradle 构建和 Docker 镜像构建的桥梁，提供了标准化的安装和配置方式。
## 10. 参考资料
- [Debian Package Management](https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html)
- [Gradle OS Package Plugin](https://github.com/nebula-plugins/gradle-ospackage-plugin)
- [ThingsBoard Packaging](https://github.com/thingsboard/thingsboard/tree/master/packaging)