Bytebase 3.23.1 配置参数详解

目标：逐项给出 Bytebase 3.23.1 全部启动参数、环境变量与子命令的实测行为、真实默认值与典型报错，作为部署（安装指南 / Compose 部署）与运维（进阶实战）的参数字典。本文每条命令与回显均在 Ubuntu 22.04.5 LTS + Bytebase 3.23.1（官方镜像，仅分发形态为镜像）环境实测采集，参数以启动时追加在镜像指令后的方式传入（下文示例均为实测原样）。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
Bytebase 版本	3.23.1（`bytebase version` 实测：`Bytebase version: 3.23.1`，`Git commit hash: 16b89d9b49741c65623970038859d0d6397c8fe5`）
镜像入口	Entrypoint `[bytebase]`，默认启动参数 `[--port 8080 --data /var/opt/bytebase]`（`docker inspect` 实测）
内置健康检查	`curl -f http://localhost:8080/healthz`，间隔 300 秒、超时 60 秒（镜像 HEALTHCHECK 实测值）
镜像默认环境变量	`OPENSSL_CONF=/etc/ssl/`、`GOGC=50`（`docker inspect` 实测）
测试方式	每个参数以一次性进程启动验证，观察启动日志、监听端口与接口行为

二、概览

Bytebase 3.23.1 的运行配置由三部分组成：

类别	内容	说明
命令行标志	`--port`、`--data`、`--external-url`、`--debug`、`--enable-json-logging`、`--metrics-remote-access`、`--ha`、`--saas`、`--memory-profile-threshold` 共 9 个	以 `bytebase --flag value` 形式传入；容器部署时追加在镜像名之后
环境变量	`PG_URL`（外置元数据库连接串）	唯一的业务环境变量；注意没有 `--pg` 标志——外置元数据库只能通过 `PG_URL` 配置
子命令	`version`、`recovery`、`completion`	版本查询、管理员密码找回入口、Shell 自动补全生成

⚠️ 特别说明：不少资料提到 Bytebase 可用 --pg 指定元数据库，3.23.1 实测不存在该标志（bytebase --help 全文可证），外置 PostgreSQL 元数据库一律用 PG_URL 环境变量配置，见 3.10 节。

三、逐项实测

3.1 帮助与版本：`--help`、`version`

bytebase --help 全文（实测逐行照抄，注意 --port 的官方帮助原文默认值描述为 Default to 80 (default 8080)，实际生效默认端口是 8080，以 (default 8080) 为准）：

Bytebase is a web-based database schema change and version control tool for teams.

Usage:
  bytebase [flags]

Flags:
      --data string                    not recommended for production. Directory where Bytebase stores data if PG_URL is not specified. If relative path is supplied, then the path is relative to the directory where Bytebase is under (default "/var/opt/bytebase")
      --debug                          enable debug level log
      --enable-json-logging            enable output logs in bytebase in json format
      --external-url string            the external URL where user visits Bytebase, must start with http:// or https://
      --ha                             run in HA mode
  -h, --help                           help for bytebase
      --memory-profile-threshold uint  the threshold of memory usage in bytes to trigger a memory profile
      --metrics-remote-access          enable remote access to metrics
      --port int                       port where Bytebase server runs. Default to 80 (default 8080)
      --saas                           run in SaaS mode

Additional help topics:
  bytebase completion  Generate the autocompletion script for the specified shell
  bytebase recovery    Recover password sign-in for a self-hosted deployment

Use "bytebase [command] --help" for more information about a command.

bytebase version 实测输出：

Bytebase version: 3.23.1
Git commit hash: 16b89d9b49741c65623970038859d0d6397c8fe5

3.2 `--port`：服务监听端口

帮助原文：port where Bytebase server runs. Default to 80 (default 8080)。默认 8080。实测改为 9099 启动（追加在镜像启动参数后）：

docker run -d --name bb-port-demo -p 18089:9099 bytebase/bytebase:3.23.1 --port 9099

Version 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5) has started on port 9099 🚀

curl -s http://localhost:18089/healthz; echo

OK

💡 内嵌元数据库（见 3.10 节说明）固定占用容器内 8082 端口（启动日志 Start embedded Postgres datastorePort=8082），与 --port 无关；--port 只决定 Web/API 监听端口。

3.3 `--data`：数据目录

帮助原文：not recommended for production. Directory where Bytebase stores data if PG_URL is not specified. If relative path is supplied, then the path is relative to the directory where Bytebase is under (default "/var/opt/bytebase")。三层含义实测确认：

