企业官网建设流程全解析

OpenIM 离线部署完整指南：内网环境镜像准备、传输与 Docker Compose 落地

【免费下载链接】open-im-serverIM Chat OpenClaw项目地址: https://gitcode.com/gh_mirrors/op/open-im-server

本指南以 OpenIM（open-im-server）官方离线部署设计文档（docs/contrib/offline-deployment.md）为核心骨架，完整讲解在无外网/受限网络中部署 OpenIM 的全过程：从基础依赖镜像与 OpenIM 业务镜像的选型、拉取、导出，到代码获取、scp传输、镜像导入，最后通过 Docker Compose 一键启动整套 IM 服务。读完本文，你将掌握一套可复制的离线部署 SOP，并理解 OpenIM 的镜像版本管理、仓库源选择与组件版本兼容策略。

1. 离线部署总体思路

OpenIM 是一套由多个微服务构成的即时通讯服务器，官方推荐通过 Docker 镜像完成部署。离线部署的核心思想只有一句话：在有外网的机器上把所需镜像全部拉取并导出为 tar 包，连同部署代码一起拷入内网，再在内网机器上导入镜像并启动容器。

整个流程可分为四个阶段：

1. 镜像准备：按需拉取基础组件镜像（Kafka、Redis、MongoDB、ZooKeeper、MinIO 等）与 OpenIM 业务镜像（server、chat、web、admin），可选拉取监控组件镜像；
2. 导出与传输：将镜像docker save为 tar 文件，把部署仓库代码一并通过scp、U 盘、移动硬盘等方式送入内网；
3. 导入：在内网服务器上docker load导入所有镜像；
4. 部署：使用 openim-docker 仓库的make init初始化配置，docker compose up -d启动全部服务并验证。

[!NOTE] 官方文档特别提示：由于 Windows 与 Linux 换行符的差异，请不要在 Windows 上 clone 仓库后再用 scp 同步到 Linux，否则可能导致脚本执行异常，应在 Linux 环境直接 clone 或下载 Release 压缩包。

2. 基础镜像清单与拉取

2.1 必需的基础镜像及版本

离线部署至少需要准备以下基础镜像（版本号来自官方离线部署文档，请与部署目标版本保持一致）：

[!IMPORTANT]关于 MySQL 的重要说明：OpenIM 自 v3.5.0（release-v3.5 分支）起已移除 MySQL 组件，因此 v3.5.0 及以上版本的离线部署不再需要 MySQL。官方文档给出的命令中虽保留了mariadb:10.6的拉取项，但这仅面向更早版本的部署需求，使用 v3.5.0+ 时无需准备。

2.2 拉取基础镜像命令

在外网机器上执行：

docker pull bitnami/kafka:3.5.1 docker pull redis:7.0.0 docker pull mongo:6.0.2 docker pull mariadb:10.6 docker pull bitnami/zookeeper:3.8 docker pull minio/minio:2024-01-11T07-46-16Z

2.3 可选的 OpenIM 业务镜像

如果还需要安装更多 IM 组件，可准备以下镜像（<version-name>替换为目标版本，版本策略详见本文第 4 节及 docs/contrib/images.md）：

• ghcr.io/openimsdk/openim-web:<version-name>
• ghcr.io/openimsdk/openim-admin:<version-name>
• ghcr.io/openimsdk/openim-chat:<version-name>
• ghcr.io/openimsdk/openim-server:<version-name>

2.4 可选的监控组件镜像

如需在内网同时部署监控告警体系（Prometheus + Alertmanager + Grafana + Node Exporter），准备以下镜像：

拉取命令：

docker pull prom/prometheus:v2.48.1 docker pull prom/alertmanager:v0.23.0 docker pull grafana/grafana:10.2.2 docker pull bitnami/node-exporter:1.7.0

3. OpenIM 业务镜像的拉取

OpenIM 的 Docker 镜像与 GitHub 上的 tag 版本一一对应：每发布一个新版本并打 tag，CI 自动化流程就会把对应镜像推送到多个镜像平台。官方强烈推荐使用ghcr.io作为部署镜像源。

按镜像类别分别执行：

# OpenIM Server（IM 服务端核心） docker pull ghcr.io/openimsdk/openim-server:<version-name> # OpenIM Chat（聊天业务层） docker pull ghcr.io/openimsdk/openim-chat:<version-name> # OpenIM Web（Web 前端） docker pull ghcr.io/openimsdk/openim-web:<version-name> # OpenIM Admin（管理后台前端） docker pull ghcr.io/openimsdk/openim-admin:<version-name>

