atlassian/bitbucket-server

!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 模式下运行时，必须挂载共享文件系统。

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

bash
# 创建命名卷
$> 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

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

bash
$> 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 http://$(docker-machine 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 驱动：

bash
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 节点配置：

bash
$> 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 实例的完整命令：

bash
$> 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=http://my.opensearch.host \
    -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 新版本，只需停止当前容器并启动基于新版本镜像的容器：

bash
$> 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，基于https://hub.docker.com/_/eclipse-temurin%E6%9E%84%E5%BB%BA%E3%80%82

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 运行，轻松收集容器化应用的线程转储：

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

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

bash
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 运行，收集应用堆转储：

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

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

手动诊断

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

bash
docker exec -it my_container /bin/bash

支持

产品支持请访问 [support.atlassian