# Seesaw APK 流水线完整构建过程（一步一图）

本文记录一次**从零新建 Pipeline** 到**生成 JKS**、**配置凭据**、**上传 XAPK 构建**、**验证产物**的完整过程。照着截图顺序操作即可复现。

- **Jenkins**：<http://10.71.1.86:7080/>（2.580.2）
- **本次演示任务**：`Seesaw-APK-Pipeline-Walkthrough`
- **演示构建**：Build #1 ✅ SUCCESS，耗时约 15 秒
- **演示凭据**：`seesaw-keystore-walkthrough` / `seesaw-keystore-pass-walkthrough`
- **正式任务**：`Seesaw-APK-Pipeline`（不要在生产任务上做实验）

> 说明：本演示为了不覆盖已有生产凭据，使用了带 `-walkthrough` 后缀的凭据。你复现时可以把流水线里的凭据 ID 换成自己的。
>
> 第 11 步在 Jenkins Script Console 里生成的是一个**临时演示 JKS**（密码随机、不回显），用于展示 `keytool` 的生成和验证输出。实际构建使用的是 `keys/seesaw-release.jks`，命令完全相同。

---

## 步骤 0：打开 Jenkins 首页


![00-dashboard.png](/static/img/cf6366b01aea30ad2e114d693bccb371.00-dashboard.webp)
登录后进入 Dashboard。左侧是 **New Item**，右上角是当前用户。

---

## 步骤 1：点击 New Item


![01-new-item.png](/static/img/10405b5a01b24aa4d0a428a672679e50.01-new-item.webp)

点击左侧 **New Item**，进入新建任务页面。

---

## 步骤 2：输入任务名并选择 Pipeline


![02-name-pipeline.png](/static/img/08806a86643cfbd307ddc1ecbf02e4da.02-name-pipeline.webp)

- 名称：`Seesaw-APK-Pipeline-Walkthrough`
- 类型：**Pipeline**
- 点击 **OK**

---

## 步骤 3：进入任务配置页


![03-config-page.png](/static/img/51e4fd723ea158b35d0f8aa5b6013bc7.03-config-page.webp)

配置页分为 General、Triggers、Pipeline、Advanced 几个区域。

---

## 步骤 4：勾选“参数化构建”


![04-parameterized.png](/static/img/a4e55a34f52e8482d970f60f46ccf134.04-parameterized.webp)

勾选 **This project is parameterized**，下面会出现 **Add Parameter** 按钮。

---

## 步骤 5：打开参数类型菜单


![05-add-parameter-menu.png](/static/img/eee88950882f10d5470455ec6bc05c09.05-add-parameter-menu.webp)

点击 **Add Parameter**，菜单里可以看到：

- Boolean / Choice / Credentials Parameter
- **File Parameter**
- Password / String Parameter

---

## 步骤 6：添加文件参数 XAPK_FILE


![06-file-parameter.png](/static/img/3fa753ca5b9cd180d37035bc2aa1f717.06-file-parameter.webp)

选择 **File Parameter**，填写：

- Name：`XAPK_FILE`
- Description：`上传 seesaw-class-*.xapk 文件`

---

## 步骤 7：补齐其余参数


![07-parameters-configured.png](/static/img/73bdbc62345b29b54aeadad2790f46cf.07-parameters-configured.webp)

继续添加 3 个 **String Parameter**：

| Name | Default Value | 说明 |
| --- | --- | --- |
| `XAPK_URL` | 空 | 可选，从 URL 下载 XAPK |
| `EXPECTED_PACKAGE` | `seesaw.shadowpuppet.co.classroom` | 期望包名 |
| `EXPECTED_VERSION` | 空 | 可选，留空不校验版本 |

---

## 步骤 8：粘贴 Pipeline 脚本


![08-pipeline-script.png](/static/img/bc430ba49f37016a73128f69ca95f440.08-pipeline-script.webp)

在 **Pipeline → Definition** 选择 **Pipeline script**，把 `pipeline.groovy` 的全部内容粘贴进去。

脚本包含 6 个阶段：Source、Extract、Merge、Sign、Verify、Artifact。

---

## 步骤 9：保存任务


![09-job-created.png](/static/img/9fdf888c5e389710d52fbc6200afedf1.09-job-created.webp)

点击 **Save**，任务创建完成。此时还没有构建记录。

---

## 步骤 10：打开 Script Console

