Ubuntu 22.04 安装 openSIPS 4.0 指南

目标：面向在 Ubuntu 22.04 服务器上部署 SIP 路由服务的运维工程师，提供 openSIPS 4.0 的两条完整安装路径——官方 APT 仓库在线安装与 .deb 依赖闭包离线安装，覆盖版本选型、systemd 服务管理、监听地址配置、SIP 连通性验证、升级降级与版本锁定、卸载清理全流程，所有命令与回显均为实测。

一、环境信息

本章列出本次安装实测所用的环境信息，后续章节的全部命令与回显均基于该环境，读者在同等环境下操作应得到一致的输出。

项目	取值
操作系统	Ubuntu 22.04.5 LTS
系统架构	x86_64
openSIPS 版本	4.0.2-1（官方 APT 仓库当前最新候选版本）
方案 A 演示服务器 IP	10.89.62.3（内网地址）
方案 B 演示服务器 IP	10.89.62.6（内网地址，与方案 A 的服务器相互独立）
SIP 探测客户端 IP	10.89.62.4（内网地址，见第七章）
SIP 监听端口	UDP/TCP 5060
服务管理方式	systemd

确认系统版本的实测命令与回显：

cat /etc/os-release | grep PRETTY_NAME && uname -m

PRETTY_NAME="Ubuntu 22.04.5 LTS"
x86_64

二、版本选型与前置条件

2.1 版本选择

openSIPS 当前并行维护两条稳定线：4.0 标准稳定线与 3.6 LTS（长期支持）线，两者都通过官方 APT 仓库按发行版代号分发，仓库组件名分别为 4.0-releases 与 3.6-releases。两条线的定位差异、4.0 大版本的核心变化（TCP/TLS 多线程重构、动态 TM 分支等）在《openSIPS 4.0 介绍与选型指南》中已详细展开。

本文选择 4.0 线安装：APT 仓库中 4.0 线当前最新小版本为 4.0.2（第三章 3.4 节的版本表可证实仓库中同时保留 4.0.0/4.0.1/4.0.2 三个小版本）。生产环境若求保守，可将仓库源中的组件名换成 3.6-releases，安装步骤与本文完全一致。

2.2 前置条件

开始安装前确认以下条件：

拥有 root 权限（本文所有命令以 root 执行）；
在线安装（方案 A）：服务器能够访问 archive.ubuntu.com 与 apt.opensips.org；
离线安装（方案 B）：另需一台同版本（Ubuntu 22.04）且能联网的下载机，下载机也需先完成 3.1 与 3.2 节的仓库配置；
方案 A 与方案 B 各自独立成篇，读者按需选其一即可，二者在同一台服务器上不要混用。

三、方案 A：在线安装（官方 APT 仓库）

本章在 IP 为 10.89.62.3 的服务器上，从官方 APT 仓库完成 openSIPS 4.0.2 的安装。流程为：导入签名密钥 → 配置仓库源 → 刷新索引 → 确认版本 → 安装 → 验证。

3.1 导入官方签名密钥

APT 通过 GPG 密钥校验仓库内软件包的来源完整性，因此先下载官方签名密钥并放到密钥环目录：

curl -fsSL https://apt.opensips.org/opensips-org.gpg -o /usr/share/keyrings/opensips-org.gpg

命令成功时无输出（-f 参数在 HTTP 错误时会使 curl 以非零状态退出）。导入后校验密钥指纹：

gpg --show-keys /usr/share/keyrings/opensips-org.gpg

gpg: directory '/root/.gnupg' created
gpg: keybox '/root/.gnupg/pubring.kbx' created
pub   rsa4096 2016-05-10 [SC]
      6173E83AE3161724CC8A73F781CE21E7049AD65B
uid                      OpenSIPS Project <info@opensips.org>

前两行是 root 用户首次运行 gpg 时自动初始化密钥环的提示，属正常输出。关键信息是指纹 6173E83AE3161724CC8A73F781CE21E7049AD65B，uid 为 OpenSIPS Project <info@opensips.org>，与官方一致即导入成功。

⚠️ 排障提示：网上部分旧教程使用的密钥地址是 https://apt.opensips.org/public.asc，该路径已失效，实测返回 404：
HTTP/2 404
date: Mon, 26 Oct 2026 10:35:29 GMT
content-type: text/html
当前有效路径为本文所用的 opensips-org.gpg。若照抄旧教程遇到 404，换用本文路径即可。

3.2 配置 APT 仓库源

