前言
本文适用于内网、涉密或无法访问外网的服务器环境。这类环境下,服务器无法直接通过 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 确认 |