safety-eval-service/docs/build-tools2/README.md

# GBS 镜像打包操作手册

## 目录概述

本目录包含 GBS 项目 Docker 镜像打包所需的全部配置和脚本。AI 会话加载本目录后，可立即执行打包操作，无需额外询问环境信息。

```
docs/build-tools2/
├── README.md              # 本文档 (打包流程说明)
├── credentials.conf       # 所有账号密码和环境配置
├── projects.conf          # 各项目打包参数清单
├── build_push.py          # 通用打包脚本 (Python, 本地执行)
├── Dockerfile.project     # 项目自带 Dockerfile 示例 (JDK 基础镜像)
└── Dockerfile.template    # 模板 Dockerfile (CentOS 7 + JDK 复制)
```

## 快速开始 (AI 会话指引)

当用户要求打包时，按以下步骤执行:

1. 读取 `credentials.conf` 获取所有连接信息
2. 读取 `projects.conf` 获取目标项目的 JAR 路径、应用名等参数
3. 确认 JAR 文件存在且为最新版本
4. 版本号递增 (基于 projects.conf 中的 latest_tag)
5. 执行 `build_push.py` 或直接用 paramiko 构建并推送
6. 返回完整镜像地址

## 打包架构

```
本地 Windows                    构建服务器 (192.168.20.100)           阿里云 ACR
┌──────────┐     SSH/SFTP       ┌──────────────────┐    docker push   ┌────────────────────┐
│ JAR 文件  │ ─────────────────→│ Docker build      │ ───────────────→│ 张家口 ACR          │
│ Dockerfile│                   │ - 拉取基础镜像     │                 │ kilaa/zcloud-gbs-   │
│ Python    │                   │ - COPY JAR        │                 │ operation           │
│ 打包脚本   │                   │ - docker build    │                 └────────────────────┘
└──────────┘                   │ - docker push     │
                               └──────────────────┘
```

## 两种打包模式

### 模式一: 项目自带 Dockerfile

适用于项目根目录有 Dockerfile 的情况（如 safety-eval-service）。

特点:
- Dockerfile 引用杭州 ACR 的 JDK 基础镜像: `jjb-registry-registry.cn-hangzhou.cr.aliyuncs.com/pub/jdk:1.8.0_202`
- JAR 放置路径: `{build_dir}/start/target/start.jar`
- 需要先登录杭州 ACR 拉取基础镜像
- 镜像大小约 870-910MB

远程构建目录结构:
```
/tmp/docker-build-{app_name}/
├── Dockerfile              (从项目上传)
└── start/
    └── target/
        └── start.jar       (从本地 JAR 上传，统一命名)
```

### 模式二: 模板 Dockerfile (CentOS 7 + JDK)

适用于没有项目 Dockerfile 的情况（如 zcloud-gbs-certificate）。

特点:
- 基础镜像: `centos:7`，JDK 从主节点 `/opt/jdk1.8.0_202` 复制到构建上下文
- JAR 放置路径: `{build_dir}/target/*.jar`
- ENTRYPOINT 包含 Nacos、MySQL 等启动参数
- 镜像大小约 840-880MB

远程构建目录结构:
```
/tmp/docker-build-{app_name}/
├── Dockerfile              (从 Dockerfile.template 上传)
├── jdk1.8.0_202/           (从 /opt/jdk1.8.0_202 复制)
└── target/
    └── *.jar               (从本地 JAR 上传)
```

## 打包流程详细步骤

### 1. 确认 JAR 文件

在本地 Windows 验证 JAR 文件存在:
```powershell
# 检查文件
Get-Item "E:\works\projects\<项目名>\...\target\*.jar" | Select-Object Name, Length, LastWriteTime
```

### 2. SFTP 上传 JAR 到构建服务器

通过 paramiko SSH 连接主节点 192.168.20.100，SFTP 上传 JAR 文件。
JAR 大小通常 170-220MB，上传速度约 1.0 MB/s，耗时约 3-4 分钟。

### 3. 准备构建上下文

在远程服务器上:
- 创建临时目录 `/tmp/docker-build-{app_name}`
- 上传 Dockerfile
- 模板模式: 复制 JDK (`cp -r /opt/jdk1.8.0_202 {build_dir}/`)

### 4. ACR 登录

```bash
# 张家口 ACR (推送目标)
echo 'Kilaa@6666' | docker login --username=kilaa --password-stdin registry.cn-zhangjiakou.aliyuncs.com

# 杭州 ACR (拉取基础镜像，仅项目 Dockerfile 模式需要)
echo 'idurCT!rIq9EzISD' | docker login --username=10952138@qq.com --password-stdin jjb-registry-registry.cn-hangzhou.cr.aliyuncs.com
```

### 5. Docker Build

