feat(ui): multi-stage Docker frontend build (no host npm) (#3074)

* feat(ui): multi-stage Docker build without host npm

Build frontend assets inside the image with node:24-bookworm, then
copy into the existing digest-pinned nginx runtime so docker compose
and CI no longer require a host-side dist step.

* fix(ui): copy local xlsx package and raise Node heap in Docker build

npm ci needs packages/xlsx before install, and vite OOM'd under the
default Node heap during the multi-stage image build.

* fix(ui): native multi-arch frontend Docker build and layer cache

Keep Vite on BUILDPLATFORM so CI does not qemu-emulate Node, pin the
builder image, and move the commit ARG after npm ci so dependency
layers stay cacheable.

---------

Co-authored-by: wizardchen <wizardchen@tencent.com>
main
HUANG Cheng 2026-09-07 19:33:57 +08:00 committed by GitHub
parent 071a87d5f7
commit 6a55860431
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
14 changed files with 143 additions and 39 deletions

View File

@ -38,6 +38,13 @@ APK_MIRROR_ARG=mirrors.tencent.com
# WITH_ANYDOC=1
# docreader 镜像构建时 apt 镜像源(留空用默认源)。
# APT_MIRROR=
# 从源码构建 frontend 镜像时写入系统信息页的短 commit。make docker-build-frontend
# 与 start_all.sh --no-pull 会从 git 自动填充;直接 docker compose build 时请自行导出,否则显示 unknown。
# VITE_FRONTEND_COMMIT=
# 构建 frontend 镜像时的 npm registry(留空用默认源;国内可设 https://registry.npmmirror.com)。
# NPM_REGISTRY=
# Vite 构建 Node 堆上限(MB)。Docker Desktop 分配内存较小时可降到 2048。
# NODE_MAX_OLD_SPACE_SIZE=4096
# ========== A2. 运行时基础 ==========
# gin 运行模式:debug(开发,详细日志 + Swagger)/ release(生产,禁用 Swagger)。

View File

@ -11,7 +11,6 @@ concurrency:
cancel-in-progress: false
env:
NODE_VERSION: "24"
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
jobs:
@ -27,19 +26,6 @@ jobs:
eval "$(./scripts/get_version.sh env)"
echo "commit_id=$COMMIT_ID" >> $GITHUB_OUTPUT
- name: Set up Node.js
uses: actions/setup-node@v6
with:
node-version: ${{ env.NODE_VERSION }}
cache: npm
cache-dependency-path: frontend/package-lock.json
- name: Build frontend
env:
VITE_IS_DOCKER: true
VITE_FRONTEND_COMMIT: ${{ steps.version.outputs.commit_id }}
run: ./scripts/build_frontend_dist.sh
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
@ -62,6 +48,8 @@ jobs:
platforms: linux/amd64,linux/arm64
file: frontend/Dockerfile
context: ./frontend
build-args: |
VITE_FRONTEND_COMMIT=${{ steps.version.outputs.commit_id }}
labels: ${{ steps.meta.outputs.labels }}
tags: ${{ steps.meta.outputs.tags }}
cache-from: type=gha,scope=build-ui

View File

@ -53,3 +53,18 @@ jobs:
- name: Build
run: npm run build
docker-image:
name: Docker multi-stage image
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v6
- name: Build UI image
run: |
docker build \
-f frontend/Dockerfile \
--build-arg VITE_FRONTEND_COMMIT="${GITHUB_SHA::7}" \
-t weknora-ui:ci \
frontend/

View File

@ -129,10 +129,12 @@ docker-build-app:
docker-build-docreader:
docker build --platform $(PLATFORM) -f docker/Dockerfile.docreader -t wechatopenai/weknora-docreader:latest .
# Build frontend Docker image
# Build frontend Docker image (multi-stage: npm runs inside the builder stage)
docker-build-frontend:
./scripts/build_frontend_dist.sh
docker build --platform $(PLATFORM) -f frontend/Dockerfile -t wechatopenai/weknora-ui:latest frontend/
@eval $$(./scripts/get_version.sh env); \
docker build --platform $(PLATFORM) \
--build-arg VITE_FRONTEND_COMMIT="$$COMMIT_ID" \
-f frontend/Dockerfile -t wechatopenai/weknora-ui:latest frontend/
# Build all Docker images
docker-build-all: docker-build-app docker-build-docreader docker-build-frontend

View File

@ -1,9 +1,16 @@
services:
frontend:
image: wechatopenai/weknora-ui:${WEKNORA_VERSION:-latest}
# Requires frontend/dist — run ./scripts/build_frontend_dist.sh before --build
# Multi-stage Dockerfile builds dist inside the image (no host npm required).
# Optional: NPM_REGISTRY=https://registry.npmmirror.com docker compose build frontend
# VITE_FRONTEND_COMMIT: start_all.sh / make docker-build-frontend inject git;
# otherwise pass it explicitly or the system-info page shows "unknown".
build:
context: ./frontend
args:
VITE_FRONTEND_COMMIT: ${VITE_FRONTEND_COMMIT:-unknown}
NPM_REGISTRY: ${NPM_REGISTRY:-}
NODE_MAX_OLD_SPACE_SIZE: ${NODE_MAX_OLD_SPACE_SIZE:-4096}
container_name: WeKnora-frontend
ports:
- "${FRONTEND_PORT:-80}:80"

View File

@ -1,5 +1,19 @@
*
!dist
!nginx.conf
!nginx-api-proxy.conf
!docker-entrypoint.sh
# Keep build context lean; multi-stage Dockerfile needs sources, not dist.
node_modules
dist
dist-ssr
coverage
logs
*.log
.DS_Store
.vscode
.idea
*.local
*.tsbuildinfo
package.json.md5
*.md
.env
.env.*
.gitignore
.dockerignore
Dockerfile

View File

@ -1,6 +1,57 @@
# Production image. Build static assets on the host first:
# ./scripts/build_frontend_dist.sh
# Production image — two-stage build (no host-side npm required).
# Mirrors scripts/build_frontend_dist.sh:
# npm ci + VITE_IS_DOCKER=true + VITE_FRONTEND_COMMIT
#
# Dist is architecture-independent. The builder uses $BUILDPLATFORM so
# multi-arch CI (linux/amd64,linux/arm64) compiles Vite once on the runner
# instead of qemu-emulating Node, and both runtime images share the same dist.
#
# docker build --platform linux/amd64 \
# --build-arg VITE_FRONTEND_COMMIT=$(git rev-parse --short HEAD) \
# -t wechatopenai/weknora-ui:latest \
# frontend/
#
# Optional npm mirror (e.g. corporate registry):
# --build-arg NPM_REGISTRY=https://registry.npmmirror.com
#
# Docker Desktop with a small VM:
# --build-arg NODE_MAX_OLD_SPACE_SIZE=2048
# ---------------------------------------------------------------------------
# Stage 1: build static assets
# ---------------------------------------------------------------------------
# Pin by digest: compiled JS is shipped in the runtime image, so a floating
# node tag could change production assets. This index includes linux/amd64
# and linux/arm64 (Node 24 / Debian bookworm slim).
FROM --platform=$BUILDPLATFORM node:24-bookworm-slim@sha256:ba849c60be29959425b8734d57b8b4b7d56f98edd9504c9af091d5281095a71e AS builder
WORKDIR /frontend
ARG NPM_REGISTRY=
ARG NODE_MAX_OLD_SPACE_SIZE=4096
ENV VITE_IS_DOCKER=true
# Vite production builds of this SPA routinely exceed Node's default heap.
ENV NODE_OPTIONS="--max-old-space-size=${NODE_MAX_OLD_SPACE_SIZE}"
# package-lock references file:packages/xlsx-*.tgz — copy before npm ci.
COPY package.json package-lock.json ./
COPY packages ./packages
RUN if [ -n "$NPM_REGISTRY" ]; then \
npm ci --registry="$NPM_REGISTRY"; \
else \
npm ci; \
fi
COPY . .
# After npm ci so a new commit hash does not bust the dependency layer.
ARG VITE_FRONTEND_COMMIT=unknown
ENV VITE_FRONTEND_COMMIT=${VITE_FRONTEND_COMMIT}
RUN npm run build
# ---------------------------------------------------------------------------
# Stage 2: nginx runtime
# ---------------------------------------------------------------------------
# Base image pinned by digest for reproducibility. Do NOT switch back to the
# floating `nginx:stable-alpine` tag: it drifts with every stable release and a
# newer Alpine base (3.24+) fails to start on old hosts such as CentOS 7
@ -8,7 +59,7 @@
# nginx 1.30.3 / Alpine 3.23.5, the same base as the working v0.6.3 image.
FROM nginx:1.30.3-alpine@sha256:0d3b80406a13a767339fbe2f41406d6c7da727ab89cf8fae399e81f780f814d1
COPY dist /usr/share/nginx/html
COPY --from=builder /frontend/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/templates/default.conf.template

View File

@ -1,5 +1,6 @@
#!/usr/bin/env bash
# Build frontend static assets for Docker / release packaging.
# Build frontend static assets for Lite / desktop packaging (host-side).
# Docker UI images use the multi-stage frontend/Dockerfile instead — no host npm.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

View File

@ -183,7 +183,7 @@ build_docreader_image() {
fi
}
# 构建前端镜像
# 构建前端镜像(多阶段:npm 在 builder 内执行,无需宿主机预构建 dist)
build_frontend_image() {
log_info "构建前端镜像 (weknora-ui)..."
@ -192,11 +192,11 @@ build_frontend_image() {
# 获取版本信息(用于注入前端 commit hash)
get_version_info
log_info "构建前端静态资源..."
VITE_IS_DOCKER=true VITE_FRONTEND_COMMIT="$COMMIT_ID" "$SCRIPT_DIR/build_frontend_dist.sh"
docker build \
--platform $PLATFORM \
--build-arg VITE_FRONTEND_COMMIT="$COMMIT_ID" \
${NPM_REGISTRY:+--build-arg NPM_REGISTRY="$NPM_REGISTRY"} \
${NODE_MAX_OLD_SPACE_SIZE:+--build-arg NODE_MAX_OLD_SPACE_SIZE="$NODE_MAX_OLD_SPACE_SIZE"} \
-f frontend/Dockerfile \
-t wechatopenai/weknora-ui:latest \
frontend/

View File

@ -58,6 +58,20 @@ log_success() {
printf "%b\n" "${GREEN}[SUCCESS]${NC} $1"
}
# Inject git short hash into the frontend image when composing from source.
# docker-compose.yml interpolates VITE_FRONTEND_COMMIT; the build context is
# frontend/ (no .git), so Vite cannot discover the commit on its own.
export_frontend_build_args() {
if [ -n "${VITE_FRONTEND_COMMIT:-}" ]; then
export VITE_FRONTEND_COMMIT
return 0
fi
# shellcheck source=/dev/null
eval "$("$PROJECT_ROOT/scripts/get_version.sh" env)"
export VITE_FRONTEND_COMMIT="${COMMIT_ID:-unknown}"
log_info "VITE_FRONTEND_COMMIT=${VITE_FRONTEND_COMMIT}"
}
# 选择可用的 Docker Compose 命令(优先 docker compose,其次 docker-compose)
DOCKER_COMPOSE_BIN=""
DOCKER_COMPOSE_SUBCMD=""
@ -355,8 +369,10 @@ start_docker() {
check_platform
# 进入项目根目录再执行docker-compose命令
# 进入项目根目录再执行docker-compose命令
cd "$PROJECT_ROOT"
export_frontend_build_args
# 启动基本服务
log_info "启动核心服务容器..."
@ -499,6 +515,8 @@ restart_container() {
# 进入项目根目录再执行docker-compose命令
cd "$PROJECT_ROOT"
export_frontend_build_args
# 检查容器是否存在
if ! "$DOCKER_COMPOSE_BIN" $DOCKER_COMPOSE_SUBCMD ps --services | grep -q "^$container_name$"; then

View File

@ -131,7 +131,7 @@ make dev-logs / dev-status / dev-stop / dev-restart
| `docker/Dockerfile.docreader` | `wechatopenai/weknora-docreader` | Python 3.10 + uv 依赖锁定;生成 protobuf;运行层安装 LibreOffice、OpenJDK 17、antiword、Playwright(webkit)与 `grpc_health_probe`。轻量版不含 PaddleOCR。`EXPOSE 50051`。支持 `APT_MIRROR` 构建参数 |
| `docker/Dockerfile.odl-hybrid` | `weknora-odl-hybrid:local` | 安装 `opendataloader-pdf[hybrid]`(Docling),监听 5002,默认 `--no-ocr`;仅本地构建不发布 |
| `docker/Dockerfile.sandbox` | `wechatopenai/weknora-sandbox` | Python 3.11-slim + Node 20 + jq,非 root 用户 `user`(UID 1000),Agent Skills 的会话沙箱镜像 |
| `frontend/Dockerfile` | `wechatopenai/weknora-ui` | 需先在宿主机执行 `./scripts/build_frontend_dist.sh` 产出 `dist/`;基底为按 digest 固定的 `nginx:1.30.3-alpine`(兼容 CentOS 7 旧内核) |
| `frontend/Dockerfile` | `wechatopenai/weknora-ui` | 两阶段:digest 锁定的 `node:24-bookworm-slim`(`$BUILDPLATFORM`,避免多架构 CI 用 QEMU 跑 Vite)内 `npm ci` + `npm run build`(`VITE_IS_DOCKER` / `VITE_FRONTEND_COMMIT`),可选 `NPM_REGISTRY` / `NODE_MAX_OLD_SPACE_SIZE`;运行层为按 digest 固定的 `nginx:1.30.3-alpine`(兼容 CentOS 7 旧内核)。无需宿主机预构建 `dist/` |
从源码构建全部镜像:
@ -168,7 +168,7 @@ make docker-build-frontend
| `scripts/dev.sh` | 开发环境编排(见上文),子命令 `start/stop/restart/logs/status/app/frontend` |
| `scripts/check-env.sh` | 校验 `.env` 必填变量(DB_*、STORAGE_TYPE、REDIS_ADDR、OLLAMA_BASE_URL 等)与 Go/npm/Docker/Air 工具链 |
| `scripts/build_images.sh` | 构建镜像并注入版本(git tag / commit / build time),支持跨架构 |
| `scripts/build_frontend_dist.sh` | 构建前端静态产物 `frontend/dist`(frontend 镜像的前置步骤) |
| `scripts/build_frontend_dist.sh` | 宿主机构建前端静态产物 `frontend/dist`(Lite / 桌面打包等非 Docker 场景;UI 镜像改由 Dockerfile 多阶段构建) |
| `scripts/migrate.sh` | golang-migrate 封装 |
| `scripts/docker-entrypoint.sh` | app 容器入口(属主修复 + 内置 Skills 合并 + docker.sock GID 补组 + gosu 降权) |
| `scripts/package-lite.sh` / `package-mac-app.sh` | Lite tarball / macOS .app 打包 |

View File

@ -192,7 +192,7 @@ sequenceDiagram
| `helm/` | Kubernetes Helm Chart(Chart.yaml / values.yaml / templates/) |
| `examples/` | API 使用示例代码;`examples/skills/` 为 Agent Skill 包示例 |
| `dataset/` | 评估用 QA 数据集及生成脚本 |
| `scripts/` | 构建/启动/迁移辅助脚本(如 `start_all.sh`、`build_frontend_dist.sh`) |
| `scripts/` | 构建/启动/迁移辅助脚本(如 `start_all.sh`;`build_frontend_dist.sh` 供 Lite / 桌面打包,UI 镜像由 `frontend/Dockerfile` 多阶段构建) |
| `tests/`、`testdata/` | 集成测试与测试数据 |
| `Formula/` | Homebrew 安装配方(macOS) |
| `misc/` | 杂项(如 `dex-config.yaml` OIDC 测试配置) |

View File

@ -294,8 +294,9 @@ RAG 流水线的可视化进度(`views/chat/components/RagPipelineProgress.vue
`frontend/Dockerfile`:
- 基础镜像固定为 digest 锁定的 `nginx:1.30.3-alpine`(注释明确禁止改回浮动 tag——更新的 Alpine 3.24+ 在 CentOS 7 旧内核上无法启动,曾导致 v0.7.0 故障);
- 静态产物需先在宿主机构建(`./scripts/build_frontend_dist.sh`),镜像只 `COPY dist`;
- 两阶段构建:digest 锁定的 `node:24-bookworm-slim` 以 `$BUILDPLATFORM` 执行 `npm ci` + `npm run build`(`VITE_IS_DOCKER=true`,`VITE_FRONTEND_COMMIT` 可经 build-arg 注入且须放在 `npm ci` 之后以免打断依赖层缓存;可选 `NPM_REGISTRY` / `NODE_MAX_OLD_SPACE_SIZE`),再拷贝到运行层;
- 运行层基础镜像固定为 digest 锁定的 `nginx:1.30.3-alpine`(注释明确禁止改回浮动 tag——更新的 Alpine 3.24+ 在 CentOS 7 旧内核上无法启动,曾导致 v0.7.0 故障);
- 无需在宿主机预构建 `dist/`(`scripts/build_frontend_dist.sh` 仍供 Lite / 桌面打包使用);
- `nginx.conf` 作为模板放入 `/etc/nginx/templates/default.conf.template`,暴露 80 端口,入口为 `docker-entrypoint.sh`。
`frontend/docker-entrypoint.sh`(运行时配置注入):

View File

@ -129,7 +129,7 @@ make package-mac-app # 打 macOS .app(scripts/package-mac-app.sh)
| --- | --- |
| `docker-build-app` | 构建 `wechatopenai/weknora-app`(`docker/Dockerfile.app`,注入 `scripts/get_version.sh` 的版本信息) |
| `docker-build-docreader` | 构建 `wechatopenai/weknora-docreader`(`docker/Dockerfile.docreader`) |
| `docker-build-frontend` | 先 `scripts/build_frontend_dist.sh`,再构建 `wechatopenai/weknora-ui` |
| `docker-build-frontend` | 多阶段构建 `wechatopenai/weknora-ui`(builder 内 `npm ci` + `npm run build`,无需宿主机预构建 dist) |
| `docker-build-all` | 以上三个镜像 |
| `docker-run` | 确保 `.env` 存在(缺失时从 `.env.example` 复制或 touch)后 `docker-compose up` |
| `docker-stop` / `docker-restart` | `docker-compose down` / `stop -t 60` + `up` |
@ -243,7 +243,7 @@ make fmt && make lint && make test
| 文件 | 触发路径 | 作用 |
| --- | --- | --- |
| `workflows/app.yml` | 根模块 Go 代码、`go.mod`、`config/`、`migrations/`、`scripts/`、`docker/Dockerfile.app` | 主模块检查:gofmt 格式校验(只针对 PR 内的提交)、`go vet`、`go test`、`go build ./cmd/server` |
| `workflows/frontend.yml` | `frontend/`、`scripts/build_frontend_dist.sh` | Node 24:`npm test` + `npm run type-check` + `npm run build` |
| `workflows/frontend.yml` | `frontend/`、`scripts/build_frontend_dist.sh` | Node 24:`npm test` + `npm run type-check` + `npm run build`;另构建 `frontend/Dockerfile` 多阶段镜像(不推送) |
| `workflows/docreader.yml` | `docreader/`、`testdata/`、`packages/`、相关 Dockerfile | uv 装依赖 → `compileall` → `unittest discover docreader/tests`;再拉起 docreader gRPC 服务跑 `go test ./docreader/client ./docreader/proto` |
| `workflows/mcp-server.yml` | `mcp-server/` | Python 3.10-3.13 矩阵测试;合入 main 后按 `pyproject.toml` 里的版本号用 PyPI Trusted Publishing 自动发布(版本已存在则跳过上传,不依赖打 tag) |
| `workflows/cli.yml` | `cli/` | ubuntu/macos/windows 三平台矩阵,Go 1.26,`go build` + `go test -race -coverprofile` + `go vet` + skill wire 词表检查 |