477 lines
13 KiB
Markdown
477 lines
13 KiB
Markdown
# docker-install-tb.sh 脚本详解
|
||
|
||
## 1. 脚本概述
|
||
|
||
`docker-install-tb.sh` 是 ThingsBoard **数据库初始化和安装脚本**，用于首次部署时创建数据库 schema 和可选的演示数据。
|
||
|
||
## 2. 脚本功能
|
||
|
||
这个脚本主要做两件事：
|
||
|
||
1. **启动依赖服务**：启动数据库和缓存服务（PostgreSQL/Cassandra、Valkey）
|
||
2. **执行数据库初始化**：运行 `tb-core1` 容器执行数据库 schema 创建
|
||
|
||
## 3. 详细执行流程
|
||
|
||
### 3.1 步骤1：解析命令行参数
|
||
|
||
```bash
|
||
# 第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
|
||
|
||
**使用示例**：
|
||
```bash
|
||
./docker-install-tb.sh # 不加载演示数据
|
||
./docker-install-tb.sh --loadDemo # 加载演示数据
|
||
```
|
||
|
||
### 3.2 步骤2：加载工具函数
|
||
|
||
```bash
|
||
# 第42行：加载 compose-utils.sh
|
||
source compose-utils.sh
|
||
```
|
||
|
||
**作用**：
|
||
- 加载 `compose-utils.sh` 中的所有工具函数
|
||
- 这些函数用于根据 `.env` 配置选择对应的 Compose 文件
|
||
|
||
### 3.3 步骤3：检测 Docker Compose 版本
|
||
|
||
```bash
|
||
# 第44行：检测 Docker Compose 版本（V1 或 V2）
|
||
COMPOSE_VERSION=$(composeVersion) || exit $?
|
||
```
|
||
|
||
**作用**：
|
||
- 检测系统中安装的是 Docker Compose V1 (`docker-compose`) 还是 V2 (`docker compose`)
|
||
- 后续会根据版本使用不同的命令
|
||
|
||
### 3.4 步骤4：选择配置组合
|
||
|
||
```bash
|
||
# 第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`）：
|
||
```bash
|
||
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：启动依赖服务
|
||
|
||
```bash
|
||
# 第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` 在后台启动，只启动指定的服务
|
||
|
||
**实际执行的命令示例**：
|
||
```bash
|
||
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：执行数据库初始化
|
||
|
||
```bash
|
||
# 第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
|
||
```
|
||
|
||
**关键参数说明**：
|
||
|
||
1. **`run`**: 运行一次性任务（不是启动服务）
|
||
2. **`--no-deps`**: 不启动依赖的服务（因为已经在步骤5启动了）
|
||
3. **`--rm`**: 容器运行完成后自动删除
|
||
4. **`-e INSTALL_TB=true`**: 设置环境变量，告诉启动脚本执行安装
|
||
5. **`-e LOAD_DEMO=${loadDemo}`**: 设置是否加载演示数据
|
||
6. **`tb-core1`**: 运行 tb-core1 服务容器
|
||
|
||
**实际执行的命令示例**：
|
||
```bash
|
||
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` 脚本：
|
||
|
||
```bash
|
||
# 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 做什么？**
|
||
1. 连接到 PostgreSQL 数据库
|
||
2. 执行 SQL 脚本创建所有表（schema）
|
||
3. 创建默认的租户、用户等基础数据
|
||
4. 如果 `load_demo=true`，加载演示设备、规则链等数据
|
||
5. 完成后退出
|
||
|
||
## 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行
|
||
```bash
|
||
-e INSTALL_TB=true
|
||
```
|
||
|
||
**检测位置**：`start-tb-node.sh` 第36行
|
||
```bash
|
||
if [ "$INSTALL_TB" == "true" ]; then
|
||
# 执行安装
|
||
fi
|
||
```
|
||
|
||
### 5.2 LOAD_DEMO
|
||
|
||
**作用**：控制是否加载演示数据
|
||
|
||
**设置位置**：`docker-install-tb.sh` 第77行
|
||
```bash
|
||
-e LOAD_DEMO=${loadDemo}
|
||
```
|
||
|
||
**传递到 Java**：`start-tb-node.sh` 第47行
|
||
```bash
|
||
-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` 会：
|
||
1. 检查服务的依赖（`depends_on`）
|
||
2. 自动启动依赖的服务
|
||
|
||
### 7.2 为什么使用 `--no-deps`？
|
||
|
||
在 `docker-install-tb.sh` 中：
|
||
1. **步骤5**已经手动启动了依赖服务（数据库、缓存）
|
||
2. **步骤6**不需要再次启动这些服务
|
||
3. 使用 `--no-deps` 避免重复启动
|
||
|
||
**好处**：
|
||
- ✅ 避免重复启动服务
|
||
- ✅ 确保依赖服务已经在运行
|
||
- ✅ 更精确的控制启动顺序
|
||
|
||
## 8. 实际执行示例
|
||
|
||
### 8.1 不加载演示数据
|
||
|
||
```bash
|
||
$ ./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 加载演示数据
|
||
|
||
```bash
|
||
$ ./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 首次安装前
|
||
|
||
1. **创建日志目录**：
|
||
```bash
|
||
./docker-create-log-folders.sh
|
||
```
|
||
|
||
2. **配置 .env 文件**：
|
||
```bash
|
||
DATABASE=postgres
|
||
CACHE=valkey
|
||
TB_QUEUE_TYPE=kafka
|
||
```
|
||
|
||
### 9.2 安装后
|
||
|
||
1. **不要重复执行**：数据库 schema 已经创建，重复执行可能会报错
|
||
2. **检查日志**：如果安装失败，查看容器日志
|
||
```bash
|
||
docker compose logs tb-core1
|
||
```
|
||
|
||
### 9.3 常见问题
|
||
|
||
**问题1：数据库连接失败**
|
||
|
||
**原因**：PostgreSQL 服务还没完全启动
|
||
|
||
**解决**：等待几秒后重试，或检查 PostgreSQL 日志
|
||
```bash
|
||
docker compose logs postgres
|
||
```
|
||
|
||
**问题2：Schema 已存在错误**
|
||
|
||
**原因**：数据库已经初始化过了
|
||
|
||
**解决**：如果需要重新安装，先删除数据库数据
|
||
```bash
|
||
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 服务
|
||
|
||
**完整流程**：
|
||
```bash
|
||
# 1. 创建日志目录
|
||
./docker-create-log-folders.sh
|
||
|
||
# 2. 初始化数据库
|
||
./docker-install-tb.sh --loadDemo
|
||
|
||
# 3. 启动所有服务
|
||
./docker-start-services.sh
|
||
```
|
||
|
||
## 11. 总结
|
||
|
||
### 11.1 脚本的核心作用
|
||
|
||
`docker-install-tb.sh` 是一个**数据库初始化脚本**，它：
|
||
|
||
1. ✅ **启动依赖服务**：确保数据库和缓存服务运行
|
||
2. ✅ **执行数据库初始化**：创建数据库 schema 和基础数据
|
||
3. ✅ **可选加载演示数据**：方便快速体验和测试
|
||
|
||
### 11.2 关键设计
|
||
|
||
- **分离关注点**：依赖服务启动和数据库初始化分开
|
||
- **一次性任务**：使用 `run` 而不是 `up`
|
||
- **自动清理**：使用 `--rm` 自动删除临时容器
|
||
- **灵活配置**：根据 `.env` 选择不同的配置组合
|
||
|
||
### 11.3 使用场景
|
||
|
||
- ✅ **首次部署**：创建数据库 schema
|
||
- ✅ **测试环境**：快速搭建带演示数据的环境
|
||
- ✅ **开发环境**：快速初始化开发数据库
|
||
|
||
**注意**：这个脚本**只在首次安装时使用**，后续启动服务使用 `docker-start-services.sh`！
|
||
|