企业官网建设流程全解析

• 后端
• 数据可视化
• 数据库
• 数据分析

导读

本文围绕 SQLPad 官方仓库中的 docker-examples/README.md 展开，系统讲解如何通过 Docker 快速拉起一个可用的 SQLPad 实例，并串联仓库中 postgres-docker-compose、mariadb、mssql-docker-compose、extending-image 等现成示例，说明数据持久化、环境变量配置、种子数据注入与镜像扩展等实战要点。读完本文，你将能独立完成 SQLPad 的最小化启动、生产级数据卷挂载、多数据库编排，以及通过环境变量预置连接、预置查询等常见落地操作。

一、Docker 示例目录概览与定位

仓库根目录下的docker-examples/目录并不是一个需要整体构建的项目，而是若干彼此独立的可运行示例，每个子目录针对一种典型使用场景：

从根目录 Dockerfile 可以看到，官方镜像sqlpad/sqlpad是一个多阶段构建产物：先用node:20-slim构建前端并安装依赖，再把server/目录连同构建好的前端一起拷入干净的运行阶段，入口为/docker-entrypoint，默认EXPOSE 3000、SQLPAD_DB_PATH=/var/lib/sqlpad。

二、最关键的前提：Docker 数据持久化

原文档在正文开头就专门强调了一条容易被忽略的注意事项：

Unless data volumes are mapped outside the containers, you will lose data inside SQLPad and various database when the containers are shutdown and removed. （除非把数据卷映射到容器外部，否则容器被关闭并移除后，SQLPad 和数据库内部的数据都会丢失。）

SQLPad 自身默认把数据（SQLite 库、查询结果缓存、会话文件）写在/var/lib/sqlpad（见 Dockerfile 的ENV SQLPAD_DB_PATH /var/lib/sqlpad）。如果只是docker run而不挂卷，容器一旦docker rm，这些数据就全部消失；数据库容器同理，Postgres/MariaDB 的数据目录都在容器内层。

因此，凡是准备投入实际使用的部署，都必须显式声明卷映射。官方推荐把数据放到宿主机的共享目录，例如~/docker-volumes（Docker Desktop 等环境需将该目录共享给 Docker 才能生效）。

三、最小化启动：docker run 命令详解

官方文档给出了两种命令行启动方式，第一种是最精简的“零配置快速体验”：

# 最精简示例，将宿主机 3000 端口映射到容器内 3000 端口 docker run -p 3000:3000 \ -e "SQLPAD_ADMIN=admin@sqlpad.com" \ -e "SQLPAD_ADMIN_PASSWORD=admin" \ sqlpad/sqlpad:latest

• -p 3000:3000：把容器内 SQLPad 的 HTTP 端口映射到宿主机；
• -e SQLPAD_ADMIN：初始管理员账号邮箱；
• -e SQLPAD_ADMIN_PASSWORD：初始管理员密码。

启动后打开浏览器访问http://localhost:3000即可进入登录页。

第二种是挂载数据卷 + 环境变量 + 后台运行的正式用法：

# 目录 ~/docker-volumes 必须与 docker 共享才能生效 docker run --name sqlpad \ -p 127.0.0.1:3000:3000 \ -e "SQLPAD_ADMIN=admin@sqlpad.com" \ -e "SQLPAD_ADMIN_PASSWORD=admin" \ --volume ~/docker-volumes/sqlpad-postgres:/var/lib/sqlpad \ --detach \ sqlpad/sqlpad:latest

几个要点：

• --name sqlpad：给容器命名，便于后续用名字而非容器 ID 操作；
• -p 127.0.0.1:3000:3000：只绑定回环地址，避免暴露到局域网/公网；
• --volume ~/docker-volumes/sqlpad-postgres:/var/lib/sqlpad：宿主机目录映射到容器内 SQLPad 数据目录，这是数据不丢的关键；
• --detach：后台运行，终端不被占用。

日常管理命令（原文档原文）：

# 列出正在运行的容器（找到名字或容器 ID） docker ps # 按名字停止容器（否则用 docker ps 得到的容器 ID） docker stop sqlpad

