3. 安装与配置：Liquibase下载安装、环境变量设置、命令行基础、配置文件liquibase.properties详解

Liquibase 的安装与配置是数据库迁移工作的起点。本章将指导你完成从下载、环境搭建到命令行验证的全流程，并深入解析核心配置文件 liquibase.properties 的每个关键参数。

3.1 下载与安装

Liquibase 提供多种安装方式，推荐使用官方压缩包进行手动安装，以便精确控制版本和依赖。

3.1.1 系统要求

组件	最低版本	说明
Java 运行时环境 (JRE)	Java 8 (1.8)	Liquibase 4.x 及以上版本需 Java 11+；建议使用 Java 17 LTS
操作系统	Windows / macOS / Linux	支持 x86_64 和 ARM 架构
磁盘空间	200 MB	包含 Liquibase 核心及常用数据库驱动

3.1.2 安装步骤（以 Linux/macOS 为例）

1. 下载：从 Liquibase 官方 GitHub Releases 页面下载最新稳定版压缩包（如 liquibase-4.28.0.tar.gz）。
2. 解压：将压缩包解压到目标目录，例如 /opt/liquibase。
3. 添加执行权限：chmod +x /opt/liquibase/liquibase
4. 验证安装：运行 /opt/liquibase/liquibase --version 查看版本信息。

# 下载示例（使用 wget）
wget https://github.com/liquibase/liquibase/releases/download/v4.28.0/liquibase-4.28.0.tar.gz

# 解压到指定目录
sudo tar -xzf liquibase-4.28.0.tar.gz -C /opt/

# 验证
/opt/liquibase/liquibase --version

3.2 环境变量设置

为方便在任意目录下使用 Liquibase 命令，需要将 Liquibase 的 bin 目录添加到系统的 PATH 环境变量中。

3.2.1 Linux / macOS 配置

编辑 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc），添加以下内容：

export LIQUIBASE_HOME=/opt/liquibase
export PATH=$PATH:$LIQUIBASE_HOME

执行 source ~/.bashrc 使配置生效。

3.2.2 Windows 配置

1. 右键“此电脑” → “属性” → “高级系统设置” → “环境变量”。
2. 新建系统变量 LIQUIBASE_HOME，值为 Liquibase 解压路径（如 C:\liquibase）。
3. 在 Path 变量中添加 %LIQUIBASE_HOME%。
4. 打开新命令行窗口，输入 liquibase --version 验证。

3.3 命令行基础

Liquibase 命令行采用 liquibase <command> [options] 的格式。以下是最常用的命令：

命令	功能	典型使用场景
update	应用所有未执行的变更集	开发环境同步、CI/CD 部署
rollback	回滚到指定标签或日期	发布回退、错误恢复
status	显示待部署的变更集数量	部署前检查、审计
generateChangeLog	从现有数据库生成变更日志	数据库逆向工程、基线迁移
diff	比较两个数据库的差异	环境一致性检查、版本对比

基本用法示例：

# 使用命令行参数直接执行更新
liquibase --changeLogFile=db/changelog/db.changelog-master.xml \
          --url=jdbc:postgresql://localhost:5432/mydb \
          --username=admin \
          --password=secret \
          update

3.4 配置文件 liquibase.properties 详解

liquibase.properties 是 Liquibase 的核心配置文件，用于集中管理数据库连接、变更日志路径、驱动等参数，避免在命令行中重复输入。该文件默认放在项目根目录或当前工作目录下，也可通过 --defaultsFile 参数指定其他路径。

3.4.1 核心参数清单

参数名	是否必需	说明	示例值
changeLogFile	是	主变更日志文件的路径（相对于项目根目录）	db/changelog/db.changelog-master.xml
url	是	目标数据库的 JDBC 连接 URL	jdbc:postgresql://localhost:5432/mydb
username	是	数据库登录用户名	app_user
password	否*	数据库登录密码（建议通过环境变量或密钥管理服务注入）	${DB_PASSWORD}
driver	否	JDBC 驱动类全名（通常可自动检测）	org.postgresql.Driver
classpath	否	额外 JAR 文件或目录的路径（用于加载数据库驱动）	lib/postgresql-42.7.1.jar
liquibaseSchemaName	否	存放 Liquibase 跟踪表（DATABASECHANGELOG 等）的 schema	liquibase_admin
liquibaseTablespaceName	否	存放 Liquibase 跟踪表的表空间	lqbs_tbs
logLevel	否	日志级别：OFF, SEVERE, WARNING, INFO, FINE, FINEST	INFO
outputFile	否	将 SQL 输出写入指定文件（用于审查或手动执行）	deploy.sql

* 密码参数在配置文件中非必需，但若未提供且未通过其他方式注入，Liquibase 会提示交互输入。

3.4.2 完整配置示例

# liquibase.properties
changeLogFile=db/changelog/db.changelog-master.xml
url=jdbc:postgresql://prod-db.example.com:5432/sales_db
username=deployer
password=${LIQUIBASE_PASSWORD}
driver=org.postgresql.Driver
classpath=lib/postgresql-42.7.1.jar:lib/custom-extension.jar
liquibaseSchemaName=public
logLevel=INFO
outputFile=logs/liquibase_output.sql

3.5 安装与配置流程总览

下图展示了从下载安装到首次执行 Liquibase 命令的完整流程，以及各组件之间的依赖关系：

3.6 常见问题与排查

问题现象	可能原因	解决方案
liquibase: command not found	PATH 未正确设置或未 source 配置文件	检查 echo $PATH 是否包含 Liquibase 目录；重新打开终端或执行 source
Could not find driver	JDBC 驱动 JAR 未在 classpath 中	在 liquibase.properties 中设置 classpath 指向驱动 JAR，或将其放入 lib/ 目录
Connection refused	数据库 URL 错误、端口未开放或防火墙拦截	使用 telnet 或 nc 测试连接；检查 URL 格式和数据库运行状态
Unsupported major.minor version	Java 版本过低，不兼容当前 Liquibase 版本	升级到 Java 11 或更高版本；或使用与当前 Java 版本兼容的 Liquibase 旧版