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 commit SHA，用於可重現的建置

請參閱 CI/CD 與治理了解建置和發布映像檔的工作流程。