四、docker-compose 多服务编排：Postgres + SQLPad 示例

仓库中 postgres-docker-compose 是最完整的入门示例，也是官方文档推荐的“下一个台阶”。使用前请确保宿主机已安装 Docker 与 docker-compose。

4.1 启动步骤（原文档原文）

在包含docker-compose.yml的目录（即docker-examples/postgres-docker-compose/）中执行：

# 拉取/下载 compose 文件里声明的镜像 docker-compose pull # 如果使用 `build` 而不是 `image`，则改为构建 SQLPad 镜像 docker-compose build # 启动 sqlpad 与 postgres docker-compose up

容器全部就绪后，SQLPad 映射在本地 3000 端口，浏览器访问http://localhost:3000。

4.2 compose 文件逐段拆解

services: postgres: image: postgres restart: always environment: POSTGRES_USER: sqlpad POSTGRES_PASSWORD: sqlpad volumes: - ./docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d sqlpad: # 要使用本仓库根目录的 Dockerfile，可把 image 换成 build # build: ../../ image: sqlpad/sqlpad:5 hostname: 'sqlpad' ports: - '3000:3000' environment: SQLPAD_ADMIN: 'admin@sqlpad.com' SQLPAD_ADMIN_PASSWORD: 'admin' SQLPAD_APP_LOG_LEVEL: debug SQLPAD_WEB_LOG_LEVEL: warn SQLPAD_SEED_DATA_PATH: /etc/sqlpad/seed-data SQLPAD_CONNECTIONS__pgdemo__name: Postgres demo SQLPAD_CONNECTIONS__pgdemo__driver: postgres SQLPAD_CONNECTIONS__pgdemo__host: postgres SQLPAD_CONNECTIONS__pgdemo__database: sqlpad SQLPAD_CONNECTIONS__pgdemo__username: sqlpad SQLPAD_CONNECTIONS__pgdemo__password: sqlpad SQLPAD_CONNECTIONS__pgdemo__multiStatementTransactionEnabled: 'true' SQLPAD_CONNECTIONS__pgdemo__idleTimeoutSeconds: 86400 volumes: - ./seed-data:/etc/sqlpad/seed-data

要点说明：

• Postgres 初始化：./docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d挂载的 pgdata.sh 会在数据库首次初始化时自动执行，创建test表并插入两行数据：

  psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL CREATE TABLE test (id int, name text); INSERT INTO test (id, name) VALUES (1, 'one'), (2, 'two'); EOSQL

• image: sqlpad/sqlpad:5vsbuild: ../../：默认从 Docker Hub 拉取官方镜像；注释掉的build: ../../表示若想用本仓库根目录 Dockerfile 从源码构建镜像，就改成build并指向仓库根（../..即sqlpad/仓库根，相对于docker-examples/postgres-docker-compose/所在层级）。两种方式二选一，不可同时生效。

• 连接预置：SQLPAD_CONNECTIONS__pgdemo__*系列变量通过环境变量直接预置了一个名为Postgres demo、ID 为pgdemo的连接，host指向 compose 网络中的postgres服务名（compose 会自动做 DNS 解析）。

• 种子数据：SQLPAD_SEED_DATA_PATH=/etc/sqlpad/seed-data配合./seed-data:/etc/sqlpad/seed-data卷挂载，把宿主机上的 seed-data 目录注入容器，SQLPad 启动时自动导入其中的查询种子数据（详见第六节）。

4.3 环境变量预置连接的解析原理

SQLPAD_CONNECTIONS__<connectionId>__<field>是 SQLPad 官方支持的环境变量式连接配置。从源码看，其解析实现在 server/lib/config/config-utils.js：

// 连接环境变量遵循格式： // SQLPAD_CONNECTIONS__<connectionId>__<connectionFieldName> // 例如：SQLPAD_CONNECTIONS__ab123__sqlserverEncrypt="" const [prefix, id, field] = envVar.split('__'); connectionsMap[id][field] = env[envVar];

