316 lines
8.7 KiB
Markdown
316 lines
8.7 KiB
Markdown
# 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)
|
||
|