!Atlassian Bitbucket Server

Atlassian Bitbucket Server Docker 镜像文档

镜像概述和主要用途

Bitbucket Server 是一款本地部署的 Git 源代码管理解决方案，具备安全、快速和企业级特性。可用于创建和管理代码仓库、设置细粒度权限以及进行代码协作，同时提供服务器部署的灵活性。

本 Docker 容器旨在简化 Bitbucket 实例的部署和运行流程。该 Docker 镜像同时以 atlassian/bitbucket 和 atlassian/bitbucket-server 名称发布，两者内容完全相同，但 -server 版本已弃用，仅为保持向后兼容性而保留；建议新安装使用较短的名称 atlassian/bitbucket。

注意：为保持向后兼容性，默认情况下镜像会同时启动 Bitbucket 和嵌入式 OpenSearch。但此配置不推荐使用，尤其是在集群环境中，且存在已知的关闭问题。建议运行独立的 OpenSearch 实例（可在另一个 Docker 容器中），详见下文“连接外部 OpenSearch 集群”的说明。

注意：如果在生产环境中运行此镜像，强烈建议使用特定版本标签而非 latest。因为 latest 标签指向的镜像频繁更新，无法保证向后兼容性。

使用 Docker 版本 >= 20.10.10

核心功能和特性

• 本地部署的 Git 源代码管理，支持仓库创建与管理
• 企业级安全特性与细粒度权限控制
• 支持多种部署模式：独立服务器、智能镜像（Smart Mirror）和数据中心集群（Data Center）
• 灵活的数据库配置，支持外部数据库集成
• 可配置的 JVM 参数，优化性能
• 集成 OpenSearch 搜索引擎（可禁用以连接外部集群）
• 内置诊断工具，支持线程转储、堆转储等故障排查功能

使用场景和适用范围

• 企业级源代码管理：需要本地控制代码仓库和访问权限的组织
• 团队协作：支持多人协作开发，提供代码审查和版本控制功能
• 混合部署环境：可作为独立服务器、智能镜像或数据中心集群节点运行
• 开发流程集成：与 CI/CD 工具集成，支持自动化构建和部署

详细的使用方法和配置说明

快速启动

BITBUCKET_HOME 目录用于存储仓库数据及其他信息，建议将主机目录挂载为数据卷或使用命名卷。在 Data Center 模式下运行时，必须挂载共享文件系统。

卷权限由入口脚本管理。以下示例使用命名卷：

# 创建命名卷
$> docker volume create --name bitbucketVolume
# 启动容器
$> docker run -v bitbucketVolume:/var/atlassian/application-data/bitbucket --name="bitbucket" -d -p 7990:7990 -p 7999:7999 atlassian/bitbucket

也可使用主机目录替代命名卷：

$> docker run -v /data/bitbucket:/var/atlassian/application-data/bitbucket --name="bitbucket" -d -p 7990:7990 -p 7999:7999 atlassian/bitbucket

成功启动后，Bitbucket 可通过 http://localhost:7990 访问。

注意：确保容器分配足够资源，建议至少 2GiB 内存以容纳应用服务器和 Git 进程。更多信息参见支持的平台。

注意：如果在 Mac OS X 上使用 docker-machine，请使用 open [***] ip default):7990 访问。

通用设置

反向代理设置

如果 Bitbucket 在反向代理服务器后运行（如此处所述），需指定以下环境变量使 Bitbucket 感知代理配置：

• SERVER_PROXY_NAME（默认：NONE）：反向代理的完全限定主机名

• SERVER_PROXY_PORT（默认：NONE）：访问 Bitbucket 使用的反向代理端口

• SERVER_SCHEME（默认：http）：访问 Bitbucket 使用的协议（http/https）

  在某些云环境（如 Kubernetes、Heroku 和 Cloud Foundry）中，若入口或负载均衡器发送 X-Forwarded-Proto 请求头，此设置将被该头的值覆盖。

• SERVER_SECURE（默认：false）：当 SERVER_SCHEME 为 https 时设为 true

• SERVER_FORWARD_HEADERS_STRATEGY（默认：在指定云环境中为 NATIVE，其他为 NONE）：显式设为 NONE 可禁用 X-Forwarded-* 头优先级，使系统使用 SERVER_SCHEME 配置

JVM 配置（仅 Bitbucket Server 5.0+）

如需覆盖默认内存配置或传递额外 JVM 参数，可使用以下环境变量：

