camilesing · camilesing · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,9 +2,9 @@
 
 > 安全弱点上报见 SECURITY.md；内部评审细节不入库。
 
-Maven 多模块，BSD-3-Clause。本机构建与 CI 统一 JDK 8（temurin/zulu 均可），产物即成 Java 8 字节码（无需本机安装 JDK 25）；CI（temurin 8）只跑 common/template/core/executor/gateway/manager 六模块的测试。
+Maven 多模块，BSD-3-Clause。本机构建与 CI 统一 JDK 8（temurin/zulu 均可），产物即成 Java 8 字节码（无需本机安装 JDK 25）；宿主机扩展构建（build-extension.sh）JDK 8 优先，无 8 时允许 8 以上（编译目标钉在 1.8，产物仍为 Java 8 字节码）。CI（temurin 8）只跑 common/template/core/executor/gateway/manager 六模块的测试。
 - lombok 1.18.46、groovy 4.0.33（org.apache.groovy）为钉版勿回退（JDK 8 与 25 下均验证可用）；注解处理器依赖必须走 `annotationProcessorPaths`。
-- 三服务经 Eureka 互联：manager（8090，Liquibase 唯一迁移执行方）、executor（8092）、gateway（8091 唯一对外入口）。前端 datapoly-manager-ui 非 Maven：manager resources 下的 `index.html` 与 `static/` 为构建产物 **不入库**（已被 .gitignore 排除，勿提交/勿 git add -f），打包前由根目录 `build-ui.sh`（node:23-alpine 容器，本机无需 Node）生成——`build.sh` 与 `docker-maven-build.sh` 已在它之前前置 `build-extension.sh`（宿主扩展装配，环境变量门控，未配置时无操作）及该 UI 步骤；纯 `mvn package` 的 jar 不含 UI。`build-ui.sh debug` 产出 devtools 可用的调试构建（`DATAPOLY_UI_ENV=debug`，NODE_ENV=development），仅限本机联调、勿随发行版发布；`build.sh`/`docker-maven-build.sh` 会透传首参给 build-ui.sh。
+- 三服务经 Eureka 互联：manager（8090，Liquibase 唯一迁移执行方）、executor（8092）、gateway（8091 唯一对外入口）。前端 datapoly-manager-ui 非 Maven：manager resources 下的 `index.html` 与 `static/` 为构建产物 **不入库**（已被 .gitignore 排除，勿提交/勿 git add -f），打包前由根目录 `build-ui.sh`（node:23-alpine 容器，本机无需 Node）生成——`build.sh` 与 `docker-maven-build.sh` 已在它之前前置 `build-extension.sh`（宿主扩展装配：配置 `DATAPOLY_EXTENSION_GIT_URL` 或 `datapoly-extension` 目录存在即构建，否则无操作）及该 UI 步骤；纯 `mvn package` 的 jar 不含 UI。`build-ui.sh debug` 产出 devtools 可用的调试构建（`DATAPOLY_UI_ENV=debug`，NODE_ENV=development），仅限本机联调、勿随发行版发布；`build.sh`/`docker-maven-build.sh` 会透传首参给 build-ui.sh。
 - 许可头：新改文件只写 BSD 许可声明行，勿写个人 Copyright 头；vendored 文件（如 io.modelcontextprotocol.*）保留原版权声明。
 
 ## 一、网络分段（必须遵守）