即变量名以__分隔为三段：前缀SQLPAD_CONNECTIONS、连接 ID、字段名。ID 就是该连接在 SQLPad 内的唯一标识（上例中的pgdemo），字段名则对应具体驱动的连接字段。

配置加载器 server/lib/config/index.js 会对这些变量做严格校验：

• 缺少name报错：Environment config SQLPAD_CONNECTIONS__${id}__name missing；
• 缺少driver报错：Environment config SQLPAD_CONNECTIONS__${id}__driver missing；
• driver不在已注册驱动列表时报错："foo" not a supported driver；
• 字段不属于该驱动定义时报错："wrongField" not a known field for postgres。

这些校验逻辑在 server/test/lib/config.js 中都有对应的测试用例覆盖。因此用环境变量配连接时，务必保证name、driver齐全，且字段名严格对应目标驱动（postgres 驱动可用字段见 server/drivers/postgres/index.js：host、port、database、username、password、postgresSsl、postgresSslSelfSigned、postgresCert、postgresKey、postgresCA、useSocks、socksHost、socksPort、socksUsername、socksPassword、preQueryStatements、queryTimeout、maxrows_override）。

提示：multiStatementTransactionEnabled、idleTimeoutSeconds等字段不属于驱动特有字段，而是连接通用字段，配置校验时会被单独解构出来（见 server/lib/config/index.js），因此可直接在环境变量中声明。

五、把数据库作为 SQLPad 后端存储：MariaDB 示例

mariadb 示例展示了一个更进阶的玩法：除了用 MariaDB 作为查询目标，还让它承担 SQLPad 自身的元数据存储（替代默认的 SQLite）。这在生产环境中很常见，因为数据库比文件更适合多实例、备份与恢复。

services: mariadb: image: mariadb:10.5.5 restart: always environment: MYSQL_USER: user MYSQL_PASSWORD: password MYSQL_DATABASE: db MYSQL_ROOT_PASSWORD: password sqlpad: image: sqlpad/sqlpad:5.6.0 hostname: 'sqlpad' depends_on: - 'mariadb' ports: - '3000:3000' environment: SQLPAD_ADMIN: 'admin@sqlpad.com' SQLPAD_ADMIN_PASSWORD: 'admin' SQLPAD_APP_LOG_LEVEL: debug SQLPAD_WEB_LOG_LEVEL: warn SQLPAD_SEED_DATA_PATH: /etc/sqlpad/seed-data # 关键：用外部数据库代替本地 SQLite 作为 SQLPad 的后端数据库 SQLPAD_BACKEND_DB_URI: mariadb://root:password@mariadb:3306/db?timezone=Etc%2FGMT0 SQLPAD_SESSION_STORE: 'database' SQLPAD_DB_PATH: '/var/lib/sqlpad' SQLPAD_DB_IN_MEMORY: 'false' SQLPAD_QUERY_RESULT_STORE: 'database' # 预置一个连接指向 SQLPad 自身的后端数据库 SQLPAD_CONNECTIONS__mariad__name: 'MariaDB Demo' SQLPAD_CONNECTIONS__mariad__driver: mysql SQLPAD_CONNECTIONS__mariad__host: mariadb SQLPAD_CONNECTIONS__mariad__port: 3306 SQLPAD_CONNECTIONS__mariad__database: db SQLPAD_CONNECTIONS__mariad__username: root SQLPAD_CONNECTIONS__mariad__password: password volumes: - ./seed-data:/etc/sqlpad/seed-data

各组环境变量含义如下：

官方文档（configuration.md）对后端数据库的说明是：只设置SQLPAD_DB_PATH时使用本地 SQLite；设置SQLPAD_BACKEND_DB_URI后改用外部数据库，并支持在连接串里追加选项（如?ssl=true）。被注释掉的两行multiStatementTransactionEnabled、idleTimeoutSeconds是可选调优项，按需取消注释即可。

六、种子数据（Seed Data）注入机制