```bash
docker build -t 'registry.cn-zhangjiakou.aliyuncs.com/kilaa/zcloud-gbs-operation:{app_name}-ota-{date}-{version}' {build_dir}
```

### 6. Docker Push

```bash
docker push 'registry.cn-zhangjiakou.aliyuncs.com/kilaa/zcloud-gbs-operation:{app_name}-ota-{date}-{version}'
```

### 7. 验证

```bash
docker pull registry.cn-zhangjiakou.aliyuncs.com/kilaa/zcloud-gbs-operation:{tag}
```

### 8. 清理

```bash
rm -rf /tmp/docker-build-{app_name}
```

## 镜像标签命名规则

格式: `{app_name}-ota-{YYYYMMDD}-{N}`

| 字段 | 说明 | 示例 |
|------|------|------|
| app_name | 应用名 (kebab-case) | jjb-saas-safety-eval |
| ota | 环境前缀 (当前统一) | ota |
| YYYYMMDD | 打包日期 | 20260703 |
| N | 当日版本号 (从 1 递增) | 12 |

完整示例: `jjb-saas-safety-eval-ota-20260703-12`

## 已打包项目

### safety-eval-service (安全评估服务)

| 配置项 | 值 |
|--------|-----|
| app_name | jjb-saas-safety-eval |
| JAR 路径 | `E:\works\projects\safety-eval-service\safety-eval-start\target\safety-eval-start-1.0-SNAPSHOT.jar` |
| Dockerfile | `E:\works\projects\safety-eval-service\Dockerfile` (项目自带) |
| 打包模式 | 项目 Dockerfile |
| 基础镜像 | `jjb-registry-registry.cn-hangzhou.cr.aliyuncs.com/pub/jdk:1.8.0_202` |
| 最近标签 | `jjb-saas-safety-eval-ota-20260703-12` |

### zcloud-gbs-certificate (证书服务)

| 配置项 | 值 |
|--------|-----|
| app_name | zcloud-gbs-certificate |
| JAR 路径 | `E:\works\projects\zcloud_gbs_certificate\start\target\start.jar` |
| Dockerfile | 模板 (Dockerfile.template) |
| 打包模式 | 模板 Dockerfile |
| 基础镜像 | centos:7 + JDK 1.8.0_202 |
| 最近标签 | `zcloud-gbs-certificate-ota-20260701-2` |

## 通用打包脚本使用

```bash
# 使用项目自带 Dockerfile
python build_push.py \
    --jar "E:\works\projects\safety-eval-service\safety-eval-start\target\safety-eval-start-1.0-SNAPSHOT.jar" \
    --app jjb-saas-safety-eval \
    --version 13 \
    --project-dockerfile "E:\works\projects\safety-eval-service\Dockerfile"

# 使用模板 Dockerfile
python build_push.py \
    --jar "E:\works\projects\zcloud_gbs_certificate\start\target\start.jar" \
    --app zcloud-gbs-certificate \
    --version 3

# 仅预览不执行
python build_push.py --jar <path> --app <name> --version 1 --dry-run
```

## K8s 部署命令

```bash
# 更新已有部署的镜像
kubectl set image deployment/{app_name} \
    {app_name}={full_image} -n jjb-dragon

# 新建部署
kubectl create deployment {app_name} \
    --image={full_image} -n jjb-dragon --replicas=1

# 查看部署状态
kubectl get pods -n jjb-dragon | grep {app_name}

# 查看 Pod 日志
kubectl logs -f deployment/{app_name}-deploy -n jjb-dragon --tail=100
```

## 常见问题

### Q: docker build 时拉取基础镜像失败
A: 确认已登录杭州 ACR: `docker login jjb-registry-registry.cn-hangzhou.cr.aliyuncs.com`

### Q: docker push 时提示 unauthorized
A: 确认已登录张家口 ACR: `docker login registry.cn-zhangjiakou.aliyuncs.com`

### Q: SSH 连接超时
A: 主节点网络偶尔不稳定，重试即可。

### Q: 应用启动后报 Nacos 连接失败
A: 项目 Dockerfile 模式下 ENTRYPOINT 不带 -D 参数，Nacos 配置由 application-{profile}.yml 提供。确认 `spring.profiles.active` 对应正确环境，且 Nacos 地址在目标部署环境可达。

### Q: 如何确认镜像已推送成功
A: 在构建服务器执行 `docker pull {full_image}`，能拉取即成功。

## 环境依赖

- **Python 3.x** (本地 Windows)
- **paramiko** (Python SSH 库): `pip install paramiko`
- **构建服务器**: 192.168.20.100 (root/Zcloud@zcloud100)
  - Docker 已安装
  - JDK 1.8.0_202 已安装在 `/opt/jdk1.8.0_202`
  - Maven 3.8.8 已安装在 `/opt/maven`