@@ -30,5 +30,5 @@ Groovy 沙箱默认启用但不是 JVM 隔离：勿把脚本编写权开放给
 - 新增 JDBC 代码资源必须 try-with-resources；firewall 规则行被删时网关按"全拒绝"处理（fail-closed，属预期）。
 - DataTask 投递 Sink 仓库内置零实现，外部以 Spring Bean / `META-INF/services` 注册（SPI `com.cs.common.datatask.DataTaskSink`）；宿主可自行维护本地扩展：在顶层 `datapoly-extension/`（已被 .gitignore 排除，独立 git 仓库）下用 `backend/` 放 Maven 扩展模块（依赖钉版在模块自身 pom、不进根 reactor，由入库脚本 build-extension.sh 在宿主机 JDK 8 构建后投放 lib-extra/，随发行版装配进各服务 classpath）、`front/` 放扩展 UI；API 扩展点 `ApiAssignmentPostProcessor` 注册方式相同、须同步执行且保持轻量。详见 docs/*/data-task.md。
 - 默认前端扩展目录 `datapoly-extension/front`（同被 .gitignore 排除）经 datapoly-manager-ui 编译期装配：webpack `@extension` 别名自动探测该目录 `src/index.js`（见 build/webpack.base.conf.js）、`src/extension-stub` 为缺省回退、扩展路由与 i18n 词条在 manager-ui 入口深合并——这四处钩子文件（build/webpack.base.conf.js、src/extension-stub、src/router、src/main.js）勿移除或改名；目录不存在时 CI 与普通构建不受影响。front 自带 `package.json` 可直接启动（`npm run dev`，复用宿主 webpack 链，前置为宿主 node_modules 已安装、Node 23——dev server 与生产构建均已实测）。
-- 宿主扩展 jar 经根目录 `lib-extra/` 投放点进入发行版 `lib/common/`（`package.xml` 打包该目录 `*.jar`；目录只占位入库，jar 永不入库）。扩展为独立 git 仓库（内部 GitLab，front+backend 一体）：`build-extension.sh` 按环境变量 `DATAPOLY_EXTENSION_GIT_URL`（真实地址不入库，CI 注入）+ `DATAPOLY_EXTENSION_GIT_REF`（默认 master）浅克隆到 `datapoly-extension/`（仍被 .gitignore 排除），目录已存在则按本地工作区构建、`DATAPOLY_EXTENSION_FORCE_SYNC=1` 强制覆盖本地改动；`build.sh`/`docker-maven-build.sh` 会先调用该脚本，未配置且目录不存在时无操作（纯开源构建零影响）。本地环境变量注入（env.sh）与防误提交钩子集中在被忽略的 `dev-local/`。
+- 宿主扩展 jar 经根目录 `lib-extra/` 投放点进入发行版 `lib/common/`（`package.xml` 打包该目录 `*.jar`；目录只占位入库，jar 永不入库）。扩展为独立 git 仓库（内部 GitLab，front+backend 一体）：`build-extension.sh` 按环境变量 `DATAPOLY_EXTENSION_GIT_URL`（真实地址不入库，CI 注入）+ `DATAPOLY_EXTENSION_GIT_REF`（默认 master）浅克隆到 `datapoly-extension/`（仍被 .gitignore 排除），目录已存在则按本地工作区构建（宿主机 JDK 8 优先、无 8 时 8 以上可用）、`DATAPOLY_EXTENSION_FORCE_SYNC=1` 强制覆盖本地改动；`build.sh`/`docker-maven-build.sh` 会先调用该脚本，未配置且目录不存在时无操作（纯开源构建零影响）。本地环境变量注入（env.sh）与防误提交钩子集中在被忽略的 `dev-local/`。
 - 多 executor 下一次性 token 每节点各可用一次（有查库兜底，已知限制）。
diff --git a/Dockerfile b/Dockerfile
@@ -26,7 +26,7 @@ WORKDIR /opt/app
 # 仓库根下 datapoly-extension/front/src,缺省回退 stub;仅生产构建,debug 变体仍走 build-ui.sh
 COPY . /opt/app
 WORKDIR /opt/app/datapoly-manager-ui
-RUN npm config set registry https://registry.npmmirror.com \
+RUN npm config set registry http://mirrors.cloud.tencent.com/npm/ \
  && npm install --no-audit --no-fund --no-package-lock --legacy-peer-deps \
  && npm run build
 

diff --git a/build-docker/install/docker_install.sh b/build-docker/install/docker_install.sh
@@ -8,9 +8,9 @@ mkdir -p /etc/docker/
 cat > /etc/docker/daemon.json <<EOF
 {
     "registry-mirrors":[
-        "https://docker.mirrors.ustc.edu.cn",
-        "http://hub-mirror.c.163.com",
-        "https://mirror.ccs.tencentyun.com"
+        "https://docker.m.daocloud.io",
+        "https://docker.1ms.run",
+        "https://docker.xuanyuan.me"
     ],
     "insecure-registries": ["127.0.0.1/8"],
     "max-concurrent-downloads":10,

diff --git a/build-docker/install/up.sh b/build-docker/install/up.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+# Use of this source code is governed by a BSD-style license
+
+# compose 一键部署的内网友好入口：先经国内镜像加速站预取 docker-compose.yml 引用的
+# 全部运行期镜像（mysql:5.7 与 camilesing/datapoly-*，镜像路径与 compose 保持原样，
+# 由 ../../docker-prefetch-images.sh 拉取并 tag 规范名；幂等、已有则跳过），再执行
+# docker compose up。公司内网直连 Docker Hub 超时（例如 docker_install.sh 提供的
+# 旧镜像源已停服）时，用 `sh up.sh -d` 代替 `docker compose up -d`；网络可达或已配置
+# 可用镜像源的环境两者等价（compose 优先命中本地已 tag 的规范名镜像，不再联网）。
+# DATAPOLY_IMAGE_MIRROR 可覆盖镜像加速站；镜像清单自动取自 docker-compose.yml 的 image: 行。
+set -e
+
+cd "$(dirname "$0")"
+
+IMAGES=$(grep -hE '^[[:space:]]*image:' docker-compose.yml | awk '{print $NF}' | grep -vE '[\$<>]')
+if [ -n "$IMAGES" ]; then
+  # 容错：公共镜像（如 mysql）预取失败通常意味着加速站整体不可用，compose 会给出原始错误；
+  # 私有/未公开发布的镜像（如本地构建的三服务镜像）本地已有时自动跳过，缺失时交由 compose 决断。
+  sh ../../docker-prefetch-images.sh $IMAGES \
+    || echo '[up.sh] 部分镜像预取失败，继续执行 compose（本地已有同名镜像时不受影响）'
+else
+  echo '[up.sh] 未从 docker-compose.yml 解析到镜像清单，跳过预取（compose 可能使用环境变量镜像名）'
+fi
+
+docker compose up "$@"
diff --git a/build-extension.sh b/build-extension.sh
@@ -8,7 +8,7 @@
 #   DATAPOLY_EXTENSION_GIT_REF      拉取的 ref（分支/标签），默认 master
 #   DATAPOLY_EXTENSION_FORCE_SYNC=1 目录已存在时强制 fetch+reset 到 REF（丢弃本地未提交改动，慎用）
 #
-# 后端模块构建沿用 dev-local/dev.sh 原约定：宿主机 JDK 8、扩展模块不进根 reactor、
+# 后端模块构建沿用 dev-local/dev.sh 原约定：宿主机 JDK 8 优先、无 8 时允许 8 以上（编译目标钉在 1.8）、扩展模块不进根 reactor、
 # 依赖经 <relativePath> 解析根 pom、产物投放 lib-extra/ 后由 package.xml 打进 lib/common。
 # 参数：--skip-tests 用 -DskipTests 替代默认 -Dmaven.test.skip=true（仅作用于扩展侧构建）。
 
@@ -65,7 +65,9 @@ if [ "$(wc -l < "$POM_LIST")" -eq 0 ]; then
     exit 0
 fi
 
-# ---------- ③ 宿主机 JDK 8（与 build.sh/dev.sh 同约定：本机构建统一 JDK 8） ----------
+# ---------- ③ 宿主机 JDK：优先 JDK 8（与 CI 的 temurin 8 对齐）；扩展模块编译目标为 1.8
+#     （根 pom maven.compiler.source/target=1.8），8 以上 JDK 构建同样产出 Java 8 字节码，
+#     故不再硬性断言 8——仅当完全无可用 JDK 时才中止 ----------
 jdkmajor() {
     "$1/bin/java" -version 2>&1 | sed -n 's/.*version "\([0-9][0-9]*\).*/\1/p' | sed 's/^1$/8/'
 }