两个数据库示例都通过SQLPAD_SEED_DATA_PATH+ 卷挂载注入了 seed-data 目录。种子数据是 SQLPad 官方文档标注为EXPERIMENTAL（实验性）的功能：服务启动时加载，按匹配属性创建或更新数据；如果之后从种子目录删除某个条目，已导入 SQLPad 的数据不会被删除。该机制适合预置“系统级”数据（如内置用户、共享查询），不适合被终端用户频繁修改的内容。

种子目录结构约定如下（参考 docs/src/pages/en/seed-data.md）：

/path/to/seed-data /connections connection-1.json /queries some-query.json another-query.json

以 query-1.json 为例：

{ "id": "seed-query-1", "name": "Seed query 1", "connectionId": "pgdemo", "queryText": "SELECT * FROM some_table", "createdBy": "admin@sqlpad.com", "acl": [ { "groupId": "__EVERYONE__", "write": false } ] }

字段说明：

• id：查询唯一标识，种子加载时按 id 匹配“创建或更新”；
• connectionId：指向已存在的连接（此处是pgdemo，由环境变量预置的连接 ID）；
• queryText：查询 SQL 文本；
• createdBy：可以是用户邮箱或用户 id；若 SQLPad 中不存在对应用户，会自动创建一个禁用状态的用户记录用于引用；
• acl：访问控制列表。__EVERYONE__是特殊组，表示对全体用户可见；write: false表示只读（可执行），write: true允许保存修改。

另一个示例 query-2.json 特意演示了createdBy引用一个不存在的用户（not-real-user@sqlpad.com），并注释说明这是“由不存在用户分享的查询”——加载时 SQLPad 会按 server/lib/load-seed-data.js 的逻辑自动补齐一个禁用用户。该文件的加载逻辑（创建/更新、ACL 中userId/userEmail/groupId三者只允许其一，超出会抛错）都可在 server/lib/load-seed-data.js 中看到源码级验证。

七、SQL Server 示例与具名卷

mssql-docker-compose 演示 SQL Server 2017 Linux 版的编排：

services: mssql: image: 'microsoft/mssql-server-linux:2017-latest' hostname: 'mssql' ports: - 1433:1433 environment: - ACCEPT_EULA=Y - MSSQL_SA_PASSWORD=SuperP4ssw0rd! - MSSQL_PID=Express sqlpad: image: sqlpad/sqlpad:5 hostname: 'sqlpad' ports: - '3000:3000' environment: SQLPAD_ADMIN: 'admin@sqlpad.com' SQLPAD_ADMIN_PASSWORD: 'admin' SQLPAD_APP_LOG_LEVEL: info SQLPAD_WEB_LOG_LEVEL: warn SQLPAD_CONNECTIONS__sqlserverdemo__name: SQL Server Demo SQLPAD_CONNECTIONS__sqlserverdemo__driver: sqlserver SQLPAD_CONNECTIONS__sqlserverdemo__host: mssql SQLPAD_CONNECTIONS__sqlserverdemo__database: master SQLPAD_CONNECTIONS__sqlserverdemo__username: sa SQLPAD_CONNECTIONS__sqlserverdemo__password: SuperP4ssw0rd! volumes: - sqlpad-volume:/var/lib/sqlpad volumes: sqlpad-volume:

与前面示例不同的是，这里使用 compose具名卷sqlpad-volume来持久化 SQLPad 数据目录/var/lib/sqlpad，而不需要指定宿主机路径——具名卷由 Docker 托管，跨容器生命周期保留数据，是比~/docker-volumes更省心的一种选择。SQL Server 侧需要ACCEPT_EULA=Y接受许可协议、MSSQL_SA_PASSWORD设置 sa 密码（示例密码SuperP4ssw0rd!仅用于演示，生产环境务必更换强密码）。

八、镜像扩展：固化配置与 ODBC/Oracle 驱动

8.1 基于官方镜像二次扩展

extending-image/Dockerfile 展示最轻量的扩展方式——直接继承官方镜像并用ENV固化管理员账号：

FROM sqlpad/sqlpad:5.6.0 ENV SQLPAD_ADMIN "admin" ENV SQLPAD_ADMIN_PASSWORD "admin" ENV SQLPAD_PORT 3000