[!TIP] 关于 OpenIM 镜像版本管理与存储策略的详细说明（含 server/chat 版本对应关系），可查阅 docs/contrib/version.md。

3.1 镜像版本命名规则（以 openim-server 为例）

依据 docs/contrib/images.md，镜像遵循语义化版本 2.0.0 策略。例如给仓库打上v3.5.0tag 后，CI 会自动发布以下镜像 tag：

• openim-server:3
• openim-server:3.5
• openim-server:3.5.0
• openim-server:v3.5.0
• openim-server:latest
• openim-server:sha-e0244d9（基于 commit SHA 的唯一 tag）

其中只有sha-<commit>形式的 tag 是绝对唯一的，v3.5.0与3.5.0也保持相对唯一性。部分镜像还提供多架构（multi-arch）支持，可按OS / Arch选择适合当前服务器架构的镜像。

4. 镜像仓库源与版本选择

4.1 可选的镜像仓库源

OpenIM 镜像托管在三个平台，可根据网络环境选择：

例如从不同源拉取openim-server:latest：

# GitHub docker pull ghcr.io/openimsdk/openim-server:latest # 阿里云（大陆推荐） docker pull registry.cn-hangzhou.aliyuncs.com/openimsdk/openim-server:latest # Docker Hub docker pull docker.io/openim/openim-server:latest

4.2 版本类型选择

部署前需要确定镜像版本，官方提供三类选择：

• 稳定版（Stable）：如release-v3.2（也可以是 3.1、3.3 等 release 分支），适合生产环境；
• 最新版（Latest）：latest，跟随最新发布；
• main 分支最新版：main，对应主分支最新代码，更新频繁、可能包含不稳定特性。

依据 docs/contrib/version.md，OpenIM 采用MAJOR.MINOR.PATCH语义化版本：MAJOR表示不兼容的 API 变更，MINOR表示向后兼容的新功能，PATCH表示向后兼容的缺陷修复。main分支承载最新特性（可能不稳定），每次重大发布都会派生出如release-v3.1这样的稳定分支，tag（如v3.1.0）则用于锁定不可变的具体版本。

4.3 组件版本兼容（Version Skew）策略

离线部署时若混合使用不同版本组件，请参考以下兼容约束（详见 docs/contrib/version.md）：

• HA 集群中，最新与最旧的openim-api实例必须处于同一个 minor 版本内（例如同为 v3.3 与 v3.2，不能跨两个 minor）；
• 所有openim-rpc-*组件不得新于 openim-api，最多可比 openim-api 旧一个 minor 版本；
• 其他服务（openim-msggateway、openim-cmdutils、openim-crontask等）同样不得新于 openim-api，建议与 openim-api 的 minor 版本保持一致，最多允许旧一个 minor 以便滚动升级。

因此，离线环境准备镜像时，建议整套组件（server、chat、web、admin）统一选取同一版本线，避免因版本错配导致服务间通信异常。

5. 离线部署七步走

第 1 步：拉取全部所需镜像

在外网机器上，按第 2、3 节命令逐一docker pull所有需要的镜像（基础组件 + OpenIM 业务镜像 + 可选监控镜像）。

第 2 步：导出镜像为 tar 文件

# 导出单个镜像 docker save -o <tar-file-name>.tar <image-name> # 一次性导出当前机器上的所有镜像 docker save -o <tar-file-name>.tar $(docker images -q)

导出的 tar 包即离线介质，建议按镜像分别命名以便内网逐个导入与校验。

第 3 步：获取部署代码

克隆 OpenIM 的 Docker 部署仓库：

git clone https://github.com/openimsdk/openim-docker.git

也可以直接下载 openim-docker 的 Releases 版本压缩包。再次提醒：避免在 Windows 上 clone 后 scp 到 Linux，换行符差异会导致脚本运行异常。

第 4 步：传输文件到内网

将镜像 tar 包与部署代码通过scp传送到内网服务器：

scp <tar-file-name>.tar user@remote-ip:/path/on/remote/server

也可选择移动硬盘、U 盘等物理介质拷贝，具体以目标机器的可达性为准。

第 5 步：在内网导入镜像

# 导入单个镜像包 docker load -i <tar-file-name>.tar

如果一次性拷贝了多个 tar 包，可用快捷命令循环导入当前目录下所有包：

for i in `ls ./`; do docker load -i $i; done

导入完成后可执行docker images确认镜像已就绪。