@@ -79,17 +81,28 @@ if [ "$(uname -s)" = "Darwin" ]; then
         /opt/homebrew/opt/openjdk@8/libexec/openjdk.jdk/Contents/Home \
         /usr/local/opt/openjdk@8/libexec/openjdk.jdk/Contents/Home \
         "$java_home_8"; do
-        if [ -n "$candidate" ] && [ "$(jdkmajor "$candidate" 2>/dev/null)" = "8" ]; then
+        if [ -n "$candidate" ] && [ -n "$(jdkmajor "$candidate" 2>/dev/null)" ]; then
             export JAVA_HOME="$candidate"
-            echo "[ext] JAVA_HOME=$JAVA_HOME"
             break
         fi
     done
 fi
-if [ -z "${JAVA_HOME:-}" ] || [ "$(jdkmajor "$JAVA_HOME" 2>/dev/null)" != "8" ]; then
-    echo "[ext] 未找到 JDK 8（AGENTS.md 约定本机构建统一 JDK 8）；如需强制沿用当前环境 mvn，请先 export JAVA_HOME" >&2
+if [ -z "${JAVA_HOME:-}" ] || [ -z "$(jdkmajor "$JAVA_HOME" 2>/dev/null)" ]; then
+    # 非 macOS 或上述候选均无效：从 PATH 上的 java 反推 JAVA_HOME（如 yum/dnf 装的 OpenJDK）
+    java_bin=$(command -v java 2>/dev/null || true)
+    if [ -n "$java_bin" ]; then
+        java_bin=$(readlink -f "$java_bin" 2>/dev/null || printf '%s' "$java_bin")
+        export JAVA_HOME=$(dirname "$(dirname "$java_bin")")
+    fi
+fi
+if [ -z "${JAVA_HOME:-}" ] || [ -z "$(jdkmajor "$JAVA_HOME" 2>/dev/null)" ]; then
+    echo "[ext] 未找到可用 JDK，无法构建扩展模块" >&2
     exit 1
 fi