• JVM_MINIMUM_MEMORY（默认：512m）：JVM 最小堆大小
• JVM_MAXIMUM_MEMORY（默认：1024m）：JVM 最大堆大小
• JVM_SUPPORT_RECOMMENDED_ARGS（默认：NONE）：额外 JVM 参数，如自定义 Java 信任存储

应用模式设置（仅 Bitbucket Server 5.0+）

本镜像可作为智能镜像或数据中心集群节点运行。可通过以下属性指定运行模式：

• SEARCH_ENABLED（默认：true）：设为 false 可阻止容器内启动 OpenSearch，适用于外部运行 OpenSearch 的场景（如数据中心集群）。也可使用 ELASTICSEARCH_ENABLED（已弃用）设置此属性。
• APPLICATION_MODE（默认：default）：运行模式，设为 'mirror' 可启动为智能镜像，此时即使未设置 SEARCH_ENABLED=false 也会禁用 OpenSearch。

数据库配置

首次运行时可通过以下设置自动配置数据库：

• JDBC_DRIVER：JDBC 驱动类名
• JDBC_URL：数据库连接 URL
• JDBC_USER：数据库用户名
• JDBC_PASSWORD：数据库密码

注意：由于许可限制，Bitbucket 未包含 MySQL 或 Oracle JDBC 驱动。使用这些数据库时，需将驱动复制到容器并重启。例如，向名为 "bitbucket" 的容器复制 MySQL 驱动：

docker cp mysql-connector-java.x.y.z.jar bitbucket:/var/atlassian/application-data/bitbucket/lib
docker restart bitbucket

更多信息参见连接 Bitbucket Server 到外部数据库。

JDBC 密码加密

从 Bitbucket 8.13 开始，JDBC 密码可通过 AWS Secrets Manager 管理。例如，使用 PostgreSQL 数据库并通过 AWS Secrets Manager 管理密码的 Bitbucket 节点配置：

$> docker run \
    -e JDBC_DRIVER=org.postgresql.Driver \
    -e JDBC_USER=atlbitbucket \
    -e JDBC_PASSWORD="{\"region\":\"us-east-1\",\"secretId\":\"mysecret\",\"secretPointer\":\"password\"}" \
    -e JDBC_PASSWORD_DECRYPTER_CLASSNAME="com.atlassian.secrets.store.aws.AwsSecretsManagerStore" \
    -e JDBC_URL=jdbc:postgresql://my.database.host:5432/bitbucket \
    -v /data/bitbucket-shared:/var/atlassian/application-data/bitbucket/shared \
    --name="bitbucket" \
    -d -p 7990:7990 -p 7999:7999 \
    atlassian/bitbucket

其他设置

除上述设置外，bitbucket.properties 文件中的所有设置均可通过 Docker 环境变量提供。环境变量与属性的映射规则参见Spring Boot 文档。

例如，使用 PostgreSQL 数据库和外部 OpenSearch 实例的完整命令：

$> docker network create --driver bridge --subnet=172.18.0.0/16 myBitbucketNetwork
$> docker run --network=myBitbucketNetwork --ip=172.18.1.1 \
    -e SEARCH_ENABLED=false \
    -e JDBC_DRIVER=org.postgresql.Driver \
    -e JDBC_USER=atlbitbucket \
    -e JDBC_PASSWORD=MYPASSWORDSECRET \
    -e JDBC_URL=jdbc:postgresql://my.database.host:5432/bitbucket \
    -e PLUGIN_SEARCH_CONFIG_BASEURL=[***] \
    -v /data/bitbucket-shared:/var/atlassian/application-data/bitbucket/shared \
    --name="bitbucket" \
    -d -p 7990:7990 -p 7999:7999 \
    atlassian/bitbucket

集群设置

运行 Bitbucket DC 集群时，集群设置通过 HAZELCAST_* 环境变量指定，主要包括：

• HAZELCAST_PORT（对应 hazelcast.port）：Hazelcast 端口
• HAZELCAST_GROUP_NAME（对应 hazelcast.group.name）：集群组名称
• HAZELCAST_GROUP_PASSWORD（对应 hazelcast.group.password）：集群组密码

不同集群类型（如 AWS/Azure/多播/TCP）有各自的设置。更多信息参见Bitbucket Data Center 集群配置和配置属性。

注意：底层网络需配置为支持所选集群类型，具体配置取决于容器管理技术，超出本文档范围。

JMX 监控

设置 JMX_ENABLED=true 可启用 JMX 监控。更多设置和指标信息参见Bitbucket JMX 文档。

容器配置

