Backstage Techdocs无法渲染文档页面，卡在发布步骤3

问题详情 #

Backstage Techdocs无法渲染文档页面，卡在**Step 3 of 3: Publishing docs for entity component...**步骤，仅输出日志：

info: Step 3 of 3: Publishing docs for entity component:default/ssr-demo-1 {"timestamp":"2023-08-11T03:39:51.346Z"}

环境配置 #

• 基于官方多阶段构建Dockerfile打包镜像，因Docker-in-Docker问题，将Techdocs的generator.runIn设为local，并手动安装mkdocs-techdocs-core==1.1.7
• 当前Techdocs配置：

techdocs:
  builder: 'local' # Alternatives - 'external'
  # generator:
  #   runIn: 'docker' # Alternatives - 'local'
  #   dockerImage: docker.io/pointmekin/kroki-server:0.0.1 # Docker image for the kroki server
  #   pullImage: true
  generator:
    runIn: 'local'
  publisher:
    type: 'local' 

• Dockerfile中mkdocs安装片段：

...
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install mkdocs-techdocs-core==1.1.7
...

解决步骤 #

1. 修复mkdocs安装权限问题 #

镜像以node用户运行，但默认pip3 install会将包安装到root权限的系统目录，导致node用户无法访问。修改Dockerfile中的安装命令，指定安装到node用户的个人目录：

# 替换原有mkdocs安装命令
RUN pip3 install --user mkdocs-techdocs-core==1.1.7
# 添加PATH环境变量，让node用户能找到mkdocs命令
ENV PATH="/home/node/.local/bin:${PATH}"

注意：PATH配置要放在切换到node用户前后，确保容器启动时生效。

2. 确保Local Publisher存储目录权限 #

Local Publisher默认使用techdocs-cache目录存储文档，需要保证node用户对该目录有读写权限，在Dockerfile的Stage3中添加：

RUN mkdir -p /app/techdocs-cache && chown -R node:node /app/techdocs-cache

也可以在app-config.yaml中显式指定路径：

techdocs:
  publisher:
    type: 'local'
    local:
      path: './techdocs-cache'

3. 匹配mkdocs-techdocs-core与Backstage版本 #

mkdocs-techdocs-core版本需与Backstage版本兼容，1.1.7版本较旧，建议根据你当前Backstage版本安装对应兼容包（比如Backstage 1.15+可安装mkdocs-techdocs-core==1.5.0）。

4. 开启调试日志定位卡点 #

修改app-config.yaml提升日志级别，获取更详细的执行细节：

app:
  logger:
    level: debug

启动后查看日志，确认Step3中具体卡在文件复制、索引更新还是其他子步骤。

5. 验证镜像内工具可用性 #

启动容器后进入内部，执行以下命令验证mkdocs是否正常：

mkdocs --version
# 如果安装了techdocs-cli也可以检查
techdocs-cli --version

确保命令能正常执行且版本匹配预期。

内容的提问来源于stack exchange，提问作者Dhanabordee Mekintharanggur