Gel 官方 Docker 镜像部署指南从 docker run 到 Docker Compose 的生产级配置【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedb本篇指南以仓库内 docker.rst 为核心系统讲解如何用官方geldata/gel镜像在 Docker 与 Docker Compose 环境中部署 Gel 数据库涵盖基础启动、数据持久化、schema 迁移、bootstrap 初始化脚本、环境变量配置、应用连接与健康检查。读完你将掌握一套可直接复制运行的单容器与多容器编排部署方案并理解每个关键环境变量在 bootstrap 阶段与运行期分别产生的影响。何时使用geldata/gel镜像geldata/gel官方镜像主要面向必须使用 Docker 容器的场景例如生产环境中的容器化部署由 Docker Compose 或类似工具编排的、包含多个容器的开发环境。除此之外官方更推荐在宿主机上直接使用 gel-server CLI 来安装和运行 Gel 服务器——镜像本质上只是把同一套gel-server进程封装进了容器因此下面的环境变量体系与裸机部署完全一致。Gel Cloud 提示如果你打算把 Gel Cloud 实例 dump 出来再 restore 到自托管实例需要先修改 Cloud 实例中默认 admin 角色edgedb或admin的自动生成密码。dump/restore 过程中使用的角色名与密码必须在新旧实例中保持一致Gel 工具链才能正常工作。修改方式ALTER ROLE admin { set password : new_password };快速上手最简单的启动方式不带数据持久化的最小启动命令如下$ docker run --name gel -d \ -e GEL_SERVER_SECURITYinsecure_dev_mode \ geldata/gelGEL_SERVER_SECURITYinsecure_dev_mode的含义在配置一节详述。启动后可以通过官方 CLI 容器认证 Gel 实例并把凭据存入一个 Docker volume$ docker run -it --rm --linkgel \ -e GEL_SERVER_PASSWORDsecret \ -v gel-cli-config:/.config/edgedb geldata/gel-cli \ -H gel instance link my_instance \ --tls-security insecure \ --non-interactive之后随时可以打开一个交互式数据库 shell$ docker run -it --rm --linkgel \ -v gel-cli-config:/.config/edgedb geldata/gel-cli \ -I my_instance注意--link是 Docker 遗留的容器互联机制新项目建议直接使用自定义网络docker network create 服务名解析与 Compose 中的服务名访问方式保持一致。数据持久化默认情况下容器内数据是易失的。要让数据库内容在容器重启后仍然存活必须把持久化 volume 挂载到GEL_SERVER_DATADIR指定的路径默认是/var/lib/gel/data$ docker run \ --name gel \ -e GEL_SERVER_PASSWORDsecret \ -e GEL_SERVER_TLS_CERT_MODEgenerate_self_signed \ -v /my/data/directory:/var/lib/gel/data \ -d geldata/gelWindows 平台必须改用 Docker volume而非 bind mount$ docker volume create --namegel-data $ docker run \ --name gel \ -e GEL_SERVER_PASSWORDsecret \ -e GEL_SERVER_TLS_CERT_MODEgenerate_self_signed \ -v gel-data:/var/lib/gel/data \ -d geldata/gel使用远程 PostgreSQL 后端如果不想使用镜像内置的 PostgreSQL可以设置GEL_SERVER_BACKEND_DSN指向一个远程 PostgreSQL 集群URI 格式连接串此时 Gel 将不再维护本地数据目录。该变量与GEL_SERVER_DATADIR互斥详见环境变量参考。适合复用已有 PG 基础设施、与现有 PostgreSQL 运维体系打通的场景。Schema 迁移派生镜像可以把应用 schema 与迁移文件放进/dbschema。容器启动时默认会尝试应用/dbschema/migrations下的迁移除非通过环境变量GEL_DOCKER_APPLY_MIGRATIONSnever显式关闭。迁移相关的完整取值来自 configuration.rst变量取值说明GEL_DOCKER_APPLY_MIGRATIONSalways默认/never是否在容器启动时自动应用/dbschema/migrations中的迁移Docker Compose 部署一个最小的docker-compose.yaml如下services: gel: image: geldata/gel environment: GEL_SERVER_SECURITY: insecure_dev_mode volumes: - ./dbschema:/dbschema ports: - 5656:5656其中./dbschema:/dbschema把宿主机上的 schema 目录挂入容器ports将容器内默认端口 5656 映射到宿主机。当dbschema/中已有 schema 定义后可以在宿主机上用 Gel CLI 创建迁移$ gel --tls-securityinsecure -P 5656 migration create如果宿主机没有安装 Gel CLI可以直接使用服务器容器自带的 CLI$ docker compose exec gel \ gel --tls-securityinsecure -P 5656 migration create生产环境建议为gel服务显式设置GEL_SERVER_PASSWORD或GEL_SERVER_PASSWORD_HASH并挂载持久化 volume而不是依赖insecure_dev_mode。配置 ConfigurationDocker 镜像支持与 Gel 服务器进程完全相同的环境变量集完整清单见环境变量参考。此外Gel 容器还支持初始化脚本和一些 Docker 专属变量。版本前缀Gel 6.0 之前的 EdgeDB 版本所有环境变量的前缀是EDGEDB_而不是GEL_。_FILE与_ENV变体部分变量支持_FILE和_ENV变体以支持更高级的配置——_FILE变体的值是文件名文件内容会被读出并作为最终值_ENV变体的值是另一个环境变量的名字该变量的值会被用作最终值。这在敏感信息由外部编排系统注入固定环境变量的部署场景中非常方便详见变体说明。初始化配置仅 bootstrap 阶段生效当容器首次在指定数据目录或远程 PG 集群上启动时会执行初始实例设置这一阶段称为bootstrap 阶段。以下环境变量只影响 bootstrap对后续容器运行没有影响。GEL_SERVER_BOOTSTRAP_COMMAND用于精细调整初始用户与分支创建等初始化逻辑。如果该变量与GEL_SERVER_BOOTSTRAP_SCRIPT_FILE都未指定容器会检查/gel-bootstrap.edgeql是否存在可放在派生镜像中。它直接映射到gel-server的--bootstrap-command参数支持_FILE与_ENV变体。GEL_SERVER_BOOTSTRAP_SCRIPT_FILE⚠️ 在镜像版本 2.8 中已废弃改用GEL_SERVER_BOOTSTRAP_COMMAND_FILE。在初始化数据库时运行脚本脚本由默认用户、在默认分支中执行。GEL_SERVER_PASSWORD将默认超级用户账户的密码设为该值。未提供时不设置密码除非通过GEL_SERVER_BOOTSTRAP_COMMAND设置。注意一旦设置了GEL_SERVER_BOOTSTRAP_COMMAND本变量会被忽略。支持_FILE与_ENV变体。GEL_SERVER_PASSWORD_HASHGEL_SERVER_PASSWORD的变体值为密码验证器的哈希而不是明文。同样设置了GEL_SERVER_BOOTSTRAP_COMMAND时本变量会被忽略。支持_FILE与_ENV变体。GEL_SERVER_GENERATE_SELF_SIGNED_CERT⚠️ 已废弃请改用GEL_SERVER_TLS_CERT_MODEgenerate_self_signed。设为1时服务器会在GEL_SERVER_DATADIR中自动生成自签名证书和密钥文件并在日志中输出证书内容如果证书文件已存在则直接复用。自签名证书通常只用于开发与测试生产环境应使用下面的方式提供自己的证书。GEL_SERVER_TLS_CERT/GEL_SERVER_TLS_KEY直接提供 TLS 证书和私钥数据与GEL_SERVER_TLS_CERT_MODEgenerate_self_signed互斥。支持_FILE与_ENV变体生产环境推荐以GEL_SERVER_TLS_CERT_FILE/GEL_SERVER_TLS_KEY_FILE挂载证书文件。/docker-entrypoint.d/自定义脚本派生镜像可以在/docker-entrypoint.d/中放入一个或多个可执行文件容器 entrypoint 会在任何其他处理之前执行它们适合做镜像级别的预置操作。运行期配置GEL_DOCKER_LOG_LEVEL控制 entrypoint 脚本的日志详细程度。合法值trace、debug、info、warning、error默认info。/gel-bootstrap.d/与/gel-bootstrap-late.d/自定义脚本派生镜像可以在以下两个目录放入一个或多个*.edgeql或*.sh脚本它们会在上述环境变量或/gel-bootstrap.edgeql指定的初始化之后额外执行/gel-bootstrap.d/中的脚本在应用任何 schema 迁移之前执行/gel-bootstrap-late.d/中的脚本在schema 迁移应用之后执行。这是官方文档推荐的、在 bootstrap 阶段既要创建分支、又要执行其他 EdgeQL 语句的标准解法由于GEL_SERVER_BOOTSTRAP_COMMAND的所有语句运行在同一个 block 中而 create branch 语句create empty branch、create schema branch、create data branch不能与任何其他语句放在同一个 block 里因此把create branch单独写在一个.edgeql文件、其余语句写在另一个文件中分别放入/gel-bootstrap.d/即可实现分支创建与其他初始化并存参考 configuration.rst。脚本命名最佳实践当有多个脚本需要按顺序执行时建议用01-、02-等数字前缀命名明确执行顺序。注意EdgeDB 5.0 之前的版本路径中为edgedb而非gel即/gel-bootstrap.d/对应/edgedb-bootstrap.d/。其他 Docker 镜像专属变量除上述变量外configuration.rst 的 Docker 镜像专属变量一节还列出以下仅对 Docker 镜像生效的变量在镜像之外设置无效变量默认值说明GEL_DOCKER_ABORT_CODE1进程失败时参数会被记录到 stderr 并以该退出码终止脚本GEL_DOCKER_BOOTSTRAP_TIMEOUT_SEC300等待实例 bootstrap 完成的超时秒数GEL_DOCKER_SHOW_GENERATED_CERTalways是否在控制台输出生成的 TLS 证书可选neverGEL_SERVER_BOOTSTRAP_COMMAND_FILE—初始化数据库时运行的脚本脚本由默认用户在默认分支中执行可与GEL_SERVER_BOOTSTRAP_ONLY搭配GEL_SERVER_BINARYgel-server指定要运行的 Gel 服务器二进制GEL_SERVER_UID1运行服务器二进制的用户 IDGEL_SERVER_EXTRA_ARGS—启动 Gel 服务器时附加的额外参数从仓库源码布局看这些环境变量在服务器侧的解析与gel-server命令行参数集中在 edb/server/args.pybootstrap 阶段的具体实现位于 edb/server/bootstrap.py读者可进一步阅读这两个文件了解变量到启动行为的完整映射。连接你的应用Gel 客户端库可以通过DSN连接串或独立环境变量两种方式配置连接参数。获取连接参数一次连接需要以下要素Host容器主机名或 IP。Docker Compose 中即服务名如gel独立容器在宿主机上可用localhost跨主机则用容器的 IP/主机名Port5656Gel 默认端口除非用-p重新映射Usernameadmin默认超级用户Password启动容器时通过GEL_SERVER_PASSWORD设置的值Branchmain默认分支。据此构造 DSN$ GEL_DSNgel://admin:passwordhostname:5656Compose 中服务名为gel时$ GEL_DSNgel://admin:secretgel:5656获取 TLS 证书如果以GEL_SERVER_TLS_CERT_MODEgenerate_self_signed配置应用需要拿到证书才能安全连接。三种获取方式从运行中的容器直接读取证书默认存于数据目录的edbtlscert.pem$ docker exec container-name cat /var/lib/gel/data/edbtlscert.pem或使用镜像内置的工具脚本$ docker exec container-name \ gel-show-secrets.sh --formatraw GEL_SERVER_TLS_CERT或通过 Gel CLI 查询$ gel --dsn $GEL_DSN --tls-security insecure \ query SELECT sys::get_tls_certificate()如果挂载了GEL_SERVER_DATADIR持久化 volume证书同样可以在volume-path/edbtlscert.pem找到。在应用容器中使用在应用容器中设置如下环境变量# docker-compose.yaml 示例 services: app: image: your-app environment: GEL_DSN: gel://admin:secretgel:5656 # 自签名证书场景 GEL_CLIENT_TLS_SECURITY: insecure # 或者提供 CA 证书内容 # GEL_TLS_CA: certificate content生产环境建议提供 TLS 证书而非关闭校验services: app: image: your-app environment: GEL_DSN: gel://admin:${GEL_PASSWORD}gel:5656 GEL_TLS_CA_FILE: /certs/gel-ca.pem volumes: - ./certs:/certs:roGel 客户端库会自动读取这些环境变量应用代码无需额外改动。本地开发用 CLI 关联容器为了在本地开发时更方便地操作容器实例可以用gel instance link创建别名。注意instance与project命令组不应用于管理生产实例。在宿主机上关联容器$ gel instance link \ --dsn gel://admin:secretlocalhost:5656 \ --non-interactive \ --trust-tls-cert \ my_docker_instance之后就可以用别名my_docker_instance代替实例名$ gel -I my_docker_instance Gel x.x Type \help for help, \quit to quit. gel或执行迁移$ gel -I my_docker_instance migrate健康检查Gel 通过 HTTP 端点暴露存活与就绪状态可以用任意 HTTP 客户端做健康检查完整细节见健康检查指南。存活检查AlivenessGET http://hostname:port/server/status/alive实例存活时返回200与OK否则返回50x或网络错误就绪检查ReadinessGET http://hostname:port/server/status/ready实例就绪可接收查询时返回200与OK否则返回50x或网络错误。在 Docker Compose 中可以直接把它们配进服务的healthcheck指令例如用curl或 wget 探测/server/status/ready让编排系统自动感知容器健康状态。小结Gel 官方镜像的部署核心可以概括为三条主线持久化挂载保证数据存活、环境变量体系驱动 bootstrap 与运行期行为、DSN TLS 证书打通应用连接。无论单容器还是 Compose 编排先以insecure_dev_mode快速验证连通性再逐步切换到密码认证、自签/自有证书与自动迁移即可平滑过渡到生产配置。完整的环境变量字典与服务器侧实现可继续阅读 环境变量参考 与 服务器启动参数解析。【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