默认值 /var/opt/bytebase：未指定时的数据目录；
「not recommended for production」：帮助原文明确建议生产环境改用 PG_URL 外置元数据库（数据落外部 PostgreSQL，见 3.10 节），--data 面向单机内嵌元数据库场景；
目录必须已存在：实测指向不存在的目录会直接拒绝启动（真实报错）：

docker run --rm bytebase/bytebase:3.23.1 --port 9099 --data /bb-data

{"time":"2026-10-16T17:03:51.88262898Z","level":"ERROR",...,"msg":"unable to access --data directory /bb-data: stat /bb-data: no such file or directory"}

目录存在（本例经 -v 挂载宿主目录 /tmp/bbdata 到 /bb-data）时正常启动，元数据全部落在该目录（实测目录结构与启动日志）：

docker run -d --name bb-data-demo -v /tmp/bbdata:/bb-data -p 18089:9099 \
  bytebase/bytebase:3.23.1 --port 9099 --data /bb-data

dataDir=/bb-data
Version 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5) has started on port 9099 🚀

docker exec bb-data-demo ls /bb-data

pgdata

💡 pgdata/ 即内嵌 PostgreSQL 的数据子目录；备份与迁移就是备份整个 --data 目录（详见《Bytebase 3.23.1 进阶实战与运维》）。相对路径按「bytebase 可执行文件所在目录」解析。

3.4 `--external-url`：外部访问地址

帮助原文：the external URL where user visits Bytebase, must start with http:// or https://。用途：平台在通知邮件等场景生成指向 Bytebase 的外部链接时使用该地址（非本机访问地址本身）。

强制格式校验（实测：不带协议头直接拒绝启动）：

docker run --rm bytebase/bytebase:3.23.1 --port 9093 --external-url bb.quzuo.net

time=2026-10-16T17:07:29.199Z level=ERROR ... msg="invalid --external-url" error="bb.quzuo.net must start with http:// or https://"

合法值实测（http:// 开头）正常启动，无额外日志行：

docker run -d --name bb-ext-demo -p 18086:9090 \
  bytebase/bytebase:3.23.1 --port 9090 --data /var/opt/bytebase --external-url http://bb.quzuo.net:8080

Version 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5) has started on port 9090 🚀

💡 实测该值不会出现在工作区设置（settings/WORKSPACE_PROFILE 无对应字段），它只影响平台生成外部链接的行为。反向代理接入时的域名配置实践见《Bytebase 3.23.1 Docker Compose 部署指南》3.5 节。

3.5 `--debug`：调试日志

帮助原文：enable debug level log。实测对比：开启后日志中新增 level=DEBUG 行（实测某次启动含 12 条 DEBUG 行，示例为实测原文）：

time=2026-10-16T15:56:27.690Z level=DEBUG source=api/v1/audit_log_service.go:118 msg="update audit log"

💡 排查工单执行、审批回调等问题时临时开启；生产常态建议关闭（日志量大）。

3.6 `--enable-json-logging`：JSON 格式日志

帮助原文：enable output logs in bytebase in json format。实测开启后日志由 time=... level=INFO source=... msg=... 文本格式变为 JSON 行格式（同一启动日志对照）：

（默认文本格式）
time=2026-10-16T17:04:22.81622214Z level=INFO source=server/server.go:108 msg="-----Config BEGIN-----"

（开启 --enable-json-logging 后）
{"time":"2026-10-16T17:04:22.81622214Z","level":"INFO","source":{"function":"github.com/bytebase/bytebase/backend/server.NewServer","file":"server/server.go","line":108},"msg":"-----Config BEGIN-----"}

💡 接入 ELK/Loki 等日志平台时开启，字段解析零成本；错误级别同样输出 JSON（如 3.3 节的 level":"ERROR" 报错）。

3.7 `--metrics-remote-access`：开放 Prometheus 指标

帮助原文：enable remote access to metrics。实测对比 /metrics 接口：

（默认，未加参数）
curl -s -o /dev/null -w '%{http_code}' http://localhost:18080/metrics
404

（加 --metrics-remote-access 后）
curl -s -o /dev/null -w '%{http_code}' http://localhost:18091/metrics
200

开启后返回 Prometheus 格式指标（实测节选）：

# HELP api_request_duration_seconds The HTTP request latencies in seconds.
# TYPE api_request_duration_seconds histogram
api_request_duration_seconds_bucket{code="200",host="localhost:18091",method="GET",url="/metrics",le="0.005"} 1