第 6 步：进入部署目录并初始化

进入openim-docker仓库目录，先按仓库 README 的说明准备部署环境。

第 7 步：使用 Docker Compose 启动

export OPENIM_IP="your ip" # 设置本机 IP make init # 初始化配置（生成 .env 与 config 文件） docker compose up -d # 后台启动全部服务 docker compose ps # 验证各服务运行状态

Note：如果使用 Docker 20 之前的旧版本，请先自行安装docker-compose独立工具，并相应调整命令为docker-compose。

6. 部署配置关键点（内网环境必读）

6.1OPENIM_IP环境变量

export OPENIM_IP="your ip"用于指定 API 服务对外地址。依据 docs/contrib/environment.md：如果服务器有公网 IP，会自动获取；内网部署时应显式设置内网 IP。客户端（App / Web）正是通过该地址访问 API 与 WebSocket 服务的，务必设置为客户端可达的地址。

6.2 镜像源切换：.env中的IMAGE_REGISTRY

执行make init后会生成.env文件，其中包含镜像仓库源配置（默认ghcr.io/openimsdk）。内网或大陆环境部署时，可注释掉当前IMAGE_REGISTRY并切换为阿里云源，以匹配离线镜像包的来源或提升拉取速度：

# 选择镜像地址：GitHub (ghcr.io/openimsdk)、Docker Hub (openim) # 或阿里云 (registry.cn-hangzhou.aliyuncs.com/openimsdk) # 取消下面三项中一项的注释。中国用户推荐阿里云。 # IMAGE_REGISTRY="ghcr.io/openimsdk" # IMAGE_REGISTRY="openim" IMAGE_REGISTRY="registry.cn-hangzhou.aliyuncs.com/openimsdk"

[!IMPORTANT]离线部署中，IMAGE_REGISTRY的值必须与内网docker load的镜像实际来源保持一致。例如你用阿里云源拉取并导出了镜像，.env中应保持阿里云源配置，避免 Compose 启动时去不存在的仓库重新拉取。

6.3 Compose 服务构成与默认凭据

open-im-server 仓库根目录的 docker-compose.yml 展示了 OpenIM 依赖的完整服务栈：mongodb、redis、etcd、kafka、minio、openim-web-front，以及可选 profilem下的 prometheus、alertmanager、grafana、node-exporter。各基础组件的镜像均通过环境变量注入（如${MONGO_IMAGE}、${REDIS_IMAGE}、${KAFKA_IMAGE}、${MINIO_IMAGE}），这些变量在make init生成的.env中定义。

Compose 中的默认凭据（生产环境务必修改，且密码至少 8 位、不允许特殊字符，参见 docs/contrib/environment.md）：

常用端口映射示例（见 docker-compose.yml）：

6.4 配置文件初始化机制

make init实际执行的是scripts/init_config.sh（相关说明见 docs/contrib/init-config.md），它会基于模板渲染生成.env与config.yaml等配置文件。open-im-server 仓库还提供了各服务的配置模板目录 config/，例如 config/openim-api.yml、config/kafka.yml、config/minio.yml、config/mongodb.yml 等，服务二进制文件清单见 start-config.yml。在离线环境中这些模板同样可随部署代码一并拷入内网，按需调整后再启动。

7. 部署验证与常见问题

7.1 验证手段

• docker compose ps：确认所有容器状态为Up；
• docker images：确认全部镜像已导入；
• 通过OPENIM_IP对应端口访问 OpenIM Web（11001）与 API 服务，验证链路连通。

7.2 常见问题速查

7.3 参考与延伸阅读

• 本指南对应的官方设计文档：docs/contrib/offline-deployment.md；
• 镜像管理策略与多源拉取指南：docs/contrib/images.md；
• 版本、分支与 tag 管理策略：docs/contrib/version.md；
• 环境变量与配置项总表：docs/contrib/environment.md；
• 配置初始化机制：docs/contrib/init-config.md；
• 官方离线部署文档中还引用了 openimsdk 社区关于离线部署相关议题（issue #432、#474）的讨论记录，可在社区中查阅以获得更丰富的实践反馈。

按照上述七个步骤，即可在完全隔离的内网环境中完成 OpenIM 全栈部署；在此基础上，可将镜像包与配置模板固化为一套内部标准件，实现多次、批量、可复现的离线交付。

【免费下载链接】open-im-serverIM Chat OpenClaw项目地址: https://gitcode.com/gh_mirrors/op/open-im-server