13 KiB

Raw Permalink Blame History

docker-install-tb.sh 脚本详解

1. 脚本概述

docker-install-tb.sh 是 ThingsBoard 数据库初始化和安装脚本，用于首次部署时创建数据库 schema 和可选的演示数据。

2. 脚本功能

这个脚本主要做两件事：

启动依赖服务：启动数据库和缓存服务（PostgreSQL/Cassandra、Valkey）
执行数据库初始化：运行 tb-core1 容器执行数据库 schema 创建

3. 详细执行流程

3.1 步骤1：解析命令行参数

# 第18-32行：解析 --loadDemo 参数
while [[ $# -gt 0 ]]
do
    case $key in
        --loadDemo)
            LOAD_DEMO=true
            shift
            ;;
    esac
done

# 第34-38行：设置 loadDemo 变量
if [ "$LOAD_DEMO" == "true" ]; then
    loadDemo=true
else
    loadDemo=false
fi

作用：

解析 --loadDemo 参数
如果提供 --loadDemo，则设置 loadDemo=true，后续会加载演示数据
如果不提供，则 loadDemo=false，只创建数据库 schema

使用示例：

./docker-install-tb.sh              # 不加载演示数据
./docker-install-tb.sh --loadDemo   # 加载演示数据

3.2 步骤2：加载工具函数

# 第42行：加载 compose-utils.sh
source compose-utils.sh

作用：

加载 compose-utils.sh 中的所有工具函数
这些函数用于根据 .env 配置选择对应的 Compose 文件

3.3 步骤3：检测 Docker Compose 版本

# 第44行：检测 Docker Compose 版本（V1 或 V2）
COMPOSE_VERSION=$(composeVersion) || exit $?

作用：

检测系统中安装的是 Docker Compose V1 (docker-compose) 还是 V2 (docker compose)
后续会根据版本使用不同的命令

3.4 步骤4：选择配置组合

# 第46-54行：根据 .env 配置选择对应的 Compose 文件
ADDITIONAL_COMPOSE_QUEUE_ARGS=$(additionalComposeQueueArgs) || exit $?
ADDITIONAL_COMPOSE_ARGS=$(additionalComposeArgs) || exit $?
ADDITIONAL_CACHE_ARGS=$(additionalComposeCacheArgs) || exit $?
ADDITIONAL_COMPOSE_EDQS_ARGS=$(additionalComposeEdqsArgs) || exit $?
ADDITIONAL_STARTUP_SERVICES=$(additionalStartupServices) || exit $?

作用：

additionalComposeQueueArgs(): 根据 TB_QUEUE_TYPE 选择队列配置（kafka/confluent）
additionalComposeArgs(): 根据 DATABASE 选择数据库配置（postgres/hybrid）
additionalComposeCacheArgs(): 根据 CACHE 选择缓存配置（valkey/valkey-cluster/valkey-sentinel）
additionalComposeEdqsArgs(): 根据 EDQS_ENABLED 选择 EDQS 配置
additionalStartupServices(): 返回需要先启动的服务列表（数据库和缓存）

返回示例（假设 .env 中 DATABASE=postgres, CACHE=valkey, TB_QUEUE_TYPE=kafka）：

ADDITIONAL_COMPOSE_ARGS="-f docker-compose.postgres.yml"
ADDITIONAL_CACHE_ARGS="-f docker-compose.valkey.yml"
ADDITIONAL_COMPOSE_QUEUE_ARGS="-f docker-compose.kafka.yml"
ADDITIONAL_STARTUP_SERVICES="postgres valkey"

3.5 步骤5：启动依赖服务

# 第56-73行：如果存在需要启动的服务，先启动它们
if [ ! -z "${ADDITIONAL_STARTUP_SERVICES// }" ]; then
    COMPOSE_ARGS="\
          -f docker-compose.yml ${ADDITIONAL_CACHE_ARGS} ${ADDITIONAL_COMPOSE_ARGS} ${ADDITIONAL_COMPOSE_QUEUE_ARGS} ${ADDITIONAL_COMPOSE_EDQS_ARGS} \
          up -d ${ADDITIONUP_SERVICES}"
    
    # 执行启动命令
    docker compose $COMPOSE_ARGS
fi

作用：

检查是否有需要先启动的服务（数据库、缓存）
如果有，先启动这些服务
使用 up -d 在后台启动，只启动指定的服务

实际执行的命令示例：

docker compose \
  -f docker-compose.yml \
  -f docker-compose.valkey.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.kafka.yml \
  up -d postgres valkey

为什么先启动这些服务？

数据库和缓存必须在 ThingsBoard 初始化之前运行
ThingsBoard 安装时需要连接到数据库创建 schema
缓存服务也需要提前准备好

3.6 步骤6：执行数据库初始化

# 第75-90行：运行 tb-core1 容器执行安装
COMPOSE_ARGS="\
      -f docker-compose.yml ${ADDITIONAL_CACHE_ARGS} ${ADDITIONAL_COMPOSE_ARGS} ${ADDITIONAL_COMPOSE_QUEUE_ARGS} ${ADDITIONAL_COMPOSE_EDQS_ARGS} \
      run --no-deps --rm -e INSTALL_TB=true -e LOAD_DEMO=${loadDemo} \
      tb-core1"

docker compose $COMPOSE_ARGS

关键参数说明：

run: 运行一次性任务（不是启动服务）
--no-deps: 不启动依赖的服务（因为已经在步骤5启动了）
--rm: 容器运行完成后自动删除
-e INSTALL_TB=true: 设置环境变量，告诉启动脚本执行安装
-e LOAD_DEMO=${loadDemo}: 设置是否加载演示数据
tb-core1: 运行 tb-core1 服务容器

实际执行的命令示例：

docker compose \
  -f docker-compose.yml \
  -f docker-compose.valkey.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.kafka.yml \
  run --no-deps --rm \
  -e INSTALL_TB=true \
  -e LOAD_DEMO=false \
  tb-core1

3.7 步骤7：容器内的安装执行

当 tb-core1 容器启动时，会执行 start-tb-node.sh 脚本：

# start-tb-node.sh 中的逻辑（第36-50行）
if [ "$INSTALL_TB" == "true" ]; then
    if [ "$LOAD_DEMO" == "true" ]; then
        loadDemo=true
    else
        loadDemo=false
    fi
    
    echo "Starting ThingsBoard installation ..."
    
    exec java -cp ${jarfile} $JAVA_OPTS \
        -Dloader.main=org.thingsboard.server.ThingsboardInstallApplication \
        -Dinstall.load_demo=${loadDemo} \
        -Dinstall.upgrade=false \
        -Dlogging.config=/usr/share/thingsboard/bin/install/logback.xml \
        org.springframework.boot.loader.launch.PropertiesLauncher
fi

作用：

检测到 INSTALL_TB=true 环境变量
调用 Java 应用程序 ThingsboardInstallApplication
执行数据库 schema 创建
如果 LOAD_DEMO=true，加载演示数据

ThingsboardInstallApplication 做什么？

连接到 PostgreSQL 数据库
执行 SQL 脚本创建所有表（schema）
创建默认的租户、用户等基础数据
如果 load_demo=true，加载演示设备、规则链等数据
完成后退出

4. 完整执行流程图

用户执行: ./docker-install-tb.sh --loadDemo
    │
    ├─ 1. 解析参数 → loadDemo=true
    │
    ├─ 2. 加载工具函数 (compose-utils.sh)
    │
    ├─ 3. 检测 Docker Compose 版本
    │
    ├─ 4. 读取 .env 配置
    │   ├─ DATABASE=postgres
    │   ├─ CACHE=valkey
    │   └─ TB_QUEUE_TYPE=kafka
    │
    ├─ 5. 选择 Compose 文件
    │   ├─ docker-compose.postgres.yml
    │   ├─ docker-compose.valkey.yml
    │   └─ docker-compose.kafka.yml
    │
    ├─ 6. 启动依赖服务
    │   └─ docker compose up -d postgres valkey
    │       │
    │       ├─ 启动 PostgreSQL 容器
    │       └─ 启动 Valkey 容器
    │
    └─ 7. 执行数据库初始化
        └─ docker compose run --no-deps --rm \
            -e INSTALL_TB=true \
            -e LOAD_DEMO=true \
            tb-core1
            │
            └─ 容器内执行 start-tb-node.sh
                │
                └─ 检测到 INSTALL_TB=true
                    │
                    └─ 执行 Java 程序
                        │
                        └─ ThingsboardInstallApplication
                            │
                            ├─ 连接 PostgreSQL
                            ├─ 创建数据库表 (schema)
                            ├─ 创建默认租户和用户
                            └─ 加载演示数据 (LOAD_DEMO=true)
                                │
                                └─ 完成后容器退出并删除

5. 关键环境变量

5.1 INSTALL_TB

作用：告诉启动脚本执行安装模式

设置位置：docker-install-tb.sh 第77行

-e INSTALL_TB=true

检测位置：start-tb-node.sh 第36行

if [ "$INSTALL_TB" == "true" ]; then
    # 执行安装
fi

5.2 LOAD_DEMO

作用：控制是否加载演示数据

设置位置：docker-install-tb.sh 第77行

-e LOAD_DEMO=${loadDemo}

传递到 Java：start-tb-node.sh 第47行

-Dinstall.load_demo=${loadDemo}

6. 为什么使用 `run` 而不是 `up`？

6.1 `docker compose run` vs `docker compose up`

docker compose up:

启动服务并保持运行
服务会一直运行直到停止
用于启动长期运行的服务

docker compose run:

运行一次性任务
任务完成后容器退出
配合 --rm 可以自动清理容器
用于执行初始化、升级等一次性操作

6.2 为什么适合安装场景？

安装是一个一次性任务：

✅ 执行完数据库初始化就完成了
✅ 不需要容器一直运行
✅ 使用 run 更合适

如果使用 up：

❌ 容器会一直运行
❌ 需要手动停止和删除
❌ 不符合安装的使用场景

7. `--no-deps` 的作用

7.1 默认行为

默认情况下，docker compose run 会：

检查服务的依赖（depends_on）
自动启动依赖的服务

7.2 为什么使用 `--no-deps`？

在 docker-install-tb.sh 中：

步骤5已经手动启动了依赖服务（数据库、缓存）
步骤6不需要再次启动这些服务
使用 --no-deps 避免重复启动

好处：

✅ 避免重复启动服务
✅ 确保依赖服务已经在运行
✅ 更精确的控制启动顺序

8. 实际执行示例

8.1 不加载演示数据

$ ./docker-install-tb.sh

# 步骤1: 启动依赖服务
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.valkey.yml \
  -f docker-compose.kafka.yml \
  up -d postgres valkey

# 步骤2: 执行安装
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.valkey.yml \
  -f docker-compose.kafka.yml \
  run --no-deps --rm \
  -e INSTALL_TB=true \
  -e LOAD_DEMO=false \
  tb-core1

# 输出：
# Starting ThingsBoard installation ...
# Creating database schema...
# Creating default tenant...
# Installation completed successfully!

8.2 加载演示数据

$ ./docker-install-tb.sh --loadDemo

# 步骤相同，但 LOAD_DEMO=true

# 输出：
# Starting ThingsBoard installation ...
# Creating database schema...
# Creating default tenant...
# Loading demo data...
#   - Demo devices...
#   - Demo dashboards...
#   - Demo rule chains...
# Installation completed successfully!

9. 注意事项

9.1 首次安装前

创建日志目录：
```
./docker-create-log-folders.sh
```

配置 .env 文件：

DATABASE=postgres
CACHE=valkey
TB_QUEUE_TYPE=kafka

9.2 安装后

不要重复执行：数据库 schema 已经创建，重复执行可能会报错
检查日志：如果安装失败，查看容器日志
```
docker compose logs tb-core1
```

9.3 常见问题

问题1：数据库连接失败

原因：PostgreSQL 服务还没完全启动

解决：等待几秒后重试，或检查 PostgreSQL 日志

docker compose logs postgres

问题2：Schema 已存在错误

原因：数据库已经初始化过了

解决：如果需要重新安装，先删除数据库数据

docker compose down -v  # 删除所有数据卷
./docker-install-tb.sh  # 重新安装

10. 与其他脚本的关系

10.1 docker-create-log-folders.sh

执行顺序：在 docker-install-tb.sh 之前执行

作用：创建日志目录并设置权限

10.2 docker-start-services.sh

执行顺序：在 docker-install-tb.sh 之后执行

作用：启动所有 ThingsBoard 服务

完整流程：

# 1. 创建日志目录
./docker-create-log-folders.sh

# 2. 初始化数据库
./docker-install-tb.sh --loadDemo

# 3. 启动所有服务
./docker-start-services.sh

11. 总结

11.1 脚本的核心作用

docker-install-tb.sh 是一个数据库初始化脚本，它：

✅ 启动依赖服务：确保数据库和缓存服务运行
✅ 执行数据库初始化：创建数据库 schema 和基础数据
✅ 可选加载演示数据：方便快速体验和测试

11.2 关键设计

分离关注点：依赖服务启动和数据库初始化分开
一次性任务：使用 run 而不是 up
自动清理：使用 --rm 自动删除临时容器
灵活配置：根据 .env 选择不同的配置组合

11.3 使用场景

✅ 首次部署：创建数据库 schema
✅ 测试环境：快速搭建带演示数据的环境
✅ 开发环境：快速初始化开发数据库

注意：这个脚本只在首次安装时使用，后续启动服务使用 docker-start-services.sh！

13 KiB Raw Permalink Blame History Unescape Escape