• SET_PERMISSIONS（默认：true）：定义启动时是否设置主目录权限，设为 false 可禁用此行为

共享目录和用户 ID

默认情况下，Bitbucket 应用以用户 bitbucket 运行，UID 和 GID 均为 2003。因此，该 UID 必须对共享文件系统有写权限。如需使用不同 UID，可通过以下方式：

• 重新构建 Docker 镜像，指定不同 UID
• 在 Linux 下，使用用户命名空间重映射

升级

要升级到 Bitbucket Server 新版本，只需停止当前容器并启动基于新版本镜像的容器：

$> docker stop bitbucket
$> docker rm bitbucket
$> docker pull atlassian/bitbucket:<目标版本>
$> docker run ... (参见上文启动命令)

数据存储在主机的数据卷目录中，升级后仍可访问。

注意：确保不要使用 -v 选项意外删除 bitbucket 容器及其卷。

备份

评估环境中可使用内置数据库，其文件存储在 Bitbucket Server 主目录中，此时只需备份主机上用作卷的目录（如示例中的 /data/bitbucket）。

Bitbucket Server 备份客户端目前不支持 Docker 环境，但可使用Bitbucket Server DIY 备份方法（适用于使用外部数据库的情况）。

更多数据恢复和备份信息：[***]

关闭

Bitbucket 允许配置活动操作完成的宽限期（默认 30 秒）。执行 docker stop 时应使用 --time 标志考虑此宽限期。

此外，提供 /shutdown-wait.sh 脚本，可启动干净关闭并等待进程完成。这是有序关闭环境（如 Kubernetes 的 preStop 钩子）中的推荐方法。

版本控制

latest 标签对应仓库的最新版本，使用 atlassian/bitbucket:latest 或 atlassian/bitbucket 将获取最新镜像。

也可使用特定次要版本标签，如 atlassian/bitbucket:6，将安装最新的 6.x.x 版本。

支持的 JDK 版本

所有 Atlassian Docker 镜像现在仅支持 JDK11，基于官方 Eclipse Temurin OpenJDK Docker 镜像构建。

Docker 镜像遵循Atlassian 支持生命周期政策；不支持版本的产品镜像仍可获取，但不再接收更新或修复。

历史上曾生成其他版本镜像（如 JDK8、Alpine、JDK "slim" 版本），这些遗留镜像仍存在于 Docker Hub，但已弃用且不再更新。

如需其他版本，参见“构建自己的镜像”部分。

构建自己的镜像

1. 克隆 Atlassian 仓库：[***]
2. 修改或替换 config 目录下的 Jinja 模板（注意：文件必须有 .j2 扩展名，可选择不使用模板变量）
3. 构建新镜像，例如：docker build --tag my-bitbucket-image --build-arg BITBUCKET_VERSION=8.x.x .
4. （可选）推送到镜像仓库并部署

支持的架构

目前 Atlassian Docker 镜像为 linux/amd64 目标平台构建；暂未计划支持其他架构。但 Dockerfile 和支持工具已移除所有架构特定组件，因此可构建 Docker 支持的任何平台镜像。

在目标架构上构建

获取平台镜像的最简单方法是在目标机器上构建，参见上文“构建自己的镜像”。

注意：此方法已知在 Mac M1 和 AWS ARM64 机器上有效，但未经过广泛测试。

故障排查

本镜像包含内置脚本，协助执行常见 JVM 诊断任务。

线程转储

/opt/atlassian/support/thread-dumps.sh 可通过 docker exec 运行，轻松收集容器化应用的线程转储：

docker exec my_container /opt/atlassian/support/thread-dumps.sh

默认收集 10 次线程转储，间隔 5 秒。可使用 -c/--count 和 -i/--interval 覆盖默认值，例如收集 20 次，间隔 3 秒：

docker exec my_container /opt/atlassian/support/thread-dumps.sh --count 20 --interval 3

线程转储将写入 $APP_HOME/thread_dumps/<日期>。

注意：默认情况下，脚本还会捕获 'Thread-mode' 的 top 输出，可通过 -n/--no-top 禁用。

堆转储

/opt/atlassian/support/heap-dump.sh 可通过 docker exec 运行，收集应用堆转储：

docker exec my_container /opt/atlassian/support/heap-dump.sh

堆转储将写入 $APP_HOME/heap.bin。若文件已存在，使用 -f/--force 覆盖。

手动诊断

镜像包含 jcmd 工具，可通过在运行的容器中启动 bash shell 使用：

docker exec -it my_container /bin/bash

支持

产品支持请访问 [support.atlassian