Flexisip 2.6.2 Docker Compose 部署指南

目标：用 Docker Compose 一键拉起 Flexisip 2.6.2 代理服务（自建镜像），完成注册验证与日常运维闭环。本文全部命令与回显来自 2026-10-25 实测（Docker 28.x + Compose v2，Ubuntu 24.04 基座）。

一、环境信息

软件版本：Flexisip 2.6.2-1（Belledonne 官方 APT 仓库 noble/stable，2026-10-25 实查）
基座镜像：ubuntu:24.04（官方镜像）
自建镜像：flexisip:2.6.2-ubuntu24.04（约 494MB）
Compose 项目名：flexisip-2.6.2-stack；容器名：flexisip-2.6.2-proxy
宿主机端口映射：5060/udp、5060/tcp、5061/tcp、3478/udp
持久化：配置文件只读挂载 + 日志目录挂载到宿主

二、镜像选型说明

2026-10-25 实查结论：Flexisip 没有可直接拉取的官方预构建容器镜像。

官方 GitLab 仓库仅提供「从源码构建镜像」的 docker/flex-from-src Dockerfile（docker build -t flexisip -f docker/flex-from-src .），未在公共 registry 发布成品镜像；
Docker Hub 搜索 flexisip 只有约 28 个第三方镜像，星数均为 0~1、多年未更新，不建议用于生产。

因此本文采用「Ubuntu 24.04 基座 + 官方 APT 仓库安装 bc-flexisip」的自建镜像方案：版本与裸机安装完全一致（同为官方 deb 2.6.2-1），构建过程透明可控。官方 Debian/Ubuntu 仓库同时是镜像内软件来源，升级时重建镜像即可。

三、前置条件

宿主机已安装 Docker 与 Docker Compose v2（docker compose version 能输出版本号即可）。
构建期需要访问 download.linphone.org（官方 APT 仓库）与 Ubuntu 官方源。
确认宿主机 5060/udp、5060/tcp、5061/tcp、3478/udp 未被占用：ss -lnup | grep -E '5060|3478'。
自建网络（示例用 flexisip-net，bridge 类型，子网按规划自选，如 10.89.74.0/24）。

四、部署步骤

4.1 项目目录结构

flexisip-compose/
├── Dockerfile            # 自建镜像定义
├── docker-compose.yml    # 编排文件
├── flexisip.conf         # 主配置（挂载进容器，只读）
└── data/
    └── log/              # 日志持久化目录（挂载到容器日志路径）

4.2 编写 Dockerfile

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
    && apt-get install -y --no-install-recommends wget gnupg ca-certificates libmariadb-dev iptables \
    && echo "deb [arch=amd64] https://download.linphone.org/snapshots/ubuntu noble stable" > /etc/apt/sources.list.d/belledonne.list \
    && wget -q https://download.linphone.org/snapshots/ubuntu/pubkey.gpg -O - | apt-key add - \
    && apt-get update \
    && apt-get install -y --no-install-recommends bc-flexisip \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# SIP UDP/TCP 5060、SIPS 5061、内置 STUN 3478/udp
EXPOSE 5060/udp 5060/tcp 5061/tcp 3478/udp

ENTRYPOINT ["/opt/belledonne-communications/bin/flexisip", "--server", "proxy", "-c", "/etc/flexisip/flexisip.conf"]

关键点解读：

libmariadb-dev：官方 Wiki 要求先装，否则 SQL 后端运行期报 Failed to find shared library for backend mysql；
iptables：Flexisip 启动时建立 DoS 防护链需要，缺了日志会刷 not found 报错；
ENTRYPOINT 直接以前台模式运行 flexisip（容器内无 systemd，不能用 systemctl）；--server proxy 指定代理角色，-c 指定配置文件；
apt-key 的 deprecated 警告仅提示性，不影响构建（新式 keyring 写法见《Ubuntu 24.04 安装 Flexisip 2.6.2 指南》4.1 节）。

4.3 生成默认配置 flexisip.conf

镜像构建后先临时跑一次生成默认配置（也可以从已装好的服务器拷贝）：

docker run --rm flexisip:2.6.2-ubuntu24.04 --dump-default all > flexisip.conf

生成的文件首行为 This is the default Flexisip (v2.6.2) configuration file，共 2762 行。默认配置即可启动（受理 localhost 域注册）；要服务自有域名，编辑 flexisip.conf 中 module::Registrar 段的 #reg-domains=localhost 为你的域名列表。

4.4 编写 docker-compose.yml

name: flexisip-2.6.2-stack