新建仓库定义文件 /etc/apt/sources.list.d/opensips.list，写入以下一行内容（发行版代号为 jammy，对应 Ubuntu 22.04；组件为 4.0-releases）：

deb [signed-by=/usr/share/keyrings/opensips-org.gpg] https://apt.opensips.org jammy 4.0-releases

写入后确认文件内容：

cat /etc/apt/sources.list.d/opensips.list

deb [signed-by=/usr/share/keyrings/opensips-org.gpg] https://apt.opensips.org jammy 4.0-releases

signed-by 指定用 3.1 节导入的密钥校验该仓库，避免全局信任。

3.3 刷新软件源索引

apt-get update

Hit:1 http://archive.ubuntu.com/ubuntu jammy InRelease
Hit:2 http://security.ubuntu.com/ubuntu jammy-security InRelease
Hit:3 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:4 https://apt.opensips.org jammy InRelease
Hit:5 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Reading package lists...

第 4 行 Hit:4 https://apt.opensips.org jammy InRelease 表明 openSIPS 仓库索引已成功同步；若此处报 GPG 错误，回到 3.1 节检查密钥路径与文件位置。

3.4 确认候选版本

安装前查看仓库中可用的版本及将安装的候选版本：

apt-cache policy opensips

opensips:
  Installed: (none)
  Candidate: 4.0.2-1
  Version table:
     4.0.2-1 500
        500 https://apt.opensips.org jammy/4.0-releases amd64 Packages
     4.0.1-1 500
        500 https://apt.opensips.org jammy/4.0-releases amd64 Packages
     4.0.0-1 500
        500 https://apt.opensips.org jammy/4.0-releases amd64 Packages

关键信息：Installed: (none) 表示尚未安装；Candidate: 4.0.2-1 表示执行安装将得到 4.0.2；版本表列出 4.0 稳定线在仓库中的全部三个小版本，这也是第八章降级操作的依据。

3.5 执行安装

apt-get install -y opensips

Reading package lists...
Building dependency tree...
Reading state information...
The following additional packages will be installed:
  python-is-python3
Suggested packages:
  opensips-auth-jwt-module opensips-auth-modules opensips-auth-web3-module
  opensips-berkeley-module opensips-carrierroute-module
  opensips-cgrates-module opensips-compression-module opensips-cpl-module
  opensips-dbhttp-module opensips-dialplan-module opensips-diameter-module
  opensips-emergency-module opensips-geoip-module opensips-http-modules
  opensips-identity-module opensips-ipsec-module opensips-jabber-module
  opensips-json-module opensips-kafka-module opensips-ldap-modules
  opensips-lua-module opensips-memcached-module opensips-mongodb-module
  opensips-msrp-modules opensips-mysql-module opensips-opentelemetry-module
  opensips-perl-modules opensips-postgres-module opensips-presence-modules
  opensips-prometheus-module opensips-python-module opensips-rabbitmq-modules
  opensips-radius-modules opensips-redis-module opensips-regex-module
  opensips-restclient-module opensips-sctp-module opensips-siprec-module
  opensips-snmpstats-module opensips-sqlite-module opensips-stir-shaken-module
  opensips-tls-module opensips-tls-openssl-module opensips-tls-wolfssl-module
  opensips-tlsmgm-module opensips-unixodbc-module opensips-uuid-module
  opensips-wss-module opensips-xml-module opensips-xmlrpc-module
  opensips-xmpp-module
The following NEW packages will be installed:
  opensips python-is-python3
