apiSQL网关 for Docker 离线安装和升级教程

《apiSQL网关 for Docker 离线安装和升级教程》

适用场景 ：内网环境、无外网访问权限的生产服务器、安全隔离网络环境下的 apiSQL 网关部署
核心优势：全程离线操作、高可用滚动升级、适配企业级安全合规要求

一、前言

在医疗、金融、政务、军工等高安全要求领域，生产环境通常与互联网物理隔离。传统通过 docker pull 拉取镜像的方式无法使用，必须采用离线部署方案。本文提供经过生产验证的完整流程，涵盖apiSQL网关镜像获取、传输、部署及升级过程的最佳实践。

二、环境准备

2.1 联网环境（镜像下载）

操作系统：支持 Linux 或 MacOS（包括 Apple Silicon 芯片）
Docker 版本：20.10.15 及以上（包含 Docker Desktop，需确保 Docker Engine ≥ 20.10.15 以上）
网络要求：需要稳定可用的互联网连接

2.2 离线环境（目标服务器部署）

操作系统：Linux 系统（支持 x86 和 ARM 架构，本文以 x86 为例）
Docker 要求：（Docker离线安装简易指南）
- Docker 20.10+
- 内置Docker Compose命令

三、镜像准备（联网环境操作）

3.1 拉取 x86_64 架构镜像

bash 复制代码

# 显式指定平台，确保获取 x86_64 镜像
docker pull --platform linux/amd64 registry.cn-hangzhou.aliyuncs.com/ymlib/apisql-gateway2:latest

🔍 为什么必须指定 --platform ？

由于镜像仓库包含多架构镜像清单，x86 架构需使用 linux/amd64 ，ARM 架构则需 linux/arm64。

3.2 （可选）验证镜像架构

bash 复制代码

docker inspect registry.cn-hangzhou.aliyuncs.com/ymlib/apisql-gateway2:latest | grep -A 2 '"Architecture"'

预期输出：

json 复制代码

        "Architecture": "amd64",
        "Os": "linux",
        "Size": 1010173298,

3.3 保存为压缩镜像包

保存镜像并生成压缩包（约364MB），根据机器配置不同，此过程可能需要1分钟以上：

bash 复制代码

docker save registry.cn-hangzhou.aliyuncs.com/ymlib/apisql-gateway2:latest | gzip > apisql-gateway2-latest-amd64.tar.gz

四、离线环境部署

4.1 传输镜像包

将镜像包上传至目标服务器

bash 复制代码

# 示例：通过内网 SCP 传输 至指定服务器 /root 目录
scp apisql-gateway2-latest-amd64.tar.gz root@192.168.10.100:/root

4.2 导入镜像

进入目标服务器镜像目录后导入：

bash 复制代码

# Docker 20.10+ 原生支持直接加载 .tar.gz
docker load -i apisql-gateway2-latest-amd64.tar.gz

✅ 验证导入成功：

bash 复制代码

docker images | grep apisql-gateway2
#输出示例：
registry.cn-hangzhou.aliyuncs.com/ymlib/apisql-gateway2   latest       0b45007354eb   38 hours ago    1.01GB

4.3 首次安装网关，编辑docker-compose.yml（升级用户可跳过此步骤）

创建目录并编辑配置文件：

bash 复制代码

mkdir /opt/apisql-gw
cd /opt/apisql-gw
vi  `docker-compose.yml`

从私有部署的 apiSQL 平台 ->安装网关界面获取您的Endpoint、ID和Token，并修改以下配置：

yaml 复制代码

version: "3.8"

services:
  apisql_gateway:
    image: registry.cn-hangzhou.aliyuncs.com/ymlib/apisql-gateway2:latest
    container_name: apisql-gw
    restart: unless-stopped
    environment: 
      - APISQLGW_ENDPOINT=http://192.168.2.18:8088
      - APISQLGW_NODE_ID=1578612931166209
      - APISQLGW_NODE_TOKEN=3A06385860
      - APISQLGW_LOG_LEVEL=debug
      - APISQLGW_LOG_CONSOLE=false
      - NODE_OPTIONS=--max-old-space-size=8192
    volumes:
      - ./logs:/apps/gw2/logs

4.4 启动服务

bash 复制代码

# 停止容器（升级用户先执行此步骤）
docker-compose down

# 后台启动
docker-compose up -d

# 查看日志
docker-compose logs -f

五、离线升级流程（零停机方案）

专业版和企业版用户（网关集群≥2节点）可采用滚动升级：

依次升级各个网关节点
升级过程中始终保持至少一个网关节点在线运行

优势：

实现零停机升级
保障API服务高可用
升级单个容器时，其他节点仍可处理请求

六、总结最佳实践

✅ 核心要点

精准拉取 ：始终使用 --platform linux/amd64 确保架构正确
高效传输 ：.tar.gz 压缩包体积减少 60%+，docker load 原生支持无需解压
配置即代码 ：推荐使用 docker-compose.yml 部署，方便后续管理和运维
高可用：通过部署apiSQL网关集群，实现API接口服务零中断，为业务系统提供持续稳定的运行保障

参考：