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
parent
071a87d5f7
commit
6a55860431
|
|
@ -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)。
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
8
Makefile
8
Makefile
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)"
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 打包 |
|
||||
|
|
|
|||
|
|
@ -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 测试配置) |
|
||||
|
|
|
|||
|
|
@ -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`(运行时配置注入):
|
||||
|
|
|
|||
|
|
@ -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 词表检查 |
|
||||
|
|
|
|||
Loading…
Reference in New Issue