💡 生产接入 Prometheus 抓取时加上该参数，抓取路径 /metrics；不要把该端口暴露到公网（指标含接口时延等信息）。

3.8 `--ha`：高可用模式

帮助原文：run in HA mode。HA 模式强制要求外置元数据库：不带 PG_URL 直接启动会报错退出（实测原文）：

docker run --rm bytebase/bytebase:3.23.1 --port 9096 --ha

level=ERROR source=cmd/root.go:218 msg="Cannot new server" error="HA mode requires external PostgreSQL (set PG_URL environment variable)"

配合 PG_URL 启动成功（实测，多副本共用同一外部元数据库，每个副本启动时生成独立的 replicaID）：

docker run -d --name bb-ha-demo -v /tmp/bbdata4:/var/opt/bytebase \
  -e PG_URL='postgresql://bytebase:密码@pgmeta:5432/bb_ha_test' \
  bytebase/bytebase:3.23.1 --port 9096 --ha

replicaID=0f9a068d-8d6f-4358-81d8-09b8170cca62
Version 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5) has started on port 9096 🚀

curl -s http://localhost:18092/healthz
OK

💡 单副本场景即使外置元数据库也不需要 --ha；HA 用于同库多副本部署（副本间通过元数据库协调，日志中的 replicaID 每个进程不同）。注意 HA 模式下各副本仍需自行保证 --port/负载均衡层面的分流。

3.9 `--saas` 与 `--memory-profile-threshold`

--saas（帮助原文：run in SaaS mode）：Bytebase 自营云服务（SaaS）形态专用，自托管部署不应使用（自托管参考文档与安装流程均基于默认 prod 模式）。
--memory-profile-threshold uint（帮助原文：the threshold of memory usage in bytes to trigger a memory profile）：内存使用超过阈值（字节）时自动生成内存 profile 用于排障。平时不设置；配合 --debug 在内存问题排查时使用，例如阈值 2 GiB 即 --memory-profile-threshold 2147483648。

3.10 环境变量 `PG_URL`：外置元数据库

Bytebase 的元数据（项目、工单、用户、审核规则等）默认存在内嵌 PostgreSQL（随 --data 目录，监听容器内 8082 端口，见 3.2/3.3 节）；设置 PG_URL 后改用外部 PostgreSQL，官方要求 PostgreSQL 14 及以上、库编码 UTF-8。连接串格式：

postgresql://用户名:密码@主机:端口/数据库名

实测切换外置元数据库（在 compose 网络中连 postgres:16，库名 bytebase）：

docker run -d --name bb-extpg-demo \
  -v /tmp/bbdata-extpg:/var/opt/bytebase \
  -e PG_URL='postgresql://bytebase:q1w2e3r4@pgmeta:5432/bytebase' \
  bytebase/bytebase:3.23.1 --port 8080

（启动日志中不再出现 "-----Embedded Postgres BEGIN-----" 行，元数据直接落外部库）

验证元数据已落外部库（实测：48 张元数据表）：

docker exec bytebase-pgmeta psql -U bytebase -d bytebase -t -A \
  -c "SELECT count(*) FROM pg_tables WHERE schemaname='public';"

连接串错误时的启动报错（实测：密码错误，进程退出）：

level=ERROR source=cmd/root.go:218 msg="Cannot new server" error="failed to connect to `user=bytebase database=bytebase`:
  172.22.0.2:5432 (pgmeta): tls error: server refused TLS connection
  172.22.0.2:5432 (pgmeta): failed SASL auth: FATAL: password authentication failed for user \"bytebase\" (SQLSTATE 28P01)"

💡 ① --data 与 PG_URL 同时提供时，--data 仅存放本地临时文件，元数据在外部库（帮助原文 stores data if PG_URL is not specified）；② 密码含 @、/、: 等字符需百分号转义；③ 库必须 UTF-8 编码（CREATE DATABASE bytebase ENCODING 'UTF8';），PostgreSQL 13 及以下不受支持；④ 报错里的 server refused TLS connection 是先尝试 TLS 再回退明文的正常过程，最终失败原因看 SQLSTATE 行。

3.11 镜像内置约定（免记忆速查）