0 upgraded, 2 newly installed, 0 to remove and 2 not upgraded.
Need to get 4402 kB of archives.
After this operation, 16.8 MB of additional disk space will be used.
Get:1 http://archive.ubuntu.com/ubuntu jammy/main amd64 python-is-python3 all 3.9.2-2 [2788 B]
Get:2 https://apt.opensips.org jammy/4.0-releases amd64 opensips amd64 4.0.2-1 [4399 kB]
debconf: delaying package configuration, since apt-utils is not installed
Fetched 4402 kB in 4s (1212 kB/s)
Selecting previously unselected package python-is-python3.
(Reading database ... (Reading database ... 5%(Reading database ... 10%(Reading database ... 15%(Reading database ... 20%(Reading database ... 25%(Reading database ... 30%(Reading database ... 35%(Reading database ... 40%(Reading database ... 45%(Reading database ... 50%(Reading database ... 55%(Reading database ... 60%(Reading database ... 65%(Reading database ... 70%(Reading database ... 75%(Reading database ... 80%(Reading database ... 85%(Reading database ... 90%(Reading database ... 95%(Reading database ... 100%(Reading database ... 7556 files and directories currently installed.)
Preparing to unpack .../python-is-python3_3.9.2-2_all.deb ...
Unpacking python-is-python3 (3.9.2-2) ...
Selecting previously unselected package opensips.
Preparing to unpack .../opensips_4.0.2-1_amd64.deb ...
Unpacking opensips (4.0.2-1) ...
Setting up python-is-python3 (3.9.2-2) ...
Setting up opensips (4.0.2-1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/opensips.service → /lib/systemd/system/opensips.service.

对输出的三点解读：

额外安装 python-is-python3：openSIPS 主包依赖 python | python-is-python3 二选一（第九章 9.1 节的依赖报错实录可印证该依赖关系），apt 自动选择了后者（把 /usr/bin/python 软链到 python3）；
Suggested packages 是 4.0 的功能模块子包清单：主包只含核心引擎与默认模块，MySQL/Postgres/TLS/radius 等能力以 opensips-<功能>-module 子包形式按需另装，例如数据库认证装 opensips-mysql-module、TLS 装 opensips-tls-openssl-module；
末尾的 Created symlink 行表明安装程序已把 opensips.service 注册进 multi-user.target，即安装完成即开机自启。

主包下载量约 4.4 MB，安装后占用约 16.8 MB。

3.6 安装结果验证

三步验证：二进制版本、服务状态、端口监听。

opensips -V

version: opensips 4.0.2 (x86_64/linux)
flags: STATS: On, DISABLE_NAGLE, USE_MCAST, SHM_MMAP, PKG_MALLOC, Q_MALLOC, F_MALLOC, HP_MALLOC, F_PARALLEL_MALLOC, DBG_MALLOC, FAST_LOCK-ADAPTIVE_WAIT

systemctl is-active opensips

active

ss -lun | grep 5060

UNCONN 0      0          127.0.0.1:5060       0.0.0.0:*    users:(("opensips",pid=3220,fd=46),("opensips",pid=3219,fd=46),("opensips",pid=3218,fd=46),("opensips",pid=3217,fd=46),("opensips",pid=3216,fd=46),("opensips",pid=3215,fd=46),("opensips",pid=3214,fd=46),("opensips",pid=3213,fd=46),("opensips",pid=3212,fd=46))

解读：

opensips -V 确认二进制为 4.0.2，flags 行显示编译特性（STATS 统计、F_MALLOC 内存分配器、自适应快速锁等）；
服务在安装完成后即处于 active（Debian 系包管理器安装时会自动启动服务）；
默认配置只监听 127.0.0.1:5060（回环地址，外部无法访问），9 个 opensips 进程共享同一个监听 socket（所有进程的 fd 编号同为 46）——监听地址的修改见 6.5 节。

四、方案 B：离线安装（.deb 依赖闭包）

内网隔离的服务器无法访问 APT 仓库，此时可在联网机上把目标包及其全部依赖预先下载成 .deb 文件集，再整体拷贝到离线服务器安装。本章在 IP 为 10.89.62.6 的全新服务器上演示完整流程。

💡 技术拓展：Linux 下的离线安装不止一种做法，常见方案对比——

方案原理适用场景与取舍
依赖闭包 + dpkg -i（本文所用）联网机递归下载全部依赖 .deb，离线机逐包安装步骤最少、离线机无需配置本地源；依赖包较多时文件集偏大
本地 APT 仓库离线源把 .deb 集做成 dpkg-scanpackages 本地源，apt 正常解析安装适合大批量同版本装机；离线机需配置本地源文件
apt-offline 工具生成签名请求包→联网机下载→离线机回灌适合"离线机不能随意插拔介质"的严格隔离环境

本文因目标服务器数量少、追求步骤最少，采用依赖闭包 + dpkg -i。

方案	原理	适用场景与取舍
依赖闭包 + dpkg -i（本文所用）	联网机递归下载全部依赖 .deb，离线机逐包安装	步骤最少、离线机无需配置本地源；依赖包较多时文件集偏大
本地 APT 仓库离线源	把 .deb 集做成 `dpkg-scanpackages` 本地源，apt 正常解析安装	适合大批量同版本装机；离线机需配置本地源文件
apt-offline 工具	生成签名请求包→联网机下载→离线机回灌	适合"离线机不能随意插拔介质"的严格隔离环境

4.1 在联网机上下载依赖闭包

在一台已按 3.1/3.2 节配置好 openSIPS 仓库的 Ubuntu 22.04 联网机上执行。先用 apt-cache depends --recurse 递归解析出全部依赖包名，再用 apt-get download 批量下载：

mkdir -p /tmp/offline && cd /tmp/offline
apt-get download $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances opensips python-is-python3 | grep "^\w" | sort -u)

以下为下载输出节选（实测首尾）：

Get:1 http://archive.ubuntu.com/ubuntu jammy/main amd64 adduser all 3.118ubuntu5 [156 kB]
Get:2 https://apt.opensips.org jammy/4.0-releases amd64 opensips amd64 4.0.2-1 [4399 kB]
...
Get:71 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 zlib1g amd64 1:1.2.11.dfsg-2ubuntu9.2 [58.4 kB]
Fetched 33.9 MB in 5s (6764 kB/s)
W: Download is performed unsandboxed as root as file '/tmp/offline/adduser_3.118ubuntu5_all.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

确认下载结果（第 2 行 Get:2 https://apt.opensips.org ... 说明主包来自 openSIPS 官方仓库，其余 70 个为基础系统依赖）：

ls /tmp/offline | wc -l

ls /tmp/offline | grep opensips

opensips_4.0.2-1_amd64.deb

共 71 个 .deb 文件、合计 33.9 MB。闭包中包含 libc6、perl、debconf 等基础包：目标服务器上若已存在同名同版本包，dpkg 会原地重装，无副作用；若目标服务器比下载机新，dpkg 降级重装基础包通常也无碍，但更稳妥的做法是让下载机与目标服务器保持同一小版本（本文两台均为 Ubuntu 22.04.5）。

命令中的 grep "^\w" 用于从 apt-cache depends 输出中筛出包名行（依赖行带缩进、包名行顶格），sort -u 去重；--no-recommends 等参数避免把"推荐/建议"级依赖一并拉入。末尾的 W: 警告说明见 9.2 节。

4.2 拷贝离线包到目标服务器

将 /tmp/offline 目录下全部 71 个 .deb 文件拷贝到离线服务器的 /opt/b1/debs/ 目录（U 盘、内网文件分发服务等任意方式均可）。拷贝完成后在离线服务器上确认：

ls /opt/b1/debs | wc -l

4.3 离线安装

dpkg -i /opt/b1/debs/*.deb

dpkg 按通配符展开顺序逐包解包并配置。以下为安装输出节选（实测首尾）：

(Reading database ... 8990 files and directories currently installed.)
Preparing to unpack .../adduser_3.118ubuntu5_all.deb ...
Unpacking adduser (3.118ubuntu5) over (3.118ubuntu5) ...
...
running python post-rtupdate hooks for python3.10...
Setting up python-is-python3 (3.9.2-2) ...
Setting up opensips (4.0.2-1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/opensips.service → /lib/systemd/system/opensips.service.
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

与在线安装一样，末尾 Created symlink 行表明服务已注册自启动。闭包必须完整：只拷主包不拷依赖会直接报错，实录与解决见 9.1 节。

4.4 安装结果验证

opensips -V

version: opensips 4.0.2 (x86_64/linux)
flags: STATS: On, DISABLE_NAGLE, USE_MCAST, SHM_MMAP, PKG_MALLOC, Q_MALLOC, F_MALLOC, HP_MALLOC, F_PARALLEL_MALLOC, DBG_MALLOC, FAST_LOCK-ADAPTIVE_WAIT

systemctl is-active opensips

active

ss -lun | grep 5060

UNCONN 0      0         10.89.62.6:5060       0.0.0.0:*

版本 4.0.2、服务 active、端口 5060 已监听，离线安装完成。后续第六、七、八、十章的配置、验证与卸载操作在方案 A 与方案 B 的服务器上完全一致，下文以方案 A 的服务器（10.89.62.3）为例。

五、两种方案对比

对比项	方案 A：在线安装	方案 B：离线安装
网络要求	服务器可达 archive.ubuntu.com 与 apt.opensips.org	仅下载机联网，服务器零外联
依赖处理	apt 自动解析	预先下载全量闭包（71 个包，33.9 MB）
安装命令	`apt-get install -y opensips`	`dpkg -i /opt/b1/debs/*.deb`
后续升级	`apt-get update` 后直接升级	重新制作闭包再拷贝
版本锁定	`apt-mark hold`（8.3 节）	闭包内版本天然固定
适用场景	云主机、IDC 等可联网服务器	内网隔离区、同版本批量装机

如何选型：服务器能出网就用方案 A，依赖解析、升级、安全更新都由 apt 托管，运维成本最低；只有当服务器处于严格隔离网络时才用方案 B，并注意闭包与目标机的系统小版本保持一致。

六、安装后的文件布局与基础配置

6.1 包文件布局

查看 opensips 主包在系统中的文件布局（筛选配置与可执行文件部分）：

dpkg -L opensips | grep -E "^/etc|^/usr/sbin"

/etc
/etc/default
/etc/default/opensips
/etc/init.d
/etc/init.d/opensips
/etc/opensips
/etc/opensips/opensips.cfg
/etc/opensips/scenario_callcenter.xml
/usr/sbin
/usr/sbin/opensips
/usr/sbin/osipsconfig

逐项说明：

文件/目录	作用
`/etc/default/opensips`	服务启动参数（共享内存、包内存、附加选项），见 6.3 节
`/etc/init.d/opensips`	SysVinit 兼容脚本，systemd 环境下主要由 systemd 单元接管
`/etc/opensips/opensips.cfg`	核心路由脚本，openSIPS 全部业务逻辑所在，见 6.4 节
`/etc/opensips/scenario_callcenter.xml`	呼叫中心场景的示例脚本资源
`/usr/sbin/opensips`	服务主程序
`/usr/sbin/osipsconfig`	配置生成器，交互式生成定制化的 opensips.cfg 骨架

其中 scenario_callcenter.xml 确属主包（而非其他模块包）：

dpkg -S /etc/opensips/scenario_callcenter.xml

opensips: /etc/opensips/scenario_callcenter.xml

6.2 systemd 服务单元解析

cat /lib/systemd/system/opensips.service

[Unit]
Description=OpenSIPS is a very fast and flexible SIP (RFC3261) server
Documentation=man:opensips
After=network.target mysqld.service postgresql.service rtpproxy.service

[Service]
Type=forking
User=opensips
Group=opensips
RuntimeDirectory=opensips
RuntimeDirectoryMode=775
Environment=P_MEMORY=32 S_MEMORY=32
EnvironmentFile=-/etc/default/opensips
PermissionsStartOnly=yes
PIDFile=%t/opensips/opensips.pid
ExecStart=/usr/sbin/opensips -P %t/opensips/opensips.pid -f /etc/opensips/opensips.cfg -m $S_MEMORY -M $P_MEMORY $OPTIONS
ExecStop=/usr/bin/pkill --pidfile %t/opensips/opensips.pid
Restart=always
TimeoutStopSec=30s
LimitNOFILE=262144

[Install]
WantedBy=multi-user.target

关键项解读：

配置项	含义
`Type=forking`	主程序以守护进程方式自行 fork，systemd 跟踪 PID 文件判断启动完成
`User/Group=opensips`	以安装时自动创建的系统用户 `opensips` 运行（非 root）
`Environment=P_MEMORY=32 S_MEMORY=32`	内置默认内存值；会被下一行的 EnvironmentFile 覆盖
`EnvironmentFile=-/etc/default/opensips`	读取 6.3 节的参数文件（`-` 前缀表示文件缺失时不报错）
`ExecStart ... -m $S_MEMORY -M $P_MEMORY $OPTIONS`	`-m` 共享内存（MB）、`-M` 每进程包内存（MB）、`$OPTIONS` 附加参数，实际生效值为 64/4
`PIDFile=%t/opensips/opensips.pid`	PID 文件位于 `/run/opensips/opensips.pid`（`%t` 即 `/run`）
`Restart=always`	进程异常退出后自动拉起
`LimitNOFILE=262144`	文件描述符上限 26 万，满足高并发 TCP/TLS 连接需求（4.0 起 TCP 改为多线程模型，连接数随线程内 fd 走）

日常运维最常用的是 systemctl start/stop/restart/status opensips 与 systemctl is-active opensips，无需直接操作二进制。

6.3 启动参数文件 /etc/default/opensips

cat /etc/default/opensips

#
# OpenSIPS startup options
#

# Set to yes to enable opensips, once configured properly.
RUN_OPENSIPS=no

# User to run as
USER=opensips

# Group to run as
GROUP=opensips

# Amount of shared memory to allocate for the running OpenSIPS server (in Mb)
S_MEMORY=64

# Amount of pkg memory to allocate for the running OpenSIPS server (in Mb)
P_MEMORY=4

# Enable the server to leave a core file when it crashes.
# Set this to 'yes' to enable OpenSIPS to leave a core file when it crashes
# or 'no' to disable this feature. This option is case sensitive and only
# accepts 'yes' and 'no' and only in lowercase letters.
# On some systems (e.g. Ubuntu 6.10, Debian 4.0) it is necessary to specify
# a directory for the core files to get a dump. Look into the opensips
# init file for an example configuration.
DUMP_CORE=no

# Any additional OpenSIPS options
OPTIONS=""

逐项说明：

参数	默认值	含义
`RUN_OPENSIPS`	no	SysVinit 时代的启用开关，供 `/etc/init.d/opensips` 脚本使用；systemd 单元不读取该值，systemd 下启停以 systemctl 为准
`USER` / `GROUP`	opensips	服务运行身份（systemd 单元内已单独声明）
`S_MEMORY`	64（MB）	共享内存大小，对应启动参数 `-m`；对话、注册表等跨进程数据都存于共享内存，高并发场景按需调大
`P_MEMORY`	4（MB）	每进程私有包内存，对应 `-M`；脚本处理单个消息的临时数据在此分配
`DUMP_CORE`	no	崩溃时是否生成 core 文件（排障期可临时打开）
`OPTIONS`	空	追加到 ExecStart 的额外命令行参数

调整内存参数时修改本文件对应值，然后 systemctl restart opensips 生效。

6.4 默认路由脚本 opensips.cfg

/etc/opensips/opensips.cfg 是 openSIPS 的核心：每个 SIP 请求都流经该脚本的路由逻辑，由脚本决定认证、查库、改写或转发。查看默认配置头部：

head -40 /etc/opensips/opensips.cfg

#
# OpenSIPS residential configuration script
#     by OpenSIPS Solutions <team@opensips-solutions.com>
#
# This is a basic residential configuration. Ready-to-use M4 templates are
# available under examples/templates/.
#
# Please refer to the OpenSIPS Manuals at:
#      https://opensips.org/Documentation/Manuals
# for an explanation of available statements, functions and parameters.
#


####### Global Parameters #########

/* uncomment the following lines to enable debugging */
#debug_mode=yes

log_level=3
xlog_level=3
stderror_enabled=no
syslog_enabled=yes
syslog_facility=LOG_LOCAL0

udp_workers=4

/* uncomment the next line to enable the auto temporary blacklisting of 
   not available destinations (default disabled) */
#disable_dns_blacklist=no

/* uncomment the next line to enable IPv6 lookup after IPv4 dns 
   lookup failures (default disabled) */
#dns_try_ipv6=yes


socket=udp:10.89.62.3:5060   # CUSTOMIZE ME



####### Modules Section ########

头部关键项解读：

配置项	默认值	含义
脚本类型注释	residential	默认脚本是「住宅/企业」场景模板（注册、认证、呼叫路由骨架齐全），源码包的 `examples/templates/` 下还有更多场景模板
`log_level` / `xlog_level`	3	日志级别（3=INFO）；排障时可临时调为 4（DBG）
`syslog_facility`	LOG_LOCAL0	日志走 syslog，facility 为 local0，可在 rsyslog 中按此分流
`udp_workers`	4	UDP 收发的 worker 进程数，对应 3.6 节 ss 回显中的多个进程
`socket`	udp:127.0.0.1:5060	监听地址，注释 `CUSTOMIZE ME` 明确提示必改，见 6.5 节
`#debug_mode=yes`	注释态	打开后前台运行+全量调试日志，仅排障使用

文件头部之后是 ####### Modules Section ######## 模块加载区与 route{} 路由逻辑区，residential 模板已预置 registrar/auth_db/dialog 等模块的加载与调用骨架，具体参数调优不在本文展开。

6.5 修改监听地址并校验配置

默认只监听 127.0.0.1，外部终端无法访问，需改为服务器实际地址（本文为 10.89.62.3）。用 sed 原地替换 socket 行并确认：

sed -i "s/^socket=.*/socket=udp:10.89.62.3:5060   # CUSTOMIZE ME/" /etc/opensips/opensips.cfg && grep -n "^socket" /etc/opensips/opensips.cfg

36:socket=udp:10.89.62.3:5060   # CUSTOMIZE ME

重启前先做语法校验（-c 只检查配置不启动服务）：

opensips -c -f /etc/opensips/opensips.cfg 2>&1 | tail -6

Oct 26 10:30:17 [4027] INFO:core:fix_poll_method: using epoll as the IO watch method (auto detected)
Oct 26 10:30:17 [4027] NOTICE:core:main: config file ok, exiting...
Listening on 
             udp: 10.89.62.3 [10.89.62.3]:5060
Aliases:

config file ok, exiting... 即校验通过，同时打印了生效的监听列表。正式重启服务并复核：

systemctl restart opensips && systemctl is-active opensips

active

ss -lun | grep 5060

UNCONN 0      0         10.89.62.3:5060       0.0.0.0:*    users:(("opensips",pid=3740,fd=46),("opensips",pid=3739,fd=46),("opensips",pid=3738,fd=46),("opensips",pid=3737,fd=46),("opensips",pid=3736,fd=46),("opensips",pid=3735,fd=46),("opensips",pid=3734,fd=46),("opensips",pid=3733,fd=46),("opensips",pid=3732,fd=46))

监听地址已从 127.0.0.1:5060 变为 10.89.62.3:5060，9 个进程共享同一 socket。若需同时监听 TCP，在配置中再加一行 socket=tcp:10.89.62.3:5060 并重启即可。

七、SIP 连通性验证

安装配置完成后，从另一台内网机器（10.89.62.4）用 sipsak 工具向服务器发 SIP OPTIONS 探测，验证信令链路端到端可用。sipsak 是轻量级 SIP 命令行测试工具，来自 Ubuntu 的 universe 仓库。

客户端安装 sipsak（本文客户端已装过 sipsak，为完整演示安装回显加 --reinstall 强制重装；全新客户端去掉该参数即可）：

apt-get install -y --reinstall sipsak

Need to get 51.8 kB of archives.
Get:1 http://archive.ubuntu.com/ubuntu jammy/universe amd64 sipsak amd64 0.9.8.1-1build1 [51.8 kB]
Preparing to unpack .../sipsak_0.9.8.1-1build1_amd64.deb ...
Unpacking sipsak (0.9.8.1-1build1) over (0.9.8.1-1build1) ...
Setting up sipsak (0.9.8.1-1build1) ...

sipsak -V

sipsak 0.9.8.1  by Nils Ohlmeier

向服务器发送 OPTIONS 探测（-s 指定目标 SIP URI；-v 打印收到的应答报文，不加 -v 时本例的非 2xx 应答不会打印任何内容）：

sipsak -v -s sip:10.89.62.3

SIP/2.0 484 Address Incomplete
Via: SIP/2.0/UDP 10.89.62.4:48012;received=10.89.62.4;branch=z9hG4bK.6a5b24e5;rport=33781;alias
To: sip:10.89.62.3;tag=6178.d7c48f8378b2364565748322c6ab2917
From: sip:sipsak@10.89.62.4:48012;tag=26d28ffb
Call-ID: 651333627@10.89.62.4
CSeq: 1 OPTIONS
Server: OpenSIPS (4.0.2 (x86_64/linux))
Content-Length: 0

结果解读：服务器返回了 484 Address Incomplete 应答——这是默认 residential 脚本对无有效用户上下文请求的正常应答，重点不在状态码本身，而在于：

Server: OpenSIPS (4.0.2 (x86_64/linux))：服务器进程存活、版本与安装一致；
Via 头中的 received=10.89.62.4 与 rport 表明服务器正确处理了 NAT 相关的 Via 参数，SIP 事务（CSeq: 1 OPTIONS）完整走完。

至此，从安装到信令连通的部署闭环完成。要实现真正的用户注册与呼叫，还需按场景扩展 opensips.cfg（数据库、认证、路由模块），可先通过 opensips 的命令行管理工具熟悉运行态操作。

八、升级、降级与版本锁定

8.1 升级到新的小版本

官方仓库发布新小版本后（版本表见 3.4 节），升级就是常规的 apt 安装指定版本操作。以下实测从 4.0.1 升级到 4.0.2：

apt-get install -y opensips=4.0.2-1

Reading package lists...
Building dependency tree...
Reading state information...
The following packages will be upgraded:
  opensips
1 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.
Need to get 4399 kB of archives.
Get:1 https://apt.opensips.org jammy/4.0-releases amd64 opensips amd64 4.0.2-1 [4399 kB]
Setting up opensips (4.0.2-1) ...

opensips -V

version: opensips 4.0.2 (x86_64/linux)

不指定版本号时，apt-get update && apt-get install -y opensips（或 apt-get upgrade）会自动升到仓库最新候选版本。升级过程中 /etc/opensips/opensips.cfg 等配置文件按 Debian conffiles 机制保留本地修改。

8.2 降级到历史版本

仓库中保留的历史小版本（4.0.0-1、4.0.1-1）可随时回退。以下实测从 4.0.2 降级到 4.0.1：

apt-get install -y --allow-downgrades opensips=4.0.1-1

Reading package lists...
Building dependency tree...
Reading state information...
The following packages will be DOWNGRADED:
  opensips
0 upgraded, 0 newly installed, 1 downgraded, 0 to remove and 2 not upgraded.
Need to get 4398 kB of archives.
Get:1 https://apt.opensips.org jammy/4.0-releases amd64 opensips amd64 4.0.1-1 [4398 kB]
Setting up opensips (4.0.1-1) ...

opensips -V

version: opensips 4.0.1 (x86_64/linux)

--allow-downgrades 是显式回退所必需的参数，缺失时 apt 拒绝执行降级。降级完成后按 3.6 节复核服务状态。

8.3 版本锁定与解锁

生产环境常需要把版本"钉"在某个小版本上，避免例行 apt-get upgrade 带来非预期升级。使用 apt-mark hold：

apt-mark hold opensips

opensips set on hold.

apt-mark showhold

opensips

锁定状态下再尝试变更版本，apt 会直接拒绝（实测报错）：

apt-get install -y opensips=4.0.2-1

E: Held packages were changed and -y was used without --allow-change-held-packages.

解除锁定后重试即可：

apt-mark unhold opensips

Canceled hold on opensips.

apt-get install -y opensips=4.0.2-1

Reading package lists...
Building dependency tree...
Reading state information...
Get:1 https://apt.opensips.org jammy/4.0-releases amd64 opensips amd64 4.0.2-1 [4399 kB]
Setting up opensips (4.0.2-1) ...

opensips -V

version: opensips 4.0.2 (x86_64/linux)

systemctl is-active opensips

active

九、常见问题与排障实录

9.1 离线安装只拷主包导致依赖报错

现象：离线安装时若只把 opensips_4.0.2-1_amd64.deb 单个文件拷到服务器执行 dpkg -i，会因缺少依赖直接失败：

dpkg -i /opt/b1/debs/opensips_4.0.2-1_amd64.deb

 opensips depends on python | python-is-python3; however:
  Package python is not installed.
  Package python-is-python3 is not installed.

dpkg: error processing package opensips (--install):
 dependency problems - leaving unconfigured
Errors were encountered while processing:
 opensips

此时包处于「已解包、未配置」状态（状态码 iU）：

dpkg -l opensips | tail -1

iU  opensips       4.0.2-1      amd64        very fast and configurable SIP server

解决：先用 dpkg --purge 清掉残留，再按 4.1 节下载全量依赖闭包（71 个 .deb）重新整体安装：

dpkg --purge opensips

Removing opensips (4.0.2-1) ...
Purging configuration files for opensips (4.0.2-1) ...

教训：报错中的 opensips depends on python | python-is-python3 印证了 3.5 节所述依赖关系——离线场景没有 apt 代为解析依赖，任何一个依赖缺漏都会卡在 unconfigured 状态，闭包必须完整。

9.2 apt-get download 出现 unsandboxed 警告

现象：4.1 节下载闭包时输出末尾出现：

W: Download is performed unsandboxed as root as file '/tmp/offline/adduser_3.118ubuntu5_all.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

原因与处理：apt 下载默认以低权限用户 _apt 运行沙箱，而本例以 root 身份在 /tmp/offline 目录下直写文件，_apt 无权访问时 apt 退回 root 下载并给出警告。该警告不影响下载结果（71 个包完整落盘），可忽略；在意告警清洁的话，可改在普通用户可写的目录中执行下载。

十、卸载与清理

彻底卸载 openSIPS 使用 apt-get purge（purge 与 remove 的区别在于是否清理配置文件，本文实测 purge）：

apt-get purge -y opensips python-is-python3

Removing opensips (4.0.2-1) ...
Removing python-is-python3 (3.9.2-2) ...
Purging configuration files for opensips (4.0.2-1) ...

卸载后验证二进制、配置目录与服务均已清理：

ls /etc/opensips

ls: cannot access '/etc/opensips': No such file or directory

dpkg -l opensips | tail -1

dpkg-query: no packages found matching opensips

/etc/opensips 配置目录随 purge 一并删除，包记录已不存在。方案 B 的离线服务器卸载后再清理 /opt/b1/debs/ 目录即可；重新安装时按第三章或第四章从零执行。

十一、参考链接

openSIPS 官方下载页（APT/YUM/源码/Docker 全渠道入口）：https://www.opensips.org/Downloads/Downloads
官方 APT 仓库：https://apt.opensips.org/
openSIPS GitHub 主仓库：https://github.com/OpenSIPS/opensips
sipsak 软件包（Ubuntu jammy）：https://packages.ubuntu.com/jammy/sipsak
组件背景、架构与选型对比：《openSIPS 4.0 介绍与选型指南》