# 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)