项	实测值
Entrypoint / 默认参数	`[bytebase]` + `[--port 8080 --data /var/opt/bytebase]`
Web/API 端口	容器内 8080（`--port` 可改）
内嵌元数据库端口	容器内 8082（固定，不对外）
健康检查	`curl -f http://localhost:8080/healthz`（Interval 300s / Timeout 60s），`/healthz` 返回纯文本 `OK`；`/health` 是前端页面不能用作探活
镜像环境变量	`OPENSSL_CONF=/etc/ssl/`、`GOGC=50`（Go GC 目标 50%）
用户/工作目录	root / `/`
`--init`	官方启动示例带 `--init`（注入 tini 回收子进程），compose 等价写法 `init: true`

3.12 `recovery` 子命令：找回管理员登录入口

bytebase recovery --help 实测：

Recover password sign-in for a self-hosted deployment

Usage:
  bytebase recovery [flags]

Flags:
  -h, --help   help for recovery

用途：管理员忘记密码且无其他管理员可重置时，在部署机上以 recovery 模式进入恢复流程（按提示操作重置管理员凭据后重启服务恢复正常模式）。这是自托管的最后手段，日常用控制台 Settings → Users 重置密码即可。

3.13 `completion` 子命令：Shell 自动补全

bytebase completion --help 实测：

Generate the autocompletion script for bytebase for the specified shell.
See each sub-command's help for details on how to use the generated script.

Usage:
  bytebase completion [command]

Available Commands:
  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

💡 直接操作 bytebase 二进制的场景可用（如 source <(bytebase completion bash)）；容器部署时参数在宿主机输入，此命令用得较少。

四、实战示例

4.1 示例：自定义端口 + JSON 日志 + 开放指标的一次性验证

docker run -d --name bb-tuned -v /tmp/bbdata:/var/opt/bytebase -p 18089:9099 \
  bytebase/bytebase:3.23.1 --port 9099 --enable-json-logging --metrics-remote-access
sleep 15
curl -s http://localhost:18089/healthz
curl -s -o /dev/null -w 'metrics:%{http_code}\n' http://localhost:18089/metrics
docker logs bb-tuned 2>&1 | head -2

OK
metrics:200
{"time":"2026-10-16T17:04:22.81622214Z","level":"INFO",...,"msg":"-----Config BEGIN-----"}

4.2 示例：切换为外置元数据库（保留内嵌数据迁移方法）

切换前先用内嵌数据目录完成备份（tar 包），再以 PG_URL 启动新实例（元数据为空库时启动会自动初始化 schema，与首次启动一致）：

# 1. 停旧实例并备份 --data 目录（元数据在此目录的 pgdata/ 内）
docker stop bb-tuned
tar -czf /opt/bytebase/data-backup-$(date +%F).tar.gz -C /tmp/bbdata .

# 2. 外部库准备（PostgreSQL 14+，UTF-8）
psql -h 192.168.1.62 -U postgres -c "CREATE DATABASE bytebase ENCODING 'UTF8';"   # 主机地址按实际替换

# 3. 以 PG_URL 启动
docker run -d --name bb-extpg -v /tmp/bbdata:/var/opt/bytebase \
  -e PG_URL='postgresql://bytebase:q1w2e3r4@192.168.1.62:5432/bytebase' \
  bytebase/bytebase:3.23.1 --port 8080
curl -s http://localhost:8080/healthz

OK

💡 注意：切换外置库后是全新元数据（内嵌库里的历史工单/项目不会自动搬移）；如需搬迁历史数据，用 PostgreSQL 层面的导出导入（pg_dump 内嵌库 → 恢复到外部库，再以 PG_URL 启动），操作步骤见《Bytebase 3.23.1 进阶实战与运维》。

4.3 示例：HA 双副本的参数组合

# 副本 1 与副本 2 共用同一外部元数据库，各自独立数据目录与端口
docker run -d --name bb-ha-r1 -v /tmp/bbr1:/var/opt/bytebase -p 8081:8080 \
  -e PG_URL='postgresql://bytebase:q1w2e3r4@192.168.1.62:5432/bytebase' \
  bytebase/bytebase:3.23.1 --port 8080 --ha
docker run -d --name bb-ha-r2 -v /tmp/bbr2:/var/opt/bytebase -p 8082:8080 \
  -e PG_URL='postgresql://bytebase:q1w2e3r4@192.168.1.62:5432/bytebase' \
  bytebase/bytebase:3.23.1 --port 8080 --ha
# 验证
curl -s http://localhost:8081/healthz && curl -s http://localhost:8082/healthz; echo

OK
OK

五、注意事项与常见问题

Q1：启动报 unable to access --data directory ...: stat ...: no such file or directory？

