Docker-Compose部署Sphinx文档网站遇报错及复制问题求助

核心问题 #

1. Dockerfile指令顺序错误：COPY指令放在CMD之后，Docker镜像构建阶段不会执行该COPY操作，导致镜像内缺少/etc/Sphinx/source目录。
2. COPY路径错误：Dockerfile位于.docker/目录下，使用/doc/作为源路径是绝对路径，构建上下文无法识别，需改用相对路径../doc/。
3. 服务器部署配置缺失：服务器的docker-compose.yml既没有挂载本地doc目录，也未使用包含文档源的镜像，导致容器内无文档文件。

修复步骤 #

1. 修正Dockerfile #

调整指令顺序，将COPY移至CMD之前，并修正源路径：

FROM alpine:latest
WORKDIR /etc/
RUN mkdir -p /etc/Sphinx/build

RUN apk add --no-cache python3 py3-pip make git
RUN pip install git+https://github.com/sphinx-doc/sphinx && \
    pip install sphinx-autobuild

# 先复制文档源到镜像内，再设置启动命令
COPY ../doc/ /etc/Sphinx/source
CMD sphinx-autobuild -b html --host 0.0.0.0 --port 80 /etc/Sphinx/source /etc/Sphinx/build

2. 重新构建并推送镜像 #

在项目根目录执行以下命令，更新镜像并推送到仓库：

docker-compose build docs
docker push registry.digitalocean.com/my_username/docs

3. 服务器部署方案（二选一） #

方案A：使用包含文档的镜像（无需挂载目录）

保持服务器的docker-compose.yml不变，拉取最新镜像后重启服务：

docker-compose pull docs
docker-compose up -d

方案B：挂载服务器本地doc目录（适用于实时更新文档场景）

修改服务器的docker-compose.yml，添加volume挂载：

version: "3.0"
services:
  docs:
    image: registry.digitalocean.com/my_username/docs
    restart: unless-stopped
    volumes:
      - ./doc:/etc/Sphinx/source
    ports:
      - 8100:80

执行更新命令：

docker-compose up -d

额外说明 #

• Dockerfile指令按从上到下顺序执行，CMD是容器启动时才触发的命令，构建镜像阶段不会处理，因此COPY必须放在CMD之前才能将文件复制到镜像内。
• 镜像构建时的上下文目录是执行docker build时指定的目录（此处为.docker/），引用上下文外的文件需要使用相对路径（如../doc/），绝对路径会导致构建失败。

内容的提问来源于stack exchange，提问作者Hayrettin Basaraner