services:
  flexisip-proxy:
    build: .
    image: flexisip:2.6.2-ubuntu24.04
    container_name: flexisip-2.6.2-proxy
    hostname: flexisip-proxy
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    ports:
      - "5060:5060/udp"
      - "5060:5060/tcp"
      - "5061:5061/tcp"
      - "3478:3478/udp"
    volumes:
      - ./flexisip.conf:/etc/flexisip/flexisip.conf:ro
      - ./data/log:/var/opt/belledonne-communications/log
    networks:
      - flexisip-net

networks:
  flexisip-net:
    external: true

逐项解读：

name: flexisip-2.6.2-stack：显式项目名，避免多项目目录同名互删；
cap_add: NET_ADMIN：授予容器配置自身网络命名空间 iptables 的权限，消除 DoS 防护链报错（不加也能跑，但日志有 Permission denied 报错，见「常见问题」Q1）；
ports：SIP 信令 5060 必须同时映射 UDP 与 TCP（SIP 默认走 UDP，注册/呼叫都依赖它，漏掉 UDP 会导致客户端无响应）；3478/udp 是内置 STUN；
volumes：配置只读挂载（:ro），日志目录持久化到宿主 ./data/log。

4.5 构建并启动

docker network create -d bridge --subnet 10.89.74.0/24 flexisip-net   # 首次执行一次
docker compose build
docker compose up -d
docker compose ps

实测回显：

NAME                   IMAGE                        COMMAND                  SERVICE          CREATED         STATUS         PORTS
flexisip-2.6.2-proxy   flexisip:2.6.2-ubuntu24.04   "/opt/belledonne-com…"   flexisip-proxy   4 seconds ago   Up 4 seconds   0.0.0.0:3478->3478/udp, [::]:3478->3478/udp, 0.0.0.0:5060->5060/udp, [::]:5060->5060/udp, 0.0.0.0:5060-5061->5060-5061/tcp, [::]:5060-5061->5060-5061/tcp

查看启动日志确认服务拉起：

docker logs --tail 5 flexisip-2.6.2-proxy

日志中出现 Starting Flexisip-proxy server [version: 2.6.2] 即启动成功。

4.6 注册验证（经宿主机映射端口）

在宿主机上用 Python 发一条 REGISTER（域为默认受理的 localhost）：

python3 -c "
import socket
msg = \"REGISTER sip:localhost SIP/2.0\r\nVia: SIP/2.0/UDP 127.0.0.1:59998;branch=z9hG4bK-reg03;rport\r\nFrom: <sip:bob@localhost>;tag=3001\r\nTo: <sip:bob@localhost>\r\nCall-ID: reg-003@host\r\nCSeq: 1 REGISTER\r\nContact: <sip:bob@127.0.0.1:59998>\r\nExpires: 3600\r\nMax-Forwards: 5\r\nContent-Length: 0\r\n\r\n\"
s=socket.socket(socket.AF_INET, socket.SOCK_DGRAM); s.settimeout(3)
s.sendto(msg.encode(), (\"127.0.0.1\",5060))
print(s.recvfrom(4096)[0].decode())
"

实测回显（注意 received=10.89.74.1，即宿主机在容器网络中的地址，NAT 修正由 NatHelper 模块自动完成）：

SIP/2.0 200 Registration successful
Via: SIP/2.0/UDP 127.0.0.1:59998;branch=z9hG4bK-reg03;rport=51245;received=10.89.74.1
From: <sip:bob@localhost>;tag=3001
To: <sip:bob@localhost>;tag=vKcFD3e2aZFXN
Call-ID: reg-003@host
CSeq: 1 REGISTER
Contact: <sip:bob@10.89.74.1:51245>
Expires: 3600
Server: Flexisip/2.6.2 (sofia-sip-nta/2.0)
Supported: path, outbound
Content-Length: 0

进容器用管理 CLI 复核注册表：

docker exec flexisip-2.6.2-proxy python3 /opt/belledonne-communications/bin/flexisip_cli.py -p 1 REGISTRAR_DUMP

实测回显：

{
  "aors": [
    "bob@localhost"
  ]
}

⚠️ 注意：容器内必须加 -p 1——前台运行时没有 /var/run/flexisip-proxy.pid 文件，flexisip_cli.py 自动找 PID 会失败（error: could not find flexisip process pid），而前台进程恰是容器内 PID 1。

五、数据持久化说明

内容	容器内路径	宿主侧	说明
主配置	`/etc/flexisip/flexisip.conf`	`./flexisip.conf`（只读挂载）	改配置后 `docker compose restart` 生效
日志	`/var/opt/belledonne-communications/log`	`./data/log`	`flexisip-proxy.log` 等
注册库	内存（默认 internal 后端）	—	默认注册信息在内存，容器重建即清空；生产接 Redis/MySQL 后端见《Flexisip 2.6 配置参数详解》cluster 与 Registrar 段

六、环境变量表

Flexisip 本身不通过环境变量做配置（全部走 flexisip.conf 与 flexisip_cli.py CONFIG_SET 热改），镜像构建期仅用一个标准变量：

变量	作用域	值	说明
`DEBIAN_FRONTEND`	构建期	`noninteractive`	抑制 debconf 交互，Dockerfile 已内置

需要调整监听、域名、日志级别时，改 ./flexisip.conf 后重启容器即可。

七、配置参数说明

容器场景最常改的三处（完整参数表见《Flexisip 2.6 配置参数详解》）：

global/transports：默认 sip:*（全地址 UDP 5060）。要开 TCP/TLS 改为 sip:* sips:* 等组合，并准备 /etc/flexisip/tls/agent.pem 证书（可再挂一个卷）；
module::Registrar/reg-domains：默认 localhost，生产改成你的 SIP 域名（空格分隔）；
global/log-level：默认 error，排障改 debug（也可在线热改：flexisip_cli.py -p 1 CONFIG_SET global/log-level debug）。

八、配置文件挂载

配置以只读方式挂载：- ./flexisip.conf:/etc/flexisip/flexisip.conf:ro。修改宿主侧文件后需要重启进程生效（热改参数除外）：

docker compose restart

验证新配置已加载——以日志级别为例：

docker exec flexisip-2.6.2-proxy python3 /opt/belledonne-communications/bin/flexisip_cli.py -p 1 CONFIG_GET global/log-level

九、等价 docker run

不用 Compose 时的等价命令（仅供理解映射关系，生产建议仍用 Compose 管理）：

docker run -d \
  --name flexisip-2.6.2-proxy \
  --hostname flexisip-proxy \
  --restart unless-stopped \
  --cap-add NET_ADMIN \
  --network flexisip-net \
  -p 5060:5060/udp -p 5060:5060/tcp -p 5061:5061/tcp -p 3478:3478/udp \
  -v $PWD/flexisip.conf:/etc/flexisip/flexisip.conf:ro \
  -v $PWD/data/log:/var/opt/belledonne-communications/log \
  flexisip:2.6.2-ubuntu24.04

十、常用运维命令

docker compose ps                                   # 查看状态
docker compose logs -f                              # 跟踪日志
docker compose restart                              # 重启（改配置后）
docker compose down                                 # 停止并删除容器（保留镜像与 ./data）
docker exec flexisip-2.6.2-proxy python3 /opt/belledonne-communications/bin/flexisip_cli.py -p 1 REGISTRAR_DUMP   # 查注册表
docker exec -it flexisip-2.6.2-proxy bash           # 进容器排障

十一、常见问题

Q1：日志刷 iptables ... Permission denied (you must be root)？

Flexisip 启动时要为 DoS 防护建 iptables 链，容器默认无 NET_ADMIN 权限。在 compose 中加 cap_add: [NET_ADMIN] 后重建即可（本文 4.4 已含）。实测加权限后 docker exec flexisip-2.6.2-proxy iptables -L FLEXISIP -n 可见链已建立：

Chain FLEXISIP (1 references)
target     prot opt source               destination

残留的一条 No chain/target/match by that name 是首次启动「先 flush 后建链」的顺序提示，无害。

Q2：容器内跑 flexisip_cli.py 报 could not find flexisip process pid？

前台运行无 pidfile，加 -p 1 指定容器内 PID 1 即可（见 4.6）。

Q3：客户端 REGISTER 超时无响应？

依次排查：① compose 端口映射是否漏了 5060/udp（SIP 默认 UDP）；② REGISTER 的域是否为 reg-domains 受理的域（默认仅 localhost）；③ docker logs 开 debug 级别看消息是否到达模块链。

Q4：容器重建后注册信息丢失？

默认注册库在内存。需要持久化/多实例共享时，接 Redis（module::Registrar 的 db-implementation）或 MySQL，参数见《Flexisip 2.6 配置参数详解》。

十二、参考链接

官方安装指南（含仓库配置）：https://wiki.linphone.org/xwiki/wiki/public/view/Flexisip/Core%20servers/Installation/
官方仓库（含 docker/flex-from-src）：https://gitlab.linphone.org/BC/public/flexisip
配置参考：https://wiki.linphone.org/xwiki/wiki/public/view/Flexisip/Core%20servers/Configuration%20reference%20guide/