前言

本文适用于内网、涉密或无法访问外网的服务器环境。这类环境下,服务器无法直接通过 docker pull 从官方仓库拉取镜像,因此需要先在具备外网条件的机器上导出镜像文件,再导入目标服务器使用。

本文只覆盖 ZLMediaKit 的部署过程,默认目标服务器已经安装 Docker。文中将操作压缩到最少,并说明每处可以简化的原因。

目标环境

项目 版本 / 说明
操作系统 Ubuntu 24.04 LTS
Docker 26.x(已安装)
部署方式 Docker 容器,默认使用镜像内置配置

先确认架构一致:登录目标服务器执行 uname -m,确认是 x86_64 还是 aarch64。拉取镜像的机器与目标服务器架构必须一致,否则镜像导入后无法启动。


一、准备离线镜像包(在可访问外网的机器上操作,文末会准备master版本2026-11月份最新版本)

拉取并导出镜像,用一条命令完成:

docker pull zlmediakit/zlmediakit:master && docker save -o zlm-master-x86.tar.gz zlmediakit/zlmediakit:master

说明:docker save 依赖本地已有镜像,pull 成功后紧接着 save 即可,中间无需再单独 docker images 确认,所以合并为一条命令(&& 表示前一步成功才执行后一步)。镜像标签用 master(持续更新的主线),也可按需换成 latest 或 release。


二、上传并导入镜像(目标服务器)

第 1 步:把 tar 包上传到服务器(scp 或 SFTP 均可,目录以 /home/app 为例):

scp /path/to/your/zlmediakit-master.tar root@xx.xx.xx.xx:/home/app

第 2 步:在目标服务器上导入镜像:

docker load -i /home/app/zlm-master-x86.tar.gz

说明:导入成功后执行 docker images 应能看到 zlmediakit/zlmediakit:master,正常场景下可省略此确认,出错时再回头核对 tar 路径。


三、启动容器(以下两种方式二选一)

ZLMediaKit 镜像内置默认配置即可直接运行(RTMP 端口 1935、RTSP 554、HTTP 80),无需先准备配置文件,启动后就能推拉流。需要改端口、密钥时再走第五节。

方式一:docker run 命令

docker run -d --name zlmediakit --restart=always -p 1935:1935 -p 554:554 -p 8080:80 zlmediakit/zlmediakit:master

各参数含义:

参数 含义
-d 后台运行,不占用当前终端
--name zlmediakit 指定容器名称
--restart=always 容器退出或宿主机重启后自动拉起
-p 1935:1935 端口映射(宿主机:容器),1935 为 RTMP
-p 554:554 端口映射,554 为 RTSP
-p 8080:80 端口映射,8080 为宿主机 HTTP,对应容器内 80(HTTP API / HLS / HTTP-FLV)
zlmediakit/zlmediakit:master 使用的镜像及标签

方式二:docker-compose 编排

创建 docker-compose.yml:

version: "3.8"                               # 保留以兼容旧版 docker-compose
services:
  zlmediakit:                                # 服务名称
    image: zlmediakit/zlmediakit:master      # 镜像及标签
    container_name: zlmediakit               # 容器名称
    restart: always                          # 自动重启策略
    ports:                                   # 端口映射(宿主机:容器)
      - "1935:1935"                          # RTMP 推流/拉流
      - "554:554"                            # RTSP 拉流
      - "8080:80"                            # HTTP API / HLS / HTTP-FLV / WebSocket-FLV

在该文件所在目录执行:

docker compose up -d

说明:新版 Compose(v2,docker compose 空格分隔)已不要求 version 字段,会自动忽略;保留 version: "3.8" 是为了兼容旧版 docker-compose(连字符)工具,新老环境都能直接使用。

端口被占用的排查:若启动报错,先执行 ss -lntp | grep -E '1935|554|8080' 定位占用进程,可改用其他宿主机端口映射(如 -p 8081:80)规避,无需改动容器内端口。


四、服务验证

部署完成后,建议先推一路流再拉回来,确认链路真正打通(docker ps 显示 Up 只代表进程在跑,不代表端口通)。

# 推流:在能访问服务器的机器上,用 mp4 测试文件推流(-re 按实际速率,-stream_loop -1 循环)
ffmpeg -re -stream_loop -1 -i test.mp4 -c copy -f flv rtmp://服务器IP:1935/live/test

# 拉流验证:能输出编码、宽高即表示链路正常
ffprobe -v error -show_entries stream=codec_name,width,height -of json rtmp://服务器IP:1935/live/test

# 观察日志:同时出现 publish 与 play,说明推拉流闭环打通
docker logs -f zlmediakit | grep -E 'play|publish'

说明:-c copy 直接封装不转码,速度快;仅当源文件不是 h264 + aac 编码时才需改成 -vcodec h264 -acodec aac 转码。其他播放方式(RTSP、HTTP-FLV、HLS)见文末附录。


五、可选:自定义配置(需要改端口、密钥时才做)

默认配置能跑通,但存在两点隐患:API 密钥 secret 为公开默认值、端口可能与现有业务冲突。生产环境建议至少修改 secret。操作如下:

# 1. 从已运行的容器导出默认配置(若路径不对,先 docker exec zlmediakit sh -c "find / -name config.ini" 定位)
docker cp zlmediakit:/opt/media/conf/config.ini /home/app/zlmediakit/config.ini

# 2. 编辑配置,重点修改 [api] 段的 secret 为高强度随机字符串

# 3. 删除旧容器,重新启动并挂载配置
docker rm -f zlmediakit
docker run -d --name zlmediakit --restart=always \
  -p 1935:1935 -p 554:554 -p 8080:80 \
  -v /home/app/zlmediakit/config.ini:/opt/media/conf/config.ini \
  zlmediakit/zlmediakit:master

说明:这里直接用 docker cp 从正在运行的容器取配置,省去了「另起临时容器定位 + 拷贝 + 删临时容器」三步——因为容器本来就在运行,直接导出即可。使用 docker-compose 的话,把 -v 挂载对应写成 volumes: 段即可。


附录:其他播放地址与常见问题

其他拉流/播放方式(端口按上文映射,live/test 为流的应用名/流 ID):

ffplay rtsp://服务器IP:554/live/test                 # RTSP
ffplay http://服务器IP:8080/live/test.flv            # HTTP-FLV
ffplay http://服务器IP:8080/live/test/hls.m3u8       # HLS

常见问题:

现象 可能原因 处理方式
容器正常但拉不到流 防火墙 / 安全组未放行端口 放行 1935、554、8080;telnet 服务器IP 1935 判断可达性
端口被占用 多个服务共用一台机器 `ss -lntp
挂载配置不生效 容器内路径不对或目录权限问题 find / -name config.ini 确认真实路径;看日志有无 permission denied
推流失败 源文件编码不支持 ffprobe 确认编码,改用 -vcodec h264 -acodec aac 转码
断电重启后起不来 未设开机自启 加 --restart=always,docker restart 后 docker logs 确认