这样构建出的镜像自带默认管理员，省去每次部署重复传环境变量。所有 SQLPad 配置项都可通过环境变量注入，完整参数表可查阅 docs/src/pages/en/configuration.md（含SQLPAD_PORT、SQLPAD_DB_PATH、SQLPAD_SESSION_STORE、SQLPAD_QUERY_RESULT_STORE、SQLPAD_BACKEND_DB_URI、SQLPAD_SEED_DATA_PATH、SQLPAD_APP_LOG_LEVEL/SQLPAD_WEB_LOG_LEVEL等）。

8.2 基于 ODBC 版镜像扩展 Oracle 驱动

oracle-odbc-image/Dockerfile 展示了更复杂的多阶段扩展：

• 第一阶段用alpine下载解压 Oracle Instant Client 精简版与 ODBC 驱动压缩包，减少后续改动脚本时的重复下载；
• 第二阶段FROM sqlpad/sqlpad:odbc（官方 ODBC 版镜像，对应根目录 Dockerfile 中ODBC_ENABLED=true构建产物），把解压好的/opt拷入，设置TNS_ADMIN、LD_LIBRARY_PATH，运行odbc_update_ini.sh注册 ODBC 驱动；
• 将 generate-tnsnames.sh 放入/etc/docker-entrypoint.d/——SQLPad 的 docker-entrypoint 脚本会在启动服务器前遍历并source该目录下所有.sh文件，因此该脚本会在每次容器启动时动态生成tnsnames.ora。

generate-tnsnames.sh 支持两种配置方式：通过TNS_URL直接下载现成的tnsnames.ora；或通过TNS_[X]_NAME/TNS_[X]_HOST/TNS_[X]_PORT/TNS_[X]_SID/TNS_[X]_SERVICE_NAME系列环境变量按索引追加多个 TNS 条目（缺失HOST或同时缺失SID/SERVICE_NAME会报错退出）。这为通过 ODBC 连接 Oracle 提供了完整的镜像内建支持，测试时该 Dockerfile 还设置了SQLPAD_AUTH_DISABLED=true与SQLPAD_AUTH_DISABLED_DEFAULT_ROLE=admin便于无认证验证。

九、从示例到生产的注意事项

1. 数据持久化是底线：docker run场景务必挂载/var/lib/sqlpad（参考原文档第一段警告）；compose 场景建议使用具名卷或宿主机共享目录。
2. 安全加固：示例中的密码（admin、password、SuperP4ssw0rd!）仅用于演示，正式环境应更换强密码，并通过-p 127.0.0.1:3000:3000等方式限制暴露范围。
3. 后端数据库：多实例或生产部署可参考 MariaDB 示例，用SQLPAD_BACKEND_DB_URI将 SQLPad 元数据迁移到外部数据库，并考虑SQLPAD_SESSION_STORE、SQLPAD_QUERY_RESULT_STORE的存储策略（file/database/redis/memory四种可选，redis需要同时设置SQLPAD_REDIS_URI，见 docs/src/pages/en/configuration.md）。
4. 种子数据的“更新不删除”语义：删除种子 JSON 不会删除 SQLPad 里已导入的数据，变更种子内容则会在下次启动时按 id 覆盖更新，规划数据时需注意这一行为（server/lib/load-seed-data.js 始终执行 update/create）。
5. Kubernetes 环境参考：仓库 kubernetes-examples/postgres-k8s/sqlpad-deployment.yml 提供了与 postgres 示例相同配置的 K8s Deployment 写法（ConfigMap 注入初始化脚本、环境变量预置pgdemo连接），可作为从 compose 迁移到 K8s 的起点。

至此，你已经掌握了 SQLPad 从“一条命令跑起来”到“compose 编排多数据库 + 种子数据 + 镜像扩展”的完整 Docker 落地路径。需要更多细节时，可继续深入阅读 docker-examples/postgres-docker-compose/README.md（原文档的实操步骤）、docs/src/pages/en/configuration.md（全部配置项）与 docs/src/pages/en/seed-data.md（种子数据规范）。

• 后端
• 数据可视化
• 数据库
• 数据分析