# 隔离测试环境增量更新说明

本文档用于后续只更新部分 EMP 服务镜像，不再每次全量打包中间件和所有服务。

## 一、适用场景

适用于只更新以下应用服务中的一个或多个：

| 简写 | Compose 服务 | 镜像 |
| --- | --- | --- |
| gateway | emp-gateway | emp-test/emp-gateway |
| auth | emp-auth | emp-test/emp-auth |
| monitor | emp-monitor | emp-test/emp-monitor |
| data | emp-data | emp-test/emp-data |
| pdf | emp-pdf | emp-test/emp-pdf |
| ws | emp-ws | emp-test/emp-ws |
| admin | emp-admin | emp-test/emp-admin |

中间件 MySQL、Redis、Kafka、TDengine、Nacos 不走增量更新包。

## 二、构建机生成增量包

进入部署脚本目录：

```bash
cd /home/git/emp_test_deploy/isolated
```

只更新 `admin` 和 `monitor`：

```bash
EMP_ROOT=/home/git/emp \
IMAGE_NAMESPACE=emp-test \
./build-update.sh admin monitor
```

生成文件在：

```bash
dist/emp-test-update-<时间戳>-admin-monitor.tar.gz
```

也可以更新其他服务：

```bash
# 只更新前端
EMP_ROOT=/home/git/emp IMAGE_NAMESPACE=emp-test ./build-update.sh admin

# 只更新数据服务
EMP_ROOT=/home/git/emp IMAGE_NAMESPACE=emp-test ./build-update.sh data

# 更新模拟器 / WebSocket
EMP_ROOT=/home/git/emp IMAGE_NAMESPACE=emp-test ./build-update.sh ws

# 更新 PDF 服务
EMP_ROOT=/home/git/emp IMAGE_NAMESPACE=emp-test ./build-update.sh pdf
```

如果镜像已经在本机构建好，只想重新打包已有镜像：

```bash
EMP_ROOT=/home/git/emp \
IMAGE_NAMESPACE=emp-test \
SKIP_BUILD=1 \
./build-update.sh admin monitor
```

## 三、传输到甲方服务器

将增量包传到甲方服务器任意目录，例如：

```bash
/home/admin-x99/emp-test/update/emp-test-update-20260602153000-admin-monitor.tar.gz
```

## 四、甲方服务器应用增量包

进入服务器：

```bash
cd /home/admin-x99/emp-test
mkdir -p update-runtime
tar -xzf update/emp-test-update-20260602153000-admin-monitor.tar.gz \
  -C update-runtime \
  --strip-components=1
cd update-runtime
```

执行增量更新：

```bash
bash apply-update.sh
```

脚本会优先使用当前目录下的 `.env`、`docker-compose.yml`；如果当前目录没有，会自动查找 `../runtime/` 和 `/home/admin-x99/emp-test/runtime/` 下的运行配置。

脚本会自动执行：

```bash
docker load -i images.tar
docker compose --env-file .env -f docker-compose.yml -p emp-test \
  up -d --no-deps --force-recreate emp-admin emp-monitor
```

如果当前目录没有 `.env` 和 `docker-compose.yml`，可以显式指定运行环境目录中的文件：

```bash
PROJECT_NAME=emp-test \
ENV_FILE=/home/admin-x99/emp-test/runtime/.env \
COMPOSE_FILE=/home/admin-x99/emp-test/runtime/docker-compose.yml \
bash apply-update.sh
```

也可以手动指定更新服务，覆盖包内 `services.txt`：

```bash
PROJECT_NAME=emp-test \
ENV_FILE=/home/admin-x99/emp-test/runtime/.env \
COMPOSE_FILE=/home/admin-x99/emp-test/runtime/docker-compose.yml \
bash apply-update.sh emp-admin emp-monitor
```

## 五、验证

查看服务状态：

```bash
cd /home/admin-x99/emp-test/runtime
docker compose --env-file .env -f docker-compose.yml -p emp-test ps emp-admin emp-monitor
```

查看后端日志：

```bash
docker compose --env-file .env -f docker-compose.yml -p emp-test logs --tail=100 emp-monitor
```

验证前端：

```bash
curl -I http://127.0.0.1:37361
```

## 六、注意事项

1. 增量更新默认同时打 `latest` 和时间戳 tag。
2. 当前测试环境 `.env` 建议继续使用 `IMAGE_TAG=latest`，不要为了增量包修改成时间戳。
3. 如果把 `.env` 的 `IMAGE_TAG` 改成某个新时间戳，但只传了部分服务镜像，其他服务会因为缺少该 tag 而无法重建。
4. 如果修改了 `docker-compose.yml`、`.env.example`、中间件初始化逻辑，建议重新全量打包或单独同步配置文件。
5. 数据库结构变更不包含在镜像增量包中，需要单独执行 SQL 迁移。

## 七、PDF 导出故障排查

报错：

```text
PDF导出失败: I/O error on GET request for "http://emp-pdf:3100/pdf": Connection refused
```

含义：`emp-monitor` 已经访问到 Docker 内网地址 `emp-pdf:3100`，但 PDF 服务端口没有进程监听，常见原因是 `emp-pdf` 容器未启动、启动后退出、正在重启，或 Node 服务未正常监听 3100。

新版 `docker-compose.yml` 已给 `emp-pdf` 增加健康检查，并让 `emp-monitor` 等待 `emp-pdf` 可访问后再启动。健康检查访问 `/pdf`，400 也算通过，因为不带 url 参数时返回 400 代表服务已正常监听。若服务器仍使用旧 compose，需要先同步新的 `docker-compose.yml` 或按下面命令手动重启 PDF 服务。

先看容器状态：

```bash
cd /home/admin-x99/emp-test/runtime
docker compose --env-file .env -f docker-compose.yml -p emp-test ps emp-pdf emp-monitor
```

查看 PDF 服务日志：

```bash
docker compose --env-file .env -f docker-compose.yml -p emp-test logs --tail=200 emp-pdf
```

在 PDF 容器内检查 PDF 服务是否监听：

```bash
docker compose --env-file .env -f docker-compose.yml -p emp-test exec emp-pdf \
  node -e "require('http').get('http://127.0.0.1:3100/pdf', r => { console.log(r.statusCode); r.resume(); process.exit(r.statusCode < 500 ? 0 : 1) }).on('error', e => { console.error(e.message); process.exit(1) })"
```

在同一个 Docker 网络里检查 `emp-monitor` 到 `emp-pdf` 的访问：

```bash
docker compose --env-file .env -f docker-compose.yml -p emp-test exec emp-monitor \
  sh -lc "curl -i http://emp-pdf:3100/pdf || wget -S -O- http://emp-pdf:3100/pdf"
```

如果 `emp-pdf` 未运行或健康检查失败，先重启 PDF 服务：

```bash
docker compose --env-file .env -f docker-compose.yml -p emp-test up -d --no-deps --force-recreate emp-pdf
```

再重启 monitor，使其重新调用可用的 PDF 服务：

```bash
docker compose --env-file .env -f docker-compose.yml -p emp-test restart emp-monitor
```

如果日志中出现 Chromium/Puppeteer 相关错误，重新构建并增量更新 `pdf`：

```bash
EMP_ROOT=/home/git/emp IMAGE_NAMESPACE=emp-test ./build-update.sh pdf
```