![](https://docs.momen.world/static/img/a3dba2f49a058bb140207efc31633ce1.10-script-console.webp)

进入 **Manage Jenkins → Script Console**。这里用来演示 JKS 的生成与验证（也可以在本机终端执行同样的 `keytool` 命令）。

---

## 步骤 11：生成并验证 JKS


![11-keytool-generate.png](/static/img/97ec570ba29a428f6fa9b9cd8824d2fc.11-keytool-generate.webp)

在 Script Console 执行 `keytool` 后，结果里可以看到：

- `Generating 4,096 bit RSA key pair ...`
- `JKS saved: /var/jenkins_home/walkthrough-keys/seesaw-demo.jks`
- `Keystore type: JKS`
- `Alias name: seesaw`
- `Entry type: PrivateKeyEntry`
- `Signature algorithm name: SHA384withRSA`
- 证书有效期与 SHA256 指纹

关键命令（实际生成 `keys/seesaw-release.jks` 时使用）：

```bash
keytool -genkeypair -storetype JKS \
  -keystore seesaw-release.jks \
  -storepass "$PASS" -keypass "$PASS" \
  -alias seesaw -keyalg RSA -keysize 4096 -validity 10000 \
  -dname "CN=Seesaw Internal, OU=Mobile, O=DEXA, L=Shanghai, ST=Shanghai, C=CN"
```

验证命令：

```bash
keytool -list -v -keystore seesaw-release.jks -storepass "$PASS"
```

> 密码保存在 `keys/keystore-info.txt`，不会写入本文档。

---

## 步骤 12：打开 Credentials


![12-credentials-page.png](/static/img/61e787b8960e48eec2197a9a209e92f9.12-credentials-page.webp)

进入 **Manage Jenkins → Credentials → System → Global credentials**。

---

## 步骤 13：新建 Secret file 凭据


![13-secret-file.png](/static/img/c14099209d980ac17a6295ac74e17b07.13-secret-file.webp)

点击 **Add Credentials**，Kind 选择 **Secret file**，点击 **Next**。

---

## 步骤 14：填写 JKS 凭据信息


![14-credential-form.png](/static/img/9dd9d5746df1bbd90ace7659c5e14ffb.14-credential-form.webp)

- File：选择 `seesaw-release.jks`
- ID：`seesaw-keystore-walkthrough`
- Description：`演示用 JKS（alias: seesaw）`
- 点击 **Create**

---

## 步骤 15：JKS 凭据创建完成


![15-credential-created.png](/static/img/9063b1c19c6baee8191f23a252beea09.15-credential-created.webp)

凭据列表中出现 `seesaw-keystore-walkthrough`。

---

## 步骤 16：新建密码凭据


![16-password-credential.png](/static/img/70d545c073751c97093c71589d7d12a5.16-password-credential.webp)

再次 **Add Credentials**，Kind 选择 **Secret text**：

- Secret：JKS 的 storepass
- ID：`seesaw-keystore-pass-walkthrough`
- Description：`演示用 JKS 密码`
- 点击 **Create**

---

## 步骤 17：两个凭据准备就绪



![17-credentials-final.png](/static/img/0a3b8f2dfae83c241923a4acf0ae42cf.17-credentials-final.webp)

现在有：

- `seesaw-keystore-walkthrough`（JKS 文件）
- `seesaw-keystore-pass-walkthrough`（密码）

---

## 步骤 18：把流水线脚本改为使用演示凭据


![18-script-updated.png](/static/img/ecdb0344a8a250dacdf8e209e8d7dddc.18-script-updated.webp)

打开任务 **Configure**，把脚本中的：

```groovy
file(credentialsId: 'seesaw-keystore', ...)
string(credentialsId: 'seesaw-keystore-pass', ...)
```

改为：

```groovy
file(credentialsId: 'seesaw-keystore-walkthrough', ...)
string(credentialsId: 'seesaw-keystore-pass-walkthrough', ...)
```

> 如果你只创建了一套凭据，直接使用原来的 ID 即可，不需要这一步。

---

## 步骤 19：保存配置


![19-job-configured.png](/static/img/9fdf888c5e389710d52fbc6200afedf1.09-job-created.webp)

点击 **Save**，回到任务页面。

---

## 步骤 20：打开 Build with Parameters


![20-build-form.png](/static/img/89271cd3b0b334da3d3e1632a3a338aa.20-build-form.webp)

点击 **Build with Parameters**，可以看到：

- `XAPK_FILE`：选择文件
- `XAPK_URL`：留空
- `EXPECTED_PACKAGE`：默认包名
- `EXPECTED_VERSION`：留空

选择 `seesaw-class-10-150-1.xapk`，点击 **Build**。

---

## 步骤 21：构建运行中


![21-build-running.png](/static/img/3f83ee2e6899b1878fb61ff8b77c4cb3.21-build-running.webp)

构建开始，页面显示 **In progress** 和当前构建号。

---

## 步骤 22：构建成功


![22-build-success.png](/static/img/9e3e6d2faaeb76ca0cafb72b82f9d737.22-build-success.webp)

Build #1 完成，结果 **SUCCESS**。

---

## 步骤 23：查看构建产物


![23-build-artifacts.png](/static/img/b44f128210d8577022109e55f3ac3801.23-build-artifacts.webp)

**Build Artifacts** 中可以看到：

| 文件 | 大小 |
| --- | --- |
| `Seesaw-10.150.1-signed.apk` | 43.02 MiB |
| `build-info.txt` | 330 B |
| `apk-info.txt` | 208 B |
| `sign.log` | 1.17 KiB |

---

## 步骤 24：查看阶段耗时


![24-build-stages.png](/static/img/50879e6323e14fbb2590c9a5fa205067.24-build-stages.webp)

6 个阶段全部变绿：

```text
Source → Extract → Merge → Sign → Verify → Artifact
```

本次总耗时约 15 秒（工具已缓存）。

---

## 步骤 25：查看验证日志


![25-verify-console.png](/static/img/bd59d1a83f20c357edea7567c3290cb1.25-verify-console.webp)

Console Output 中可以看到 Verify 阶段的检查结果：

```text
+ grep -q signature verified build/sign.log
+ unzip -t build/signed/seesaw-merged-aligned-signed.apk
+ echo VERIFIED package=seesaw.shadowpuppet.co.classroom version=10.150.1 code=1988154
VERIFIED package=seesaw.shadowpuppet.co.classroom version=10.150.1 code=1988154
+ FINAL=build/Seesaw-10.150.1-signed.apk
```

说明：

- 签名验证通过（`signature verified`）
- APK 完整性检查通过（`unzip -t`）
- 包名 `seesaw.shadowpuppet.co.classroom`
- 版本 `10.150.1`，versionCode `1988154`

---

## 复现检查清单

| 检查项 | 预期 |
| --- | --- |
| 任务类型 | Pipeline |
| 参数 | XAPK_FILE、XAPK_URL、EXPECTED_PACKAGE、EXPECTED_VERSION |
| 凭据 | JKS Secret file + 密码 Secret text |
| 构建结果 | SUCCESS |
| 阶段 | 6 个阶段全部通过 |
| 产物 | `Seesaw-<版本>-signed.apk` |
| 验签 | 日志包含 `signature verified` |
| 完整性 | `unzip -t` 无错误 |

## 与正式任务的关系

本次演示创建的是 `Seesaw-APK-Pipeline-Walkthrough`，正式任务 `Seesaw-APK-Pipeline` 不受影响。

复现时建议：

1. 先按本文创建一个演示任务，确认流程能跑通
2. 再用正式 JKS 创建/更新 `seesaw-keystore`
3. 最后把演示任务删除，只保留正式任务

---

_本文截图位于 `screenshots/walkthrough/`，完整原理与排错见 `Seesaw-APK流水线复盘.md`。_


Jenkins 新增流水线

# Seesaw APK 自动构建流水线 — 配置复盘

- **Jenkins**：<http://10.71.1.86:7080/>（2.580.2，Linux 容器，Java 21）
- **任务名**：`Seesaw-APK-Pipeline`
- **测试输入**：`/home/momen/Downloads/seesaw-class-10-150-1.xapk`
- **最终产物**：`Seesaw-10.150.1-signed.apk`（43.02 MiB）
- **验证结果**：✅ 上传文件构建成功（Build #9，耗时 15 秒）
- **状态**：已完成并通过一次真实上传构建

---

## 1. 需求与实现

| 阶段 | 需求 | 实现 |
| --- | --- | --- |
| 1. Source | 获取 XAPK（上传） | Jenkins File Parameter `XAPK_FILE` |
| 2. Extract | 检查 APK 数量、包名、版本、模块 | `unzip` + APKEditor `info` |
| 3. Merge | 合并分包 | `APKEditor.jar m` |
| 4. Sign | 使用 Jenkins Credentials 中的 JKS | `uber-apk-signer` + Secret file/Secret text |
| 5. Verify | 签名、版本、包名、完整性 | 验签日志 + 包名/版本比对 + `unzip -t` |
| 6. Artifact | 保存 APK 供 Intune 上传 | `archiveArtifacts` + 构建信息 |

---

## 2. 环境勘查与问题修复

### 2.1 初始环境



![01-jenkins-dashboard.png](/static/img/cf33fd9d4dcb7d1c76ec73b95e5e58df.01-jenkins-dashboard.webp)
全新 Jenkins：无任务、无构建历史，内置节点 2 个执行器。

### 2.2 插件依赖损坏（已修复）

![02-script-console-env.png](/static/img/20fc44044e29a826adeee32d0fdb4d34.02-script-console-env.webp)

初始状态下 Pipeline 系列插件全部 **Failed to load**，无法创建 Pipeline 任务。根因：

- `ssh-credentials`、`workflow-cps`、`bootstrap5-api`、`jakarta-xml-bind-api`、`snakeyaml-api` 等依赖缺失
- 插件加载失败被禁用后，Jenkins 不会自动重试

处理过程：


![03-manage-plugins-error.png](/static/img/3c8511f002b9019501b5279f85454e8b.03-manage-plugins-error.webp)
1. 在 Update Center 选择并安装缺失依赖
2. 等待所有插件下载完成
3. 通过 `/restart` 重启 Jenkins
4. 重启后 `Dependency errors` 全部消失

### 2.3 凭据为空（已补充）


![04-credentials-empty.png](/static/img/1255e83458fb30e7bcb173d3325171fa.04-credentials-empty.webp)
项目没有现成 JKS，因此生成了一个测试用签名密钥：

- 文件：`keys/seesaw-release.jks`
- 别名：`seesaw`
- 类型：JKS，RSA 4096，有效期 10000 天
- 密码：单独保存在 `keys/keystore-info.txt`（权限 600，未写入本文档）

Jenkins Credentials 中创建了：

| Credential ID | 类型 | 用途 |
| --- | --- | --- |
| `seesaw-keystore` | Secret file | JKS 文件 |
| `seesaw-keystore-pass` | Secret text | keystore 密码（key 密码相同） |


![06-credential-jks-dialog.png](/static/img/1fd9d171d71a9a881966e3195ce876d1.06-credential-jks-dialog.webp)

> ⚠️ 这是测试密钥。如果线上已有正式签名 JKS，请替换 `seesaw-keystore`，并保持别名/密码一致；否则已安装的 App 无法覆盖升级。

### 2.4 构建节点工具链

通过 Script Console 只读检查容器环境：


![02-script-console-env.png](/static/img/20fc44044e29a826adeee32d0fdb4d34.02-script-console-env.webp)
| 工具 | 结果 |
| --- | --- |
| `unzip` / `curl` / `git` | ✅ 已有 |
| `java` / `keytool` | ⚠️ 在 `/opt/java/openjdk/bin/`，PATH 中没有 |
| Android SDK / aapt2 / apksigner | ❌ 未安装 |
| `apkeditor` | ❌ 未安装 |

方案：不安装完整 Android SDK，改用两个纯 Java 工具，缓存在 `$JENKINS_HOME/tools`：

- `APKEditor-1.4.9.jar`
- `uber-apk-signer-1.3.0.jar`

首次构建自动下载（约 30 MB），后续复用。

---

## 3. 流水线实现

### 3.1 任务参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `XAPK_FILE` | File | 上传 `.xapk` |
| `XAPK_URL` | String | 可选，从 URL 下载（优先于上传文件） |
| `EXPECTED_PACKAGE` | String | 默认 `seesaw.shadowpuppet.co.classroom` |
| `EXPECTED_VERSION` | String | 可选，留空不校验 |

### 3.2 六个阶段

1. **Source**：优先使用 `XAPK_URL`；否则读取 `XAPK_FILE`
2. **Extract**：统计 APK 数量、解包、APKEditor 读取包名/版本/模块
3. **Merge**：APKEditor 合并为单体 APK
4. **Sign**：`withCredentials` 注入 JKS，uber-apk-signer 签名
5. **Verify**：验签、包名/版本比对、ZIP 完整性检查
6. **Artifact**：归档 APK、构建信息、签名日志

完整脚本：`pipeline.groovy`；Jenkins 任务 XML：`job-config.xml`。

### 3.3 实现中的关键坑

**坑 1：Pipeline 的 File 参数不会自动进入 workspace**

Jenkins 的 `FileParameterValue` 只有 Freestyle 的 `BuildWrapper` 会把它复制到 workspace。Pipeline 构建中文件实际保存在：

```text
$JENKINS_HOME/fileParameterValueFiles/jenkins*.tmp
```

并且 `XAPK_FILE` 环境变量只是原始文件名，不是路径。因此在 Source 阶段增加了兜底逻辑：如果 workspace 找不到，就取该目录下最新的 `.tmp` 文件。

**坑 2：`set -euo pipefail` 导致兜底逻辑被跳过**

`find` 查找不存在的目录时返回非 0，配合 `pipefail` 会让赋值语句直接退出脚本。修复方式：

```bash
SRC=$(find ... | head -1) || SRC=""
```

**坑 3：workspace 残留导致合并失败**

APKEditor 拒绝覆盖已存在的 `build/seesaw-merged.apk`。修复：Source 阶段先 `rm -rf build`。

**坑 4：Jenkins 2.580 的文件参数表单**

新 UI 的 `<form>` 默认是 `application/x-www-form-urlencoded`，脚本自动化时需要显式设置：

```js
form.enctype = "multipart/form-data";
```

然后提交，文件才会被 Jenkins 保存到临时目录。

---

## 4. 构建验证

### 4.1 任务创建
![](https://docs.momen.world/static/img/03716c9deb03eb686213d4cda63301aa.07-pipeline-job-created.webp)
、
### 4.2 构建过程

首次构建（Build #1）用于验证参数传递，因文件参数未进入 workspace 而失败：


![08-build1-running.png](/static/img/86dd6a6e425ca84dceda8d561bf1f4e3.08-build1-running.webp)
随后通过 `XAPK_URL` 方式验证了完整流程（Build #5）：


![09-build5-success.png](/static/img/0d056689ad012ec73bd4b8204495e4a3.09-build5-success.webp)

![10-build5-stages.png](/static/img/4b0b274c6d7126e09f6f2d855818d4ce.10-build5-stages.webp)

### 4.3 上传文件构建（最终验收）


![11-build9-upload-success.png](/static/img/c5ae4617d04005d3068fc780808844b8.11-build9-upload-success.webp)
本次通过 `XAPK_FILE` 上传构建，结果：

```text
PACKAGE=seesaw.shadowpuppet.co.classroom
VERSION=10.150.1
VERSION_CODE=1988154
APK_COUNT=30
MODULES=ar,arm64_v8a,armeabi_v7a,de,en,es,et,fr,hdpi,hi,in,it,ja,km,ko,ms,my,nl,pt,ru,th,tr,tvdpi,uk,vi,xhdpi,xxhdpi,xxxhdpi,zh
SIGNED_APK=Seesaw-10.150.1-signed.apk
SHA256=7a9a49f285609162fcbf86c0699f405407f33c3fdfcdb22cb943caed6f99b99a
```

### 4.4 阶段耗时


![12-build9-stages.png](/static/img/408d847671f46184ad6bb4c1105b296b.12-build9-stages.webp)
| 阶段 | 耗时 |
| --- | --- |
| Source（上传） | 0.34 秒 |
| Extract | 1 秒 |
| Merge | 4 秒 |
| Sign | 4 秒 |
| Verify | 2 秒 |
| Artifact | 0.88 秒 |

总耗时约 15 秒（工具已在 Build #5 缓存，Build #9 不再下载）。

### 4.5 签名验证

```text
VERIFY
file: .../seesaw-merged-aligned-signed.apk (43.02 MiB)
- zipalign verified
- signature verified [v3]
  Subject: CN=Seesaw Internal, OU=Mobile, O=DEXA, L=Shanghai, ST=Shanghai, C=CN
  SHA256: 627a802032312e8266bb5a1d154575e59b73af6688ae2c63a7e36111fa5e9853
  Expires: Fri Mar 27 02:41:01 UTC 2054
Successfully processed 1 APKs and 0 errors
```

---

## 5. 构建产物与 Intune

Build #9 归档内容：

| 文件 | 大小 | 说明 |
| --- | --- | --- |
| `Seesaw-10.150.1-signed.apk` | 43.02 MiB | 最终签名 APK |
| `build-info.txt` | 330 B | 包名、版本、模块、SHA256 |
| `apk-info.txt` | 208 B | APKEditor 读取的包信息 |
| `sign.log` | 1.13 KiB | 签名与验签日志 |

获取方式：打开 Build #9 → **Build Artifacts** → 下载 `Seesaw-10.150.1-signed.apk`，然后手动上传 Intune。

> Intune 自动上传未实现（按确认结果：只归档，手动上传）。

---

## 6. 复盘：做对了什么 / 下次怎么更快

### 做对了

1. **先在本地跑通合并/签名/验签**，确认工具链可行，再动 Jenkins
2. 用纯 Java 工具替代 Android SDK，减少 1 GB 级依赖
3. 登录态掉线时使用 request-help 让用户接管，而不是猜测密码
4. 每一步都保留截图和构建日志，最终有完整证据链

### 踩过的坑

| 问题 | 原因 | 解决 |
| --- | --- | --- |
| Pipeline 插件全部加载失败 | 依赖缺失后被禁用 | 安装依赖 + 重启 |
| 上传文件找不到 | Pipeline 不会把 File 参数复制进 workspace | 读取 `$JENKINS_HOME/fileParameterValueFiles` |
| 兜底逻辑不执行 | `pipefail` + `find` 非 0 | `|| SRC=""` |
| 合并报 Path already exists | workspace 未清理 | Source 阶段 `rm -rf build` |
| 自动化上传无效 | 表单 enctype 是 urlencoded | 显式改为 `multipart/form-data` |
| 脚本控制台结果为空 | 直接改 textarea value 不触发 Jenkins 的输入事件 | 用 `bsk fill` 后再提交表单 |

### 后续建议

1. **替换正式 JKS**：当前为测试密钥，正式发布前务必换成组织现有签名密钥
2. **清理临时文件**：`$JENKINS_HOME/fileParameterValueFiles/*.tmp` 会累积（本次测试留下多个 39 MB 文件），可加定期清理任务
3. **补充失败通知**：可在 `post { failure { ... } }` 中接入邮件或企微机器人
4. **产物保留策略**：按 Intune 发布节奏设置 `buildDiscarder`
5. **正式化 Source**：如果后续从制品库获取 XAPK，可直接使用 `XAPK_URL`，比文件参数更稳定

---

## 7. 操作时间线

| 时间 | 操作 | 结果 |
| --- | --- | --- |
| 09:xx | 打开 Jenkins、检查环境 | 发现插件依赖缺失、无凭据 |
| 10:xx | 本地验证合并/签名/验签 | 成功，确认方案可行 |
| 10:41 | 生成测试 JKS | 完成 |
| 10:4x | 安装缺失插件并重启 | 依赖错误清零 |
| 10:4x | 创建 `seesaw-keystore` / `seesaw-keystore-pass` | 完成 |
| 10:50 | 创建 `Seesaw-APK-Pipeline` | 完成 |
| 10:52 | Build #5（XAPK_URL） | ✅ 成功 |
| 10:57 | Build #9（文件上传） | ✅ 成功，15 秒 |

---

_本文档与截图保存在 `/home/momen/jenkins-seesaw-doc/`。_


Jenkins初始化并构建Xapk转apk流水线

![](https://docs.momen.world/static/img/58039f26bd0e245b64b022e9f11fd985.image.webp)

https://www.dell.com/support/product-details/en-us/product/poweredge-r730xd/drivers

![image.png](/static/img/f98a0aa904d763dd36bb0c1018b51756.image.webp)

下载并放入vmware7.0中（根据服务器实际安装的系统来定）
解压

解压后存在一个zip `VMWare-perccli64_007.1910.zip`

查看readme得知
```
2. For esx 7.x, To install the perccli, run following command:

                         esxcli software component apply -d <full path to perccli.zip file>

Note: VMWARE will only support 64-bit perccli vib from esxi 7.0 onwards.
```
压缩包要绝对路径

```
[root@localhost:~] esxcli software component apply -d /VMWare-perccli64_007.1910.zip 
Installation Result
   Components Installed: BCM-vmware-perccli64_007.1910.0000.0000-01
   Components Removed: 
   Components Skipped: 
   Message: Operation finished successfully.
   Reboot Required: false
[root@localhost:~] 
```



```
cd /opt/lsi/perccli64/

root@localhost:/opt/lsi/perccli64] ./perccli64 /c0/bbu show all >/1.txt
[root@localhost:/opt/lsi/perccli64] cat /1.txt 
CLI Version = 007.1910.0000.0000 Oct 08, 2021
Operating system = VMkernel 7.0.3
Controller = 0
Status = Success
Description = None


BBU_Info :
========

----------------------
Property      Value   
----------------------
Type          BBU     
Voltage       11 mV   
Current       0 mA    
Temperature   43 C    
Battery State Optimal 
----------------------


BBU_Firmware_Status :
===================

-------------------------------------------------
Property                                   Value 
-------------------------------------------------
Charging Status                            None  
Voltage                                    Low   
Temperature                                OK    
Learn Cycle Requested                      Yes   
Learn Cycle Active                         No    
Learn Cycle Status                         OK    
Learn Cycle Timeout                        No    
I2C Errors Detected                        No    
Battery Pack Missing                       No    
Replacement required                       No    
Remaining Capacity Low                     No    
Periodic Learn Required                    No    
Transparent Learn                          Yes   
No space to cache offload                  No    
Pack is about to fail & should be replaced No    
Cache Offload premium feature required     No    
Module microcode update required           No    
-------------------------------------------------


GasGaugeStatus :
==============

-------------------------------------
Property                   Value     
-------------------------------------
GasGauge StatusCode        0x238     
Fully Discharged           N/A       
Fully Charged              N/A       
Discharging                N/A       
Initialized                N/A       
Remaining Time Alarm       N/A       
Terminate Discharge Alarm  N/A       
Over Temperature           N/A       
Charging Terminated        N/A       
Over Charged               N/A       
Relative State of Charge   100%      
Charger System State       Unknown   
Remaining Capacity         475       
Full Charge Capacity       475       
Is SOH Good                Yes       
Battery backup charge time 0 hour(s) 
-------------------------------------


BBU_Capacity_Info :
=================

--------------------------------------
Property                 Value        
--------------------------------------
Relative State of Charge 100%         
Absolute State of charge 0%           
Remaining Capacity       475 mAh      
Full Charge Capacity     475 mAh      
Run time to empty        Unavailable  
Average time to empty    38 min       
Average Time to full     Unavailable  
Cycle Count              0            
Max Error                0%           
Remaining Capacity Alarm 0 mAh        
Remaining Time Alarm     0 minutes(s) 
--------------------------------------


BBU_Design_Info :
===============

--------------------------------
Property                Value   
--------------------------------
Date of Manufacture     00/00/0 
Design Capacity         460 mAh 
Design Voltage          0 mV    
Specification Info      0       
Serial Number           0       
Pack Stat Configuration 0       
Manufacture Name        0x113   
Device Name                     
Device Chemistry                
Battery FRU             N/A     
Transparent Learn       1       
App Data                0       
Module Version          0.4     
--------------------------------


BBU_Properties :
==============

-------------------------------------------
Property             Value                 
-------------------------------------------
Auto Learn Period    90d (7776000 seconds) 
Learn Delay Interval 0 hour(s)             
Auto-Learn Mode      Transparent           
-------------------------------------------



[root@localhost:/opt/lsi/perccli64] 
```

r730xd更换raid卡电池后仍然显示错误

# Docker MySQL 容器故障修复记录

## 环境

- 容器：`1Panel-mysql-vVOO`
- 镜像：`mysql:8.4.4`
- Compose：`/opt/1panel/apps/mysql/mysql/docker-compose.yml`
- 配置：`/opt/1panel/apps/mysql/mysql/conf/my.cnf`
- 数据目录：`/opt/1panel/apps/mysql/mysql/data`
- MySQL 地址：`127.0.0.1:30006`
- 修复日期：2026-07-14

> 不要在此文档或 shell 历史中记录 sudo、MySQL root 等明文密码。以下使用环境变量占位。

```bash
export SUDO_PASSWORD='<sudo-password>'
export MYSQL_ROOT_PASSWORD='<mysql-root-password>'
export MYSQL_CONTAINER='1Panel-mysql-vVOO'
export MYSQL_APP='/opt/1panel/apps/mysql/mysql'
```

## 故障表现与根因

检查容器：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker ps -a
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker logs --tail 300 "$MYSQL_CONTAINER"
```

容器以退出码 `1` 停止。日志包含 InnoDB 断言失败和以下 socket 锁错误：

```text
[ERROR] [MY-013183] [InnoDB] Assertion failure
[ERROR] [MY-010276] [Server] Unix socket lock file is empty /var/run/mysqld/mysqld.sock.lock
[ERROR] [MY-010268] [Server] Unable to setup unix socket lock file.
```

检查容器配置和挂载：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker inspect "$MYSQL_CONTAINER" --format '{{json .Config}}\n{{json .HostConfig}}\n{{json .Mounts}}\n{{json .State}}'
```

原 MySQL 配置包含：

```ini
innodb_force_recovery=6
```

该参数表明 InnoDB 已损坏，`6` 是最高应急恢复等级，只适用于只读导出，不能用于正常生产运行。旧容器可写层另有残留空 socket 锁文件，导致启动中止。

## 检查存储与配置

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S df -h / /opt /var/lib/docker
printf '%s\n' "$SUDO_PASSWORD" | sudo -S sh -c 'df -i / /opt /var/lib/docker'
```

修复时数据目录为约 4.7 GiB，磁盘余量约 283 GiB。

## 第一次容器重建

为清除旧容器运行层内残留的 socket 锁文件，先强制重建容器。此命令不删除 bind mount 中的数据目录：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker compose -f "$MYSQL_APP/docker-compose.yml" up -d --force-recreate
```

确认 MySQL 仍在应急恢复模式：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker exec "$MYSQL_CONTAINER" mysql --protocol=socket -uroot -p"$MYSQL_ROOT_PASSWORD" -e 'SELECT VERSION() AS version, @@innodb_force_recovery AS innodb_force_recovery;'
```

结果为 `innodb_force_recovery = 6`。

## 创建备份

先创建包含权限和属主的物理备份，并备份原配置：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S sh -c 'backup=/opt/1panel/apps/mysql/mysql/data-backup-20260714-0309; test -d /opt/1panel/apps/mysql/mysql && test ! -e "$backup" && cp -a /opt/1panel/apps/mysql/mysql/data "$backup" && cp -a /opt/1panel/apps/mysql/mysql/conf/my.cnf /opt/1panel/apps/mysql/mysql/conf/my.cnf.backup-20260714-0309 && du -sh "$backup"'
```

在强制恢复模式下导出全部数据库、例程、事件和触发器：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S sh -c 'test -d /opt/1panel/apps/mysql/mysql && test ! -e /opt/1panel/apps/mysql/mysql/recovery-export-20260714-0616.sql && docker exec 1Panel-mysql-vVOO mysqldump --protocol=socket -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases --routines --events --triggers --hex-blob --single-transaction > /opt/1panel/apps/mysql/mysql/recovery-export-20260714-0616.sql && ls -lh /opt/1panel/apps/mysql/mysql/recovery-export-20260714-0616.sql'
```

逻辑导出文件为 `recovery-export-20260714-0616.sql`，大小约 61 MiB。

## 重建干净的数据库实例

从 `my.cnf` 中移除：

```ini
innodb_force_recovery=6
```

其余配置保持：

```ini
[mysqld]
host-cache-size=0
skip-name-resolve
datadir=/var/lib/mysql
socket=/var/run/mysqld/mysqld.sock
secure-file-priv=/var/lib/mysql-files
user=mysql
pid-file=/var/run/mysqld/mysqld.pid

[client]
socket=/var/run/mysqld/mysqld.sock

!includedir /etc/mysql/conf.d/
```

停止旧实例，保留旧数据目录，创建新的空数据目录，写入正常配置并重新启动：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S sh -c 'set -e; app=/opt/1panel/apps/mysql/mysql; test -d "$app"; test -f "$app/recovery-export-20260714-0616.sql"; docker compose -f "$app/docker-compose.yml" down; mv "$app/data" "$app/data-before-rebuild-20260714-0619"; mkdir "$app/data"; chown 999:999 "$app/data"; install -o root -g root -m 0644 /tmp/mysql-my.cnf-normal "$app/conf/my.cnf"; docker compose -f "$app/docker-compose.yml" up -d'
```

等待 MySQL 初始化完成：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S sh -c 'for i in $(seq 1 30); do if docker exec 1Panel-mysql-vVOO mysqladmin --protocol=socket -uroot -p"$MYSQL_ROOT_PASSWORD" ping >/dev/null 2>&1; then exit 0; fi; sleep 10; done; docker logs --tail 120 1Panel-mysql-vVOO; exit 1'
```

正常结果：

```text
mysqld is alive
```

## 导入备份

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S sh -c 'set -e; docker exec -i 1Panel-mysql-vVOO mysql --protocol=socket -uroot -p"$MYSQL_ROOT_PASSWORD" < /opt/1panel/apps/mysql/mysql/recovery-export-20260714-0616.sql; docker exec 1Panel-mysql-vVOO mysql --protocol=socket -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SELECT VERSION() AS version, @@innodb_force_recovery AS innodb_force_recovery, @@read_only AS read_only; SHOW DATABASES;"'
```

导入后应确认：

```text
innodb_force_recovery = 0
read_only = 0
```

## 功能与重启验证

执行临时读写测试并检查 Nextcloud 表数量：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker exec "$MYSQL_CONTAINER" mysql --protocol=socket -uroot -p"$MYSQL_ROOT_PASSWORD" -e "CREATE DATABASE mysql_recovery_verify; CREATE TABLE mysql_recovery_verify.t (id INT PRIMARY KEY); INSERT INTO mysql_recovery_verify.t VALUES (1); SELECT COUNT(*) AS persisted_write_count FROM mysql_recovery_verify.t; DROP DATABASE mysql_recovery_verify; SELECT COUNT(*) AS nextcloud_table_count FROM information_schema.tables WHERE table_schema = 'nextcloud';"
```

修复时结果：临时写入成功，`nextcloud` 有 167 张表。

重启后再次验证：

```bash
printf '%s\n' "$SUDO_PASSWORD" | sudo -S docker restart "$MYSQL_CONTAINER"

最终验证结果：容器为 `running`，退出码为 `0`，`innodb_force_recovery=0` 且 `read_only=0`。

## 保留的恢复文件

在确认 Nextcloud 长期正常前，不要删除：

```text
/opt/1panel/apps/mysql/mysql/data-backup-20260714-0309
/opt/1panel/apps/mysql/mysql/data-before-rebuild-20260714-0619
/opt/1panel/apps/mysql/mysql/recovery-export-20260714-0616.sql
/opt/1panel/apps/mysql/mysql/conf/my.cnf.backup-20260714-0309
```

建议至少保留 7 至 30 天，并把逻辑 SQL 备份复制至其他磁盘或远程存储。


mysql表故障修复

在本地仓库执行
`git remote -v`



```
origin  https://github.com/vmomenv/xxxx.git (fetch)
origin  https://github.com/vmomenv/xxxx.git (push)
```

如果显示http，则应当修改。

`git remote set-url origin git@github.com:vmomenv/xxxx.git`

检查：

`git remote -v`

正确应当显示
```
origin  git@github.com:vmomenv/xxxx.git (fetch)
origin  git@github.com:vmomenv/xxxx.git (push)
```