+echo "[ext] JAVA_HOME=$JAVA_HOME"
+if [ "$(jdkmajor "$JAVA_HOME" 2>/dev/null)" != "8" ]; then
+    echo "[ext] 当前为 JDK $(jdkmajor "$JAVA_HOME" 2>/dev/null)（非 8）：编译目标 1.8，产物仍为 Java 8 字节码（与容器内 temurin 8 一致）"
+fi
 
 HOST_VERSION=$(grep -m1 '<version>' "$ROOT/pom.xml" | sed -E 's/.*<version>([^<]+)<\/version>.*/\1/')
 

diff --git a/docs/en/build-deploy.md b/docs/en/build-deploy.md
@@ -53,6 +53,32 @@ sh build-docker/build_and_push_image.sh debug
 cd build-docker/install && docker compose up -d
 ```
 
+**(4) Host extension assembly (optional):**
+
+Host-specific extensions can be maintained under the top-level `datapoly-extension/` directory (a standalone
+git repository, excluded by .gitignore and never committed to the host repo): `backend/` holds Maven extension
+modules and `front/` holds extension UI (bundled into the management UI via the webpack `@extension` alias).
+
+```
+# Either point the build at the extension repository — it is shallow-cloned / refreshed under datapoly-extension/
+export DATAPOLY_EXTENSION_GIT_URL=<extension-repository-url>   # git-clone-able URL
+export DATAPOLY_EXTENSION_GIT_REF=master                       # branch/tag, defaults to master
+# -- or skip the env vars and clone the repository under datapoly-extension/ by hand once
+
+# Assemble extensions only: build backend modules (host JDK 8 preferred, 8+ works too, compile target 1.8)
+# and drop the jars into lib-extra/
+sh build-extension.sh
+
+# Or run the regular build: extension assembly runs first, then the UI build and mvn package
+sh build.sh
+# Build the three images with the extension baked in and retag them :latest
+sh build-docker/build_and_push_image.sh
+```
+
+The assembly step runs when `DATAPOLY_EXTENSION_GIT_URL` is set or `datapoly-extension/` already exists: the
+extension jars then ship with the release into `lib/common`, on the runtime classpath of manager / executor /
+gateway; otherwise the step is skipped and pure OSS builds are unaffected.
+
 > Debug builds are for local debugging only and must never be published; rebuild without the argument to restore
 > the production UI.
 

diff --git a/docs/zh/build-deploy.md b/docs/zh/build-deploy.md
@@ -52,6 +52,28 @@ sh build-docker/build_and_push_image.sh debug
 cd build-docker/install && docker compose up -d
 ```
 
+**(4) 宿主扩展装配（可选）：**
+
+支持在顶层 `datapoly-extension/` 目录维护宿主自有扩展（独立 git 仓库，已被 .gitignore 排除、不随宿主仓库提交），
+其中 `backend/` 放 Maven 扩展模块、`front/` 放扩展 UI（webpack `@extension` 别名自动装配进管理端界面）。
+
+```
+# 方式一：配置扩展仓库地址，构建时自动浅克隆/同步到 datapoly-extension/
+export DATAPOLY_EXTENSION_GIT_URL=<扩展仓库地址>   # 可用 git clone 的地址
+export DATAPOLY_EXTENSION_GIT_REF=master           # 分支/标签，默认 master
+# 方式二：不配置环境变量，手动把扩展仓库克隆到宿主根目录（只需一次）
+
+# 单独装配扩展：构建 backend（宿主机 JDK 8 优先，无 8 时 8 以上 JDK 亦可用，编译目标 1.8）并投放 jar 到 lib-extra/
+sh build-extension.sh
+
+# 或直接走常规打包：先自动装配扩展，再构建 UI、mvn 打包，产出带扩展的发行包
+sh build.sh
+# 出带扩展的三张镜像并重标 :latest
+sh build-docker/build_and_push_image.sh
+```
+
+配置了 `DATAPOLY_EXTENSION_GIT_URL` 或本地已有 `datapoly-extension/` 目录时，`build-extension.sh` 才会构建投放——扩展 jar 随发行版进入
+`lib/common`，打进 manager / executor / gateway 的运行时 classpath；两者皆无则跳过，纯开源构建不受影响。
 
 > 调试构建仅供本机联调，**勿随发行版发布**；不带参数重新构建即可恢复生产版 UI。
 

diff --git a/lib-extra/README.md b/lib-extra/README.md
@@ -5,8 +5,8 @@
 classpath（三服务的 `bin/datapolyctl.sh` 均以 `lib/common/*` 通配加载）。
 
 宿主扩展（根目录 `datapoly-extension/`，已被 `.gitignore` 排除，独立 git 仓库）构建后的产物由入库脚本
-`build-extension.sh` 自动投放到这里——`build.sh` / `docker-maven-build.sh` 会先调用它（无环境变量配置时
-该脚本为无操作）。本地一键入口仍是 `dev-local/dev.sh`（薄包装：注入 env.sh 后转发）。第三方额外 jar 也可手工投放。
+`build-extension.sh` 自动投放到这里——`build.sh` / `docker-maven-build.sh` 会先调用它：配置 `DATAPOLY_EXTENSION_GIT_URL`
+或本地已有 `datapoly-extension/` 目录时即构建 backend（宿主机 JDK 8 优先、无 8 时 8 以上可用）并投放本目录，两者皆无则无操作（纯开源构建零影响）。本地一键入口仍是 `dev-local/dev.sh`（薄包装：注入 env.sh 后转发）。第三方额外 jar 也可手工投放。
 
 - 仅 `*.jar` 参与装配；本文件与 `.gitkeep` 只占位，保证目录在干净 clone 中恒存在。
 - 手工清理（回归纯开源构建）：`rm -f lib-extra/*.jar`