--data 指向的目录必须已存在（实测），先创建目录（容器场景确认挂载点已建立）再启动；相对路径以 bytebase 可执行文件所在目录为基准。

Q2：启动报 can't read memory.max from cgroup v2？

内嵌元数据库（TiDB/PostgreSQL 组件）启动时会读取 cgroup v2 的 memory.max 判断内存限额。真实报错：unexpected error [error="can't read memory.max from cgroup v2: open /sys/fs/cgroup/memory.max: no such file or directory"]。物理机/常规虚机上不会出现；出现在受限运行环境（cgroup 视图被遮蔽）时，保证进程能读到自身 cgroup 的 memory.max（调整运行环境的 cgroup 挂载方式）即可。

Q3：--pg 参数用了没反应？

3.23.1 没有 --pg 标志（--help 全文可证），外置元数据库用 PG_URL 环境变量，见 3.10 节；旧资料中的 --pg 写法属于历史版本或讹传。

Q4：--ha 启动报 HA mode requires external PostgreSQL？

HA 模式必须配 PG_URL（实测报错原文见 3.8 节）。先准备外置元数据库，再加 --ha 启动。

Q5：PG_URL 连接报 password authentication failed (SQLSTATE 28P01)？

账号或密码错误（实测原文见 3.10 节）。核对连接串三要素：用户名、密码（特殊字符需百分号转义）、库名；确认外部库版本 ≥ 14 且编码 UTF-8。

Q6：--external-url 设置后在哪里生效？

用于平台生成外部链接（通知邮件等），必须以 http:// 或 https:// 开头（实测校验原文：must start with http:// or https://），否则拒绝启动。它不改变服务监听地址（那是 --port），也不出现在工作区设置里（实测 settings/WORKSPACE_PROFILE 无此字段）。

Q7：/metrics 返回 404？

默认不开放远程指标访问，加 --metrics-remote-access 后返回 200（实测），抓取地址 http://<服务地址>/metrics。

Q8：--port 帮助文字写 "Default to 80" 但实际是 8080？

以帮助输出括号里的 (default 8080) 为准（实测 8080）。帮助文字 Default to 80 为官方文案瑕疵，不影响行为。

六、参考链接

Bytebase 官方环境变量文档：https://www.bytebase.com/docs/get-started/install/environment-variables/
Bytebase 外置元数据库文档：https://www.bytebase.com/docs/get-started/install/external-postgres/
Bytebase 高可用说明：https://www.bytebase.com/docs/administration/ha/
Bytebase 源码（cmd/root.go 参数定义）：https://github.com/bytebase/bytebase/tree/3.23.1/backend/bin/server
本专栏相关文档：《Bytebase 3.23.1 Ubuntu 22.04 安装指南》《Bytebase 3.23.1 Docker Compose 部署指南》《Bytebase 3.23.1 进阶实战与运维》

Bytebase 3.23.1 配置参数详解

Bytebase 3.23.1 配置参数详解

一、环境信息

二、概览

三、逐项实测

3.1 帮助与版本：--help、version

3.2 --port：服务监听端口

3.3 --data：数据目录

3.4 --external-url：外部访问地址

3.5 --debug：调试日志

3.6 --enable-json-logging：JSON 格式日志

3.7 --metrics-remote-access：开放 Prometheus 指标

3.8 --ha：高可用模式

3.9 --saas 与 --memory-profile-threshold

3.10 环境变量 PG_URL：外置元数据库

3.11 镜像内置约定（免记忆速查）

3.12 recovery 子命令：找回管理员登录入口

3.13 completion 子命令：Shell 自动补全

四、实战示例

4.1 示例：自定义端口 + JSON 日志 + 开放指标的一次性验证

4.2 示例：切换为外置元数据库（保留内嵌数据迁移方法）

4.3 示例：HA 双副本的参数组合

五、注意事项与常见问题

六、参考链接

3.1 帮助与版本：`--help`、`version`

3.2 `--port`：服务监听端口

3.3 `--data`：数据目录

3.4 `--external-url`：外部访问地址

3.5 `--debug`：调试日志

3.6 `--enable-json-logging`：JSON 格式日志

3.7 `--metrics-remote-access`：开放 Prometheus 指标

3.8 `--ha`：高可用模式

3.9 `--saas` 与 `--memory-profile-threshold`

3.10 环境变量 `PG_URL`：外置元数据库

3.12 `recovery` 子命令：找回管理员登录入口

3.13 `completion` 子命令：Shell 自动补全