ci: 拆分 Jenkins 与 Agent 职责

.gitignore

@@ -38,3 +38,4 @@ lerna-debug.log*
 .env
 .env.*
 !.env.example
+ci/jenkins-agent/*.env

Jenkinsfile

@@ -22,7 +22,7 @@ def isPublishBranch(String branchName, String pattern) {
 }
 
 pipeline {
-  agent any
+  agent { label 'kt-node-agent' }
 
   options {
     skipDefaultCheckout(true)
@@ -33,7 +33,7 @@ pipeline {
 
   parameters {
     booleanParam(name: 'BUILD_DOCKER_IMAGE', defaultValue: true, description: '是否在非 PR 分支使用项目现有 dockerfile 构建镜像')
-    booleanParam(name: 'PUSH_DOCKER_IMAGE', defaultValue: false, description: '是否执行 docker push；仅发布分支生效，需要 Jenkins Agent 已提前完成 docker login')
+    booleanParam(name: 'PUSH_DOCKER_IMAGE', defaultValue: false, description: '是否执行 docker push；仅发布分支生效，需要 Agent 已提前完成 docker login')
     string(name: 'PUBLISH_BRANCH_PATTERN', defaultValue: '^(main|master|release/.+)$', description: '允许推送镜像的分支正则')
     string(name: 'DOCKER_REGISTRY', defaultValue: '', description: '镜像仓库地址，为空时只生成本地镜像')
     string(name: 'IMAGE_NAME', defaultValue: 'kt-template-online-api', description: 'Docker 镜像名称')
@@ -67,7 +67,7 @@ pipeline {
           def registry = params.DOCKER_REGISTRY?.trim()
           env.DOCKER_IMAGE = registry ? "${registry}/${params.IMAGE_NAME}:${env.IMAGE_TAG_FINAL}" : "${params.IMAGE_NAME}:${env.IMAGE_TAG_FINAL}"
 
-          // 项目以 pnpm-lock.yaml 为准；Agent 未安装 pnpm 时再通过 Corepack 启用 pnpm 9。
+          // Agent 由 NAS 侧预先创建；这里仅确认 CI 所需的 Node/pnpm 环境可用。
           if (isUnix()) {
             runCmd("""
               node --version

ci/jenkins-agent/Dockerfile

@@ -0,0 +1,27 @@
+FROM jenkins/inbound-agent:latest-jdk21
+
+USER root
+
+ARG NODE_MAJOR=22
+ARG PNPM_VERSION=9
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends ca-certificates curl git gnupg openssh-client \
+  && install -m 0755 -d /etc/apt/keyrings \
+  && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+  && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODE_MAJOR}.x nodistro main" > /etc/apt/sources.list.d/nodesource.list \
+  && curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+  && chmod a+r /etc/apt/keyrings/docker.gpg \
+  && . /etc/os-release \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian ${VERSION_CODENAME} stable" > /etc/apt/sources.list.d/docker.list \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends nodejs docker-ce-cli docker-buildx-plugin docker-compose-plugin \
+  && corepack enable \
+  && corepack prepare pnpm@${PNPM_VERSION} --activate \
+  && node --version \
+  && pnpm --version \
+  && docker --version \
+  && docker compose version \
+  && rm -rf /var/lib/apt/lists/*
+
+USER jenkins

ci/jenkins-agent/README.md

@@ -0,0 +1,91 @@
+# Jenkins Agent 镜像
+
+这个目录只负责提供 NAS 上创建 Jenkins Agent 所需的镜像和启动说明。Jenkinsfile 只做 CI，不再创建或更新 Agent 节点。
+
+Agent 镜像内置：
+
+- Jenkins inbound agent
+- Git / OpenSSH client
+- Node.js 22
+- pnpm 9
+- Docker CLI / Buildx / Compose plugin
+
+项目业务镜像仍然使用仓库根目录的 `dockerfile`。本目录的 Dockerfile 是给 Jenkins Agent 用的，不是后端服务运行镜像。
+
+## Jenkins 侧配置
+
+在 Jenkins 页面手动创建节点：
+
+```text
+Manage Jenkins -> Nodes -> New Node
+Node name: kt-node-agent
+Type: Permanent Agent
+Remote root directory: /home/jenkins/agent
+Labels: kt-node-agent nodejs docker
+Usage: Only build jobs with label expressions matching this node
+Launch method: Launch agent by connecting it to the controller
+```
+
+保存后进入节点页面，复制 inbound agent 的 `secret`。Jenkinsfile 会通过下面的标签调度到这个节点：
+
+```groovy
+agent { label 'kt-node-agent' }
+```
+
+## NAS 侧构建镜像
+
+在 NAS 上准备 Docker 环境，然后从仓库根目录执行：
+
+```bash
+docker build -t kt-jenkins-agent:node22 -f ci/jenkins-agent/Dockerfile ci/jenkins-agent
+```
+
+## NAS 侧启动 Agent
+
+如果 Jenkins Controller 容器名是 `jenkins`，并且你希望 Agent 通过 Docker 网络访问 Jenkins，可以先准备网络：
+
+```bash
+docker network create jenkins
+docker network connect jenkins jenkins
+```
+
+启动 Agent 容器。你的 Jenkins Controller compose 暴露的是 `18080:8080`，如果 Agent 和 Jenkins 在同一个 Docker 网络，容器内仍然使用 `http://jenkins:8080/`；如果 Agent 不在同一个网络，使用 NAS/服务器可访问地址，例如 `http://Jenkins服务器IP:18080/`。
+
+```bash
+docker run -d \
+  --name kt-node-agent \
+  --restart=always \
+  --network jenkins \
+  -u root \
+  -e JENKINS_URL=http://jenkins:8080/ \
+  -e JENKINS_AGENT_NAME=kt-node-agent \
+  -e JENKINS_SECRET=替换成节点页面里的secret \
+  -e JENKINS_AGENT_WORKDIR=/home/jenkins/agent \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v kt-node-agent-workdir:/home/jenkins/agent \
+  kt-jenkins-agent:node22
+```
+
+如果 Jenkins Controller 不在同一台 NAS 上，把 `JENKINS_URL` 改成 Agent 容器可访问的 Jenkins 地址，例如：
+
+```bash
+-e JENKINS_URL=http://192.168.1.10:18080/
+```
+
+如果 NAS 上的 Agent 需要执行 `docker build`，保留 `/var/run/docker.sock` 挂载。这个挂载等同于让 Agent 拥有 NAS Docker 控制权限，只建议放在可信内网环境。
+
+## 验证
+
+查看 Agent 日志：
+
+```bash
+docker logs -f kt-node-agent
+```
+
+Jenkins 页面确认节点在线：
+
+```text
+Manage Jenkins -> Nodes -> kt-node-agent
+```
+
+节点在线后，多分支流水线点击构建即可进入 CI 阶段。