alien_cloud/docs/jenkins

UAT 流水线：构建镜像并推送到 Harbor（方案 A）

在现有 UAT Maven + jar 部署 流水线上增加可选阶段，把业务镜像推到：

39.105.153.68/alien_cloud/<服务名>:uat-latest          # 当前预生产最新
39.105.153.68/alien_cloud/<服务名>:uat-build-<N>       # 被本次构建顶替的旧 uat-latest（归档）

生产侧 Gateway-K8s / Alien-Cloud-K8s-Whole 推荐使用 SOURCE_TAG=uat-latest 做晋升；需要固定某一版快照时用 uat-build-<N>。

脚本：docs/jenkins/Jenkinsfile-uat-build-deploy.groovy

---

一、整体流程

UAT Jenkins Job（88:30003）
  1. Checkout（拉 alien_cloud 预生产分支）
  2. Maven Build（mvn clean package）
  3. Push images to Harbor（PUSH_TO_HARBOR=true 时）
       若已有 uat-latest：pull → 再打 tag uat-build-<本次构建号> → push
       docker build → push ...:uat-latest
  4. Deploy Services（拷 jar 到 /app_deploy_uat + docker restart，与现网一致）

Harbor Web（153.68）gateway 等仓库有 uat-latest + 若干 uat-build-*

生产 Jenkins（同机，另一文件夹）
  Gateway-K8s / Whole：SOURCE_TAG=uat-latest → produ-xxx → ACK

标签规则（以构建 #49 为例）

步骤	说明
推送前	若存在 uat-latest，将其归档为 uat-build-49（与本次 Jenkins 构建号一致）
推送后	新镜像仅打 uat-latest
生产晋升	SOURCE_TAG=uat-latest 即「当前 UAT 最新」

---

二、一次性准备（运维 / Jenkins 管理员）

2.1 Harbor（153.68）

• 项目 alien_cloud 已存在
  
• 基础镜像 alien_cloud/base/openjdk8-ffmpeg:v1 已 push
  
• 机器人 robot$alien_cloud+jenkins-k8s 具备 推送 权限
  

2.2 Jenkins 凭据（全局，UAT / 生产 Job 共用）

ID	类型	内容
harbor-robot-alien	Username with password	用户 robot$alien_cloud+jenkins-k8s，密码=Token
zhanghaomimapingzheng	Git	UAT Job SCM 已在使用

2.3 Jenkins 执行机 Docker（通常在 88 本机或 Jenkins 容器内）

# 探测 Registry
curl -sI http://39.105.153.68/v2/

# 登录（与凭据一致）
echo '<TOKEN>' | docker login 39.105.153.68 -u 'robot$alien_cloud+jenkins-k8s' --password-stdin

若 HTTP + IP 访问，需在 运行 docker 的宿主机 /etc/docker/daemon.json 增加：

{
  "insecure-registries": ["39.105.153.68"]
}

然后 systemctl restart docker（注意：若在 153.68 上误执行会影响 Harbor，应在 88 Jenkins 节点 配置）。

2.4 将脚本提交到 Gitea

本地修改 docs/jenkins/Jenkinsfile-uat-build-deploy.groovy 后，push 到 UAT Job 使用的分支（如 uat-20260202）。

---

三、配置 UAT Jenkins Job

项	值
定义	Pipeline script from SCM
仓库	http://8.152.195.41:3000/alien/alien_cloud
分支	*/uat-20260202（与你们一致）
Script Path	docs/jenkins/Jenkinsfile-uat-build-deploy.groovy
SCM 凭据	Git（不要选 Harbor 机器人）

保存后先 立即构建一次，加载新参数。

---

四、Build with Parameters（推荐首次 gateway）

配置页 vs 构建页（易混）

页面	HARBOR_PUSH_SCOPE 长什么样
Job → 配置（Configure）	多行文本框，每行一个选项——这是在编辑下拉列表，不是让你手打 tag
Build with Parameters（立即构建旁）	下拉框，可点选 all-java-services、gateway-only 等

若在「配置」里看到文本框，属正常；请去 Build with Parameters 里选。

必须勾选 PUSH_TO_HARBOR

参数	说明
PUSH_TO_HARBOR	必须勾选，否则整个「Push images to Harbor」阶段跳过，Harbor 不会出现 gateway（与 HARBOR_PUSH_SCOPE 选什么无关）
HARBOR_PUSH_SCOPE	仅当 PUSH_TO_HARBOR=true 时生效

配置里「Set by Default」未勾时，每次构建都要在 Build with Parameters 手动勾选 PUSH_TO_HARBOR。

参数	首次试跑建议
GIT_BRANCH	uat-20260202
FORCE_UPDATE	按需
PUSH_TO_HARBOR	勾选 true
HARBOR_PUSH_SCOPE	下拉选 all-java-services 或 gateway-only
HARBOR_REGISTRY	39.105.153.68
HARBOR_PROJECT	alien_cloud

构建成功后日志末尾应有：

>>> archive previous uat-latest -> uat-build-<N>   # 非首次构建才有
>>> pushed 39.105.153.68/alien_cloud/gateway:uat-latest
>>> Prod promote: SOURCE_TAG=uat-latest

---

五、验证 Harbor

浏览器打开：http://39.105.153.68/harbor/ → 项目 alien_cloud → 镜像仓库应出现 gateway，标签 uat-latest，以及若干 uat-build-*。

或命令行：

curl -s -u 'robot$alien_cloud+jenkins-k8s:<TOKEN>' \
  'http://39.105.153.68/v2/alien_cloud/gateway/tags/list'

---

六、接生产晋升流水线

在 Gateway-K8s 或 Alien-Cloud-K8s-Whole：

参数	值
SOURCE_TAG	uat-latest（推荐）；或指定历史 uat-build-<N>
DEPLOY_STRATEGY	先 skip（只晋升 Harbor），再 rolling
DEPLOY_MODE	单服务用 single + gateway

---

七、参数说明

参数	说明
PUSH_TO_HARBOR	默认 true（推 Harbor）；仅 jar 部署 UAT 时 取消勾选
HARBOR_PUSH_SCOPE	默认 all-java-services（七个）；gateway-only 等只推一个；Maven 须对所选模块打出 jar
HARBOR_PRUNE_OLD_TAGS	默认 true：每个仓库只保留最近 10 个 uat-build-* tag，删更旧的（不删 uat-latest）
HARBOR_KEEP_TAG_COUNT	保留 uat-build-* 个数，默认 10

旧镜像清理说明

• 每次 push 更新 uat-latest；被顶替的旧 uat-latest 会归档为 uat-build-<本次 Jenkins 构建号>。
• 脚本在 push 后调 Harbor API 删除最老的 uat-build-*，保留最近 N 个；永不删除 uat-latest。
• 机器人需有 删除制品 权限；若删除失败，日志会有 WARN: delete failed。
• 不会删除 base/openjdk8-ffmpeg 等基础镜像。
• Jenkins 本机 docker images 可用 docker image prune 另行清理，与 Harbor 无关。

环境变量	说明
UAT_HARBOR_LATEST_TAG	固定 uat-latest
UAT_HARBOR_BUILD_TAG	本次归档名 uat-build-${BUILD_NUMBER}（仅在有旧 uat-latest 时 push）

---

八、常见问题

现象	处理
not found pull 基础镜像	确认 Harbor 有 base/openjdk8-ffmpeg:v1
Login Succeeded 后 push 失败	机器人是否有项目 push 权限
x509 / 证书错误	88 上 insecure-registries 或 HTTPS + ca.crt
Harbor 仍无 gateway	是否勾选了 PUSH_TO_HARBOR；Maven 是否打出 alien-gateway/target/*.jar
生产 Whole uat-latest: not found	先跑一轮 UAT 推 Harbor；SOURCE_TAG 填 uat-latest
需要回滚到上一版 UAT	在 Harbor 查 uat-build-<N>，生产 Job 填该 tag 作 SOURCE_TAG
no space left on device（docker build）	Jenkins 节点磁盘满；见下文 磁盘不足

磁盘不足（no space left on device）

Harbor 阶段会在本机 docker build，store/lawyer 等带 lib/ 时单次上下文可达数百 MB，七个服务连续构建易占满 /var/lib/docker。

在 Jenkins 节点（日志里多为 /var/jenkins_home 所在盘）执行：

df -h
docker system df
docker system prune -af          # 清理未使用镜像/构建缓存（会删未引用镜像，慎用前先确认）
docker builder prune -af       # 仅清构建缓存（相对安全）

脚本已做优化：withLib=false 的服务（如 gateway）构建上下文不再拷贝 target/lib，仅保留空 lib/.keep；每个服务 push 后删除本地镜像并清理 .jenkins_docker_ctx。仍建议在节点定期 docker system prune。

---

九、与现网 jar 部署的关系

• Deploy Services 阶段仍会拷 jar 并 docker restart UAT 容器，不影响现有 UAT 访问方式。
  
• Harbor 镜像供 ACK / 生产晋升 使用，两套路径可并行。
  
• 日常若只更新 UAT 机 jar、暂不发 ACK，可 PUSH_TO_HARBOR=false。