2025实战：Backstage容器化部署从零到精通

【免费下载链接】backstage Backstage is an open platform for building developer portals 项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

Backstage是一个开源的开发者门户平台，能帮助团队集中管理服务、文档和工具。本文将带你从零开始，掌握Backstage的容器化部署技术，通过Docker和Docker Compose实现快速、可靠的部署流程。

📦 为什么选择容器化部署Backstage？

容器化部署为Backstage带来了环境一致性、隔离性和可移植性。通过Docker容器，你可以确保开发、测试和生产环境的一致性，避免"在我电脑上能运行"的问题。同时，容器化部署简化了扩展和维护流程，让Backstage的部署和升级变得更加高效。

图：Backstage容器化部署架构示意图，展示了前端容器、后端容器和服务容器的关系

📋 部署前的准备工作

在开始容器化部署前，请确保完成以下准备工作：

1. 按照Getting Started指南创建Backstage应用
2. 设置认证提供程序，推荐参考Authentication指南
3. 准备Postgres数据库，可参考Database指南

⚠️ 警告：不要使用默认的Guest认证提供程序，它不适用于容器化环境。

🔧 快速启动依赖服务

项目根目录下提供了docker-compose.deps.yml文件，可快速启动Postgres、Redis和OpenSearch等依赖服务：

# docker-compose.deps.yml 内容摘要
services:
  psql:
    image: postgres:17.7
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - '5432:5432'
  
  redis:
    image: redis:8.2.1-alpine
    ports:
      - '6379:6379'
  
  opensearch:
    image: opensearchproject/opensearch:2.19.4
    environment:
      plugins.security.disabled: true
      discovery.type: single-node
    ports:
      - '9200:9200'

启动命令：

docker compose -f docker-compose.deps.yml up -d

🚀 两种构建方式详解

1. 主机构建（推荐）

主机构建是推荐的方式，大部分构建过程在Docker外部完成，速度更快且缓存更高效。

构建步骤：

# 安装依赖
yarn install --immutable

# 生成类型定义
yarn tsc

# 构建后端包
yarn build:backend

构建Docker镜像：

项目已包含Dockerfile在packages/backend/Dockerfile，使用以下命令构建：

docker image build . -f packages/backend/Dockerfile --tag backstage

运行容器：

docker run -it -p 7007:7007 backstage

2. 多阶段构建

如果你的环境不支持Docker in Docker，可使用多阶段构建，整个构建过程在Docker内部完成：

# 多阶段构建Dockerfile示例（位于项目根目录）
# Stage 1 - 创建依赖安装层
FROM node:24-trixie-slim AS packages
# ...省略中间步骤...

# Stage 2 - 安装依赖并构建包
FROM node:24-trixie-slim AS build
# ...省略中间步骤...

# Stage 3 - 构建最终镜像
FROM node:24-trixie-slim
# ...省略中间步骤...

构建命令：

docker image build -t backstage .

⚙️ 配置文件说明

Backstage使用YAML配置文件管理设置，主要配置文件包括：

• app-config.yaml: 基础配置
• app-config.production.yaml: 生产环境配置
• app-config.docker.yaml: Docker特定配置

部署时可通过--config参数指定多个配置文件：

node packages/backend --config app-config.yaml --config app-config.production.yaml

🐛 常见问题解决

构建失败？试试这些技巧：

1. 使用--progress=plain获取详细构建日志：

   docker image build . -f packages/backend/Dockerfile --tag backstage --progress=plain
   

2. 清除缓存重新构建：

   docker image build . -f packages/backend/Dockerfile --tag backstage --no-cache
   

3. 权限问题？确保BuildKit已启用：

   DOCKER_BUILDKIT=1 docker image build ...
   

社区贡献的Dockerfile

除了官方提供的Dockerfile，社区还贡献了其他选择：

• 最小化安全镜像：位于contrib/docker/minimal-hardened-image，使用wolfi-base镜像减少漏洞

📚 进一步学习资源

• 官方部署文档：docs/deployment/docker.md
• Kubernetes部署指南：docs/deployment/k8s.md
• Docker Compose配置：docker-compose.deps.yml

通过本文的指南，你已经掌握了Backstage容器化部署的核心技术。无论是开发环境还是生产环境，容器化部署都能为你提供一致、高效的部署体验。开始你的Backstage容器化之旅吧！

【免费下载链接】backstage Backstage is an open platform for building developer portals 项目地址: https://gitcode.com/GitHub_Trending/ba/backstage