Docker 构建

构建器以 Docker 镜像的形式交付。内容仓库通过运行它来生成静态 HTML，无需在本地安装 Node.js 或 Astro。

Dockerfile

docker/Dockerfile 基于 node:24-alpine 使用多步骤构建：

FROM node:24-alpine AS builder
WORKDIR /app

# Install deps (cached layer)
COPY package*.json ./
RUN npm ci

# Copy framework code
COPY . .

# Remove placeholder content
RUN rm -rf src/content/docs/*

COPY docker/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

分层策略

层	内容	为何单独缓存
1	`COPY package*.json` + `npm ci`	依赖变更不频繁；缓存此层可避免每次构建都重新下载
2	`COPY . .`	框架源代码
3	`rm -rf src/content/docs/*`	清除所有占位内容，确保只显示注入的内容
4	`COPY entrypoint.sh`	构建编排脚本

入口点

docker/entrypoint.sh 在每次容器启动时运行。它按以下顺序执行这些步骤：

步骤 1：更新依赖

npm install
npm update

确保主题包和所有依赖项都处于最新的兼容版本。

步骤 2：复制主题配置

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs
cp /app/node_modules/@f5-sales-demo/docs-theme/src/content.config.ts /app/src/content.config.ts

从主题包中复制 astro.config.mjs 和 content.config.ts。主题是 Astro 配置的唯一权威来源——有关主题系统设计请参阅架构。

步骤 3：注入内容

if [ -d "$CONTENT_DIR" ]; then
  cp -r "$CONTENT_DIR"/* /app/src/content/docs/
else
  echo "ERROR: No content found at $CONTENT_DIR"
  exit 1
fi

将挂载的内容复制到 Astro 的内容集合目录中。如果内容目录缺失，则输出错误并退出。

步骤 4：提取标题

if [ -z "$DOCS_TITLE" ] && [ -f /app/src/content/docs/index.mdx ]; then
  DOCS_TITLE=$(grep -m1 '^title:' /app/src/content/docs/index.mdx | sed 's/title: *["]*//;s/["]*$//')
  export DOCS_TITLE
fi

如果未通过环境变量设置 DOCS_TITLE，则从 index.mdx 的 title: frontmatter 字段中提取。

步骤 5：提取基础路径

if [ -z "$DOCS_BASE" ] && [ -n "$GITHUB_REPOSITORY" ]; then
  DOCS_BASE="/${GITHUB_REPOSITORY#*/}"
  export DOCS_BASE
fi

从 GitHub 仓库名称推导站点基础路径（例如，owner/my-docs 变为 /my-docs）。

步骤 6：构建

npm run build

运行 astro build，在 /app/dist/ 中生成静态输出。

步骤 7：复制输出

if [ -d "$OUTPUT_DIR" ]; then
  cp -r /app/dist/* "$OUTPUT_DIR"/
fi

将构建好的站点复制到输出挂载点。

环境变量

变量	默认值	描述
`CONTENT_DIR`	`/content/docs`	挂载的内容目录路径
`OUTPUT_DIR`	`/output`	构建后站点的复制目标路径
`DOCS_TITLE`	（从 index.mdx 提取）	传递给 Astro 配置的站点标题
`DOCS_DESCRIPTION`	（从 index.mdx 提取）	来自 frontmatter 的站点描述
`DOCS_BASE`	（从 `GITHUB_REPOSITORY` 推导）	站点的基础路径（例如 `/my-docs`）
`DOCS_SITE`	（从 `GITHUB_REPOSITORY_OWNER` 推导）	传递给 Astro 配置的站点 URL（例如 `https://<owner>.github.io`）
`GITHUB_REPOSITORY`	（由 GitHub Actions 设置）	用于推导 `DOCS_BASE` 的 `owner/repo` 字符串
`GENERATE_PDF`	`false`	构建后启用 PDF 生成
`PDF_FILENAME`	`docs`	生成的 PDF 的输出文件名
`LLMS_OPTIONAL_LINKS`	`[]`	用于 `llms.txt` Optional 部分的子站点 URL JSON 数组

本地使用

使用 Docker 在本地构建文档：

docker run --rm \
  -v "$(pwd)/docs:/content/docs" \
  -v "$(pwd)/output:/output" \
  ghcr.io/f5-sales-demo/docs-builder:latest

这会将本地的 docs/ 目录作为内容挂载，并将构建好的站点写入 output/。

对于希望使用实时开发服务器工作流的内容作者，请参阅内容作者本地预览。

开发者：本地开发服务器

在开发构建器本身（组件、插件、主题集成）时，您可以直接运行 Astro 的开发服务器而无需 Docker：

npm ci
cp node_modules/@f5-sales-demo/docs-theme/astro.config.mjs astro.config.mjs
cp node_modules/@f5-sales-demo/docs-theme/src/content.config.ts src/content.config.ts
# Copy some test content into the content collection
cp -r /path/to/test-content/* src/content/docs/
DOCS_TITLE="Dev Test" npx astro dev --host

打开 http://localhost:4321。热模块替换（HMR）支持组件和插件更改的即时更新。

镜像仓库

镜像发布到 GitHub Container Registry：

ghcr.io/f5-sales-demo/docs-builder

每次构建会推送两个标签：

标签	描述
`latest`	从 `main` 分支构建的最新版本
`<sha>`	完整的 Git 提交 SHA，用于可复现的构建

有关构建和发布镜像的工作流，请参阅 CI/CD 与治理。