firebirdsql/firebird

Firebird Docker镜像

镜像概述和主要用途

Firebird Docker镜像是用于快速部署和运行Firebird数据库服务的容器化解决方案。该镜像支持通过环境变量自定义配置，包括数据库管理员密码、普通用户、数据库名称及字符集等，同时提供数据持久化存储和初始化脚本执行功能，适用于开发、测试和生产环境中的容器化应用集成。

核心功能和特性

• 便捷配置：通过环境变量设置数据库管理员密码、普通用户、数据库名称及字符集等
• 数据持久化：默认挂载卷/var/lib/firebird/data，确保数据库数据持久存储
• 初始化支持：可执行/docker-entrypoint-initdb.d/目录下的Shell或SQL脚本初始化数据库内容
• 时区自定义：支持通过环境变量或挂载主机时区文件调整容器时区
• 配置灵活性：通过FIREBIRD_CONF_*环境变量自定义Firebird配置文件（firebird.conf）参数

使用场景和适用范围

• 开发环境中快速搭建Firebird数据库服务
• 测试环境中模拟生产数据库配置
• 生产环境中作为容器化应用的数据库服务组件
• 需要快速部署多个独立Firebird实例的场景

使用方法和配置说明

镜像默认配置

• 暴露端口：3050/tcp（Firebird默认端口）
• 数据卷：/var/lib/firebird/data（用于持久化数据库文件）

启动Firebird服务器实例

使用docker run命令直接启动：

bash
docker run \
    -e FIREBIRD_ROOT_PASSWORD= \
    -e FIREBIRD_USER=alice \
    -e FIREBIRD_PASSWORD= \
    -e FIREBIRD_DATABASE=mirror.fdb \
    -e FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8 \
    -v ./data:/var/lib/firebird/data \
    --detach docker.xuanyuan.run/firebirdsql/firebird

使用Docker Compose

创建docker-compose.yml文件：

yaml
services:
  firebird:
    image: docker.xuanyuan.run/firebirdsql/firebird
    restart: always
    environment:
      - FIREBIRD_ROOT_PASSWORD=
      - FIREBIRD_USER=alice
      - FIREBIRD_PASSWORD=
      - FIREBIRD_DATABASE=mirror.fdb
      - FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8
    volumes:
      - ./data:/var/lib/firebird/data

启动服务：docker-compose up -d

连接现有实例（使用isql）

通过isql工具连接运行中的Firebird实例：

bash
docker run -it --rm docker.xuanyuan.run/firebirdsql/firebird isql -u SYSDBA -p SERVER:/path/to/file.fdb

环境变量配置

FIREBIRD_ROOT_PASSWORD

设置Firebird数据库管理员（SYSDBA）密码。默认情况下，Firebird安装程序会生成一次性密码并存储在/opt/firebird/SYSDBA.password中。设置此变量后，SYSDBA密码将被更新，且该密码文件会被删除。

FIREBIRD_USER

在Firebird安全数据库中创建普通用户。必须同时设置FIREBIRD_PASSWORD变量，否则容器初始化将失败。

FIREBIRD_DATABASE

创建新数据库（如果数据库不存在）。数据库默认存储在/var/lib/firebird/data目录下，也支持指定绝对路径（需在该目录外）。可通过以下变量进一步配置：

• FIREBIRD_DATABASE_PAGE_SIZE：设置数据库页大小
• FIREBIRD_DATABASE_DEFAULT_CHARSET：设置数据库默认字符集（如UTF8）

FIREBIRD_USE_LEGACY_AUTH

启用传统身份验证模式（不推荐，详情参见Firebird文档）。

FIREBIRD_CONF_*

以FIREBIRD_CONF_为前缀的环境变量可用于自定义Firebird配置文件（firebird.conf）参数。例如，FIREBIRD_CONF_DataTypeCompatibility=3.0会将配置文件中的DataTypeCompatibility参数设置为3.0。注意：参数名称区分大小写，未在配置文件中定义的参数将被忽略。

*_FILE

所有上述环境变量均支持通过添加_FILE后缀从文件加载值。例如，FIREBIRD_PASSWORD_FILE=/run/secrets/firebird-passwd会从/run/secrets/firebird-passwd文件中读取FIREBIRD_PASSWORD的值。注意：原变量与_FILE变量不可同时使用，否则容器初始化将失败。

初始化数据库内容

当通过FIREBIRD_DATABASE环境变量创建新数据库时，可通过以下方式初始化数据库内容：将扩展名为.sh、.sql、.sql.gz、.sql.xz或.sql.zst的文件放入/docker-entrypoint-initdb.d/目录，容器启动时会按字母顺序执行这些文件。其中，无执行权限（+x）的.sh文件将被 sourcing（而非直接执行）。

重要：仅当数据目录（/var/lib/firebird/data）为空时，初始化脚本才会执行；若目录中已有数据库文件，脚本将被忽略。

设置容器时区

容器默认使用UTC时区，可通过以下方式修改：

方法一：设置TZ环境变量

yaml
environment:
  - TZ=America/New_York

方法二：挂载主机时区文件

yaml
volumes:
  - /etc/localtime:/etc/localtime:ro
  - /etc/timezone:/etc/timezone:ro

参考文档

• 快速入门指南
• 语言参考
• 发行说明