如何在Docker容器中搭建OpenShift文档（openshift-docs）环境？

我明白你在Docker容器里部署openshift-docs预览站点时遇到了麻烦——本地用asciibinder跑文档工作站没问题，但按自己的思路打包成Nginx镜像后达不到预期效果。咱们一步步拆解问题，再给你一个可靠的实现方案：

先排查你原思路里的潜在问题 #

你的核心思路是对的，但可能踩了这几个坑：

• 构建环境不一致：本地生成的_preview目录依赖你本地的asciibinder版本、系统环境，直接复制到容器里可能存在路径、资源引用的兼容性问题
• 文件权限缺失：Nginx容器默认以nginx用户运行，如果你直接复制本地文件，可能容器没有读取权限
• Nginx路由配置不足：openshift-docs的预览页面可能有前端路由（比如不带.html的链接），默认Nginx配置无法正确解析这类路由

可靠的Docker化实现方案（多阶段构建） #

用多阶段构建可以彻底隔离文档构建环境和Nginx运行环境，避免依赖问题，步骤如下：

1. 编写Dockerfile #

创建一个Dockerfile文件，内容如下：

# 第一阶段：在专用环境构建文档预览目录
FROM ruby:2.7-slim AS builder

# 安装asciibinder及依赖工具
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    git \
    && gem install asciibinder \
    && rm -rf /var/lib/apt/lists/*

# 克隆openshift-docs仓库（如果是本地已有仓库，替换成COPY . /docs）
WORKDIR /docs
RUN git clone https://github.com/openshift/openshift-docs.git .

# 生成预览目录
RUN asciibinder build --preview

# 第二阶段：构建Nginx运行镜像
FROM nginx:alpine

# 复制构建好的预览文件到Nginx默认静态目录
COPY --from=builder /docs/_preview /usr/share/nginx/html

# 修复文件权限，确保Nginx能读取
RUN chown -R nginx:nginx /usr/share/nginx/html

# 可选：替换Nginx配置，支持文档的前端路由
COPY nginx.conf /etc/nginx/conf.d/default.conf

2. 编写Nginx路由配置（可选但推荐） #

创建nginx.conf文件，解决无.html后缀的路由访问问题：

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html index.htm;

    # 处理文档路由，找不到文件时返回主页（适配前端路由）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源设置缓存，提升访问速度
    location ~* \.(css|js|png|jpg|svg|ico)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. 构建并运行容器 #

执行以下命令完成镜像构建和容器启动：

# 构建镜像，命名为openshift-docs-preview
docker build -t openshift-docs-preview .

# 启动容器，把本地8080端口映射到容器80端口
docker run -d -p 8080:80 openshift-docs-preview

4. 调试技巧 #

如果还是无法正常访问，试试这几步排查：

• 查看容器日志：docker logs <容器ID>，看有没有权限错误、404错误
• 直接挂载本地_preview目录测试Nginx：docker run -d -p 8080:80 -v $(pwd)/_preview:/usr/share/nginx/html nginx:alpine，如果这样能访问，说明问题出在镜像构建的复制步骤
• 进入容器检查文件：docker exec -it <容器ID> /bin/sh，查看/usr/share/nginx/html下的文件是否完整

内容的提问来源于stack exchange，提问作者shengbang he