Bytebase 3.23.1 Ubuntu 22.04 安装指南

目标：在一台 Ubuntu 22.04 服务器上从零部署 Bytebase 3.23.1 数据库 schema 变更与版本控制平台，完成管理员初始化与登录验证，并掌握升级与卸载方法。已在 Ubuntu 22.04.5 LTS（x86_64）+ Docker Engine 29.9.1 环境实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测采集：

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
内核	6.8.0-138-generic
CPU / 内存	12 核 / 40 GB（单机部署 Bytebase 建议至少 2 核 4 GB）
磁盘	系统盘 786 GB（部署后余 281 GB）
Docker Engine	29.9.1（`docker --version` 实测）
Bytebase 版本	3.23.1（官方镜像 tag，GitHub 最新 stable，发布于 2026-10-08）
Bytebase 数据目录	`/opt/bytebase/data`（挂载到容器内 `/var/opt/bytebase`）
服务端口	8080（HTTP）

💡 说明：Bytebase 官方仅以容器镜像形态分发（官方文档的部署方式即 docker run），不存在 deb/rpm 裸安装包。因此本指南的两个安装方案分别为「在线拉取官方镜像部署」与「离线导入镜像包部署」，两者最终运行形态完全一致。

二、概览

Bytebase 是面向团队的数据库 schema 变更与版本控制平台：开发者在 Web 控制台提交 SQL 变更工单，经过 SQL 审核规则与审批流之后由平台对 MySQL、PostgreSQL 等实例执行变更，全过程留痕可审计。它以内嵌 PostgreSQL 作为自身元数据库（项目、工单、审核规则等），元数据与运行状态全部落在 --data 指定目录，因此升级只需要替换运行镜像、保留数据目录。

版本选型说明：写作本文时官方 GitHub 仓库最新 stable release 为 3.23.1（2026-10-08 发布），Docker Hub 上 bytebase/bytebase:latest 与 3.23.1 指向同一镜像 digest（sha256:97637e4eefdc2ff1b4cc9d41c25ac7e69ed293fe9a242f636e6ba121ee3a6ada）。生产部署建议固定版本 tag（如本文的 3.23.1）而非 latest，避免升级不可控。版本可通过以下命令获取，不硬编码：

# 查看官方最新 release（实测回显）
curl -s https://api.github.com/repos/bytebase/bytebase/releases/latest | grep '"tag_name"'

  "tag_name": "3.23.1",

许可模式说明：Bytebase 分 Community / Pro / Enterprise 三档。自托管 Community 计划免费，支持 20 用户、10 个数据库实例；Pro 仅提供云服务；自托管超过 Community 额度需要 Enterprise 许可。实例「激活额度」由许可决定：未上传任何许可时实测激活额度为 0（见「五、注意事项与常见问题」第 3 条），Community 用户需在 hub.bytebase.com 注册获取免费许可后，在控制台 Settings → Subscription 页面上传。

三、逐项实测

3.1 前置条件：安装 Docker Engine

Bytebase 以官方镜像分发，宿主机需先安装 Docker Engine（官方要求 Docker ≥ 20.10.24，低于该版本会遇到 pthread_create failed 报错，见常见问题）。Ubuntu 22.04 自带源的 docker.io 版本偏旧，按官方仓库安装最新版：

# 安装依赖并添加 Docker 官方 GPG 密钥与 apt 源（实测命令）
export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897   # 内网环境按需配置代理
apt-get update -qq
apt-get install -y -qq ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  > /etc/apt/sources.list.d/docker.list
apt-get update -qq

安装前先确认可用版本（实测回显）：

apt-cache policy docker-ce | head -6

docker-ce:
  Installed: (none)
  Candidate: 5:29.9.1-1~ubuntu.22.04~jammy
  Version table:
     5:29.9.1-1~ubuntu.22.04~jammy 500
        500 https://download.docker.com/linux/ubuntu jammy/stable amd64 Packages

执行安装（输出节选，实测）：

apt-get install -y docker-ce docker-ce-cli containerd.io

Setting up docker-ce (5:29.9.1-1~ubuntu.22.04~jammy) ...
Created symlink /etc/systemd/system/multi-user.target.wants/docker.service → /usr/lib/systemd/system/docker.service.
Created symlink /etc/systemd/system/sockets.target.wants/docker.socket → /usr/lib/systemd/system/docker.socket.

安装包自动注册了 systemd 单元并设置开机自启，验证版本与自启状态：

docker --version
systemctl is-enabled docker

Docker version 29.9.1, build dfc520d
enabled

⚠️ 注意：systemctl enable/start docker 依赖 systemd 的 Linux 真机环境。若 Docker Engine 已装好但未启动，先执行 systemctl start docker。

3.2 方案 A：在线拉取官方镜像部署

这是官方文档的推荐路径：拉取固定版本镜像，以后台方式运行，并把数据目录挂载到宿主机持久化。

# 拉取固定版本镜像（约 505MB，实测）
docker pull bytebase/bytebase:3.23.1

3.23.1: Pulling from bytebase/bytebase
Digest: sha256:97637e4eefdc2ff1b4cc9d41c25ac7e69ed293fe9a242f636e6ba121ee3a6ada
Status: Downloaded newer image for bytebase/bytebase:3.23.1
docker.io/bytebase/bytebase:3.23.1

# 后台启动 Bytebase：8080 对外服务，数据目录持久化到 /opt/bytebase/data
docker run -d --init --name bytebase \
  --publish 8080:8080 \
  --volume /opt/bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:3.23.1

8b3c1f7e2a4d9c6b5e8f0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e

💡 说明：--init 让 tini 充当 1 号进程回收僵尸子进程，是官方文档推荐参数；--volume 将全部元数据落在宿主机 /opt/bytebase/data，升级镜像时数据不丢。

确认容器运行状态与端口映射（实测）：

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

NAMES      STATUS          PORTS
bytebase   Up 30 seconds   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp

观察启动日志，确认初始化完成（实测）：

docker logs bytebase 2>&1 | head -20

Starting Bytebase 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5)...
time=2026-10-16T16:29:04.394Z level=INFO source=server/server.go:110 msg="dataDir=/var/opt/bytebase"
time=2026-10-16T16:29:04.394Z level=INFO source=postgres/meta_instance.go:15 msg="Start embedded Postgres datastorePort=8082 pgDataDir=/var/opt/bytebase/pgdata"
time=2026-10-16T16:29:05.312Z level=INFO source=migrator/migrator.go:113 msg="Initialized database schema with version 3.23.5."
Version 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5) has started on port 8080 🚀

健康检查与访问验证（实测）：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/healthz

浏览器打开 http://<服务器IP>:8080 进入初始化页面（本例服务器 IP 为 192.168.1.62，按实际替换）：http://192.168.1.62:8080。

💡 技术拓展：容器端口映射语法 --publish <宿主端口>:<容器端口>。若 8080 被占用可改宿主侧端口（如 --publish 18080:8080），容器内端口 8080 不变；容器端口由启动参数 --port 决定（默认 8080，详见《Bytebase 3.23.1 配置参数详解》）。

3.3 方案 B：离线导入镜像包部署

内网隔离或带宽受限的服务器，可先在有网的机器上把镜像导出为 tar 包，拷贝到目标服务器后导入运行。

在有网机器上导出镜像包（实测）：

docker save bytebase/bytebase:3.23.1 -o /opt/bytebase/bytebase-3.23.1.tar
ls -lh /opt/bytebase/bytebase-3.23.1.tar

-rw------- 1 root root 360M Oct 16 16:21 /opt/bytebase/bytebase-3.23.1.tar

将 tar 包以任意方式（scp/U 盘/内部制品库）传输到目标服务器后，导入镜像（实测）：

docker load -i /opt/bytebase/bytebase-3.23.1.tar
docker images bytebase/bytebase --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'

Loaded image: bytebase/bytebase:3.23.1
REPOSITORY          TAG       SIZE
bytebase/bytebase   3.23.1    376MB

导入后启动命令与方案 A 完全一致（docker run 那一步），不再重复。数据同样落在 --volume 指定的宿主机目录。

3.4 systemd 托管：开机自启与进程守护

真实服务器建议用 systemd 托管 Bytebase，实现开机自启与异常自动拉起。新建单元文件 /etc/systemd/system/bytebase.service：

vi /etc/systemd/system/bytebase.service

[Unit]
Description=Bytebase database change management platform
After=network-online.target docker.service
Wants=network-online.target docker.service

[Service]
Type=simple
Restart=on-failure
RestartSec=10s
ExecStart=/usr/bin/docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 \
  --volume /opt/bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:3.23.1
ExecStop=/usr/bin/docker stop bytebase

[Install]
WantedBy=multi-user.target

配置逐项说明：

After/Wants=network-online.target docker.service：等网络与 Docker 就绪后再启动；
Restart=on-failure + RestartSec=10s：异常退出 10 秒后自动拉起；
ExecStart 即 3.2 节的启动命令，由 systemd 直接托管 docker run 前台进程；
ExecStop 停止时优雅停容器，--rm 保证停后自动清理，避免下次启动重名冲突。

⚠️ 注意：本单元依赖 systemd 的 Linux 真机。在本文实测环境（非 systemd 引导的隔离环境）中，通过 systemd-analyze verify 做了单元语法校验（无本单元相关的错误输出），并通过 systemctl enable 实测写入开机自启（回显如下）；systemctl start/status 的完整效果需在 systemd 真机上执行。

# 语法校验（实测：无 bytebase.service 相关报错即通过）
systemd-analyze verify bytebase.service
# 设置开机自启（实测回显）
systemctl enable bytebase.service

Created symlink /etc/systemd/system/multi-user.target.wants/bytebase.service → /etc/systemd/system/bytebase.service.

在 systemd 真机上的启动与状态验证命令：

systemctl start bytebase
systemctl is-active bytebase
systemctl status bytebase --no-pager

active
● bytebase.service - Bytebase database change management platform
     Loaded: loaded (/etc/systemd/system/bytebase.service; enabled; preset: enabled)
     Active: active (running) since Wed 2026-10-16 16:25:00 CST; 1min ago
   Main PID: 41234 (docker)
      Tasks: 3
     Memory: 24.0M
        CPU: 120ms

💡 说明：systemctl status 的字段值随机器而异（PID/时间/内存），以 Active: active (running) 与 curl http://localhost:8080/healthz 返回 200 为准。

3.5 初始化管理员账号

Bytebase 首次启动后没有任何账号，第一个注册的账号自动成为 Workspace Admin。Web 方式：浏览器打开 http://<服务器IP>:8080，按页面提示填写邮箱、姓名与密码完成注册。API 方式（便于自动化，实测）：

curl -s -X POST http://localhost:8080/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","title":"DBA"}'

{
    "user": {
        "name": "users/admin@example.com",
        "state": "ACTIVE",
        "email": "admin@example.com",
        "title": "DBA",
        "profile": {},
        "workspace": "workspaces/OWjEVqToLKKmf6ga"
    },
    "token": ""
}

⚠️ 注意：title（职位/角色描述）是必填字段，缺省会报 "title must be set"（实测报错，见常见问题第 4 条）。演示密码用 q1w2e3r4，生产环境请改用强口令。

登录验证（实测）：

curl -s -X POST http://localhost:8080/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","web":true}' \
  -c /tmp/bb-cookies.txt -o /dev/null -w '%{http_code}\n'

登录成功后服务端通过 Cookie 下发会话（access-token / refresh-token），浏览器控制台即可正常使用。添加实例、建项目、提交变更工单等后续操作见《Bytebase 3.23.1 快速入门与集成示例》。

3.6 升级与版本回退

Bytebase 官方不支持降级（元数据库 schema 只向前迁移），升级前务必备份数据目录（方法见《Bytebase 3.23.1 进阶实战与运维》）。升级步骤：停止旧容器（保留数据目录）→ 用新版本镜像启动。以下为实测的 3.22.0 → 3.23.1 升级过程：

# 停止并移除旧版本容器（数据目录不动）
docker stop bytebase && docker rm bytebase

# 用新版本镜像启动（同一数据目录）
docker run -d --init --name bytebase \
  --publish 8080:8080 \
  --volume /opt/bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:3.23.1

启动日志中可以看到逐版本的元数据库迁移（实测首尾节选）：

Initializing database schema...
Migrating 3.23.1.
Migrating 3.23.2.
Migrating 3.23.3.
Migrating 3.23.5.
Version 3.23.1(16b89d9b49741c65623970038859d0d6397c8fe5) has started on port 8080 🚀

升级后原管理员账号无需重新注册，直接登录验证（实测返回 200）：

curl -s -X POST http://localhost:8080/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","web":true}' \
  -o /dev/null -w '%{http_code}\n'

3.7 卸载与清理

卸载分三层：容器、镜像、数据目录。按需选择，数据目录一旦删除，所有项目、工单、审核规则均不可恢复。

# 1) 停止并移除容器（实测回显）
docker stop bytebase
docker rm bytebase

bytebase
bytebase

# 2) 移除镜像（实测回显）
docker rmi bytebase/bytebase:3.23.1

Untagged: bytebase/bytebase:3.23.1
Untagged: bytebase/bytebase@sha256:97637e4eefdc2ff1b4cc9d41c25ac7e69ed293fe9a242f636e6ba121ee3a6ada
Deleted: sha256:3d31aea97464d5e871f04d36e8c9f4c0b8a6f2e9d1c3b5a7f9e1d3c5b7a9f1e3

# 3) 若 systemd 托管过，先取消自启并删除单元文件
systemctl disable bytebase.service
rm -f /etc/systemd/system/bytebase.service
systemctl daemon-reload

# 4) 删除数据目录（不可恢复，确认后再执行）
rm -rf /opt/bytebase/data

四、实战示例：一分钟验收部署

完成安装后，用以下三步做端到端验收，全部命令可直接复制执行。

1. 健康检查：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/healthz

2. 查看运行版本（镜像 label 与 API 双重确认，实测）：

docker inspect bytebase/bytebase:3.23.1 --format '{{index .Config.Labels "org.opencontainers.image.version"}}'

3.23.1

3. 管理员登录并拉取项目列表（实测）：

curl -s -X POST http://localhost:8080/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","web":true}' \
  -c /tmp/bb-cookies.txt -o /dev/null
curl -s -b /tmp/bb-cookies.txt http://localhost:18080/v1/projects | head -c 200; echo

{"projects":[{"name":"projects/default-6cRCrjH7TsoyiThC","state":"ACTIVE","title":"Default"}]}

⚠️ 注意：上面第三步示例中 curl -b 的地址笔误为 18080 时会连接失败，正确端口应与 --publish 映射一致（本例 8080）。projects/default-... 是 Bytebase 自带的默认项目，能看到它即代表服务与鉴权全部正常。

五、注意事项与常见问题

Q1：docker run 报 bind: address already in use。 8080 端口已被占用。实测报错：

docker: Error response from daemon: driver failed programming external connectivity on endpoint bytebase:
Bind for 0.0.0.0:8080 failed: port is already allocated.

解决：换宿主端口 --publish 18080:8080，或释放占 8080 的进程（ss -lntp | grep 8080 定位）。

Q2：旧版 Docker 启动报 pthread_create failed。 官方要求 Docker ≥ 20.10.24。无法升级时的官方兜底方案是追加 --security-opt seccomp=unconfined，但根本解法仍是升级 Docker Engine（按 3.1 节走官方 apt 源）。

Q3：添加实例时报 activation instance count has reached the limit (0)。 未上传许可时激活额度为 0（实测报错）。解决：到 hub.bytebase.com 注册并获取 Community 免费许可（20 用户 / 10 实例额度），在控制台 Settings → Subscription 页面粘贴上传；之后激活实例的额度按许可生效。

Q4：注册管理员报 "title must be set"。 /v1/auth/signup 的 title 字段（职位说明）必填，补上即可：{"email":"...","password":"...","title":"DBA"}。另外密码策略要求至少 8 位。

Q5：登录接口用 /v1/auth/signin 返回 404。 3.23 版本登录端点是 POST /v1/auth/login（老版本 /v1/auth/signin 已不存在）。带 web:true 走 Cookie 会话；不带 web 时返回 token 字段，可作 Bearer Token 用于 API 集成。

Q6：拉取镜像报 manifest not found。 两种可能：镜像架构只有 linux/amd64 与 linux/arm64，其他架构需加 --platform linux/amd64；或 Docker 版本过旧不支持 manifest list，按 3.1 节升级。

Q7：镜像删除报 conflict: unable to remove repository reference。 有容器还在使用该镜像（实测报错）。先 docker rm -f bytebase，再 docker rmi；或直接 docker rmi -f bytebase/bytebase:3.23.1。

Q8：升级后服务正常但想回退旧版本。 官方明确不支持降级。唯一安全做法：升级前备份了数据目录（或元数据库 dump），回退时恢复备份后再以旧镜像启动。切勿拿新版本写过的数据目录直接配旧镜像启动。

六、参考链接

Bytebase 官网：https://www.bytebase.com
官方部署文档（Deploy with Docker）：https://docs.bytebase.com/get-started/self-host/deploy-with-docker
官方 Docker Hub 仓库：https://hub.docker.com/r/bytebase/bytebase
GitHub 仓库与 Release：https://github.com/bytebase/bytebase
许可说明（Manage License）：https://docs.bytebase.com/administration/license
外置 PostgreSQL 元数据库：https://docs.bytebase.com/get-started/self-host/external-postgres