Ubuntu ShadowsocksR 启动失败：MutableMapping 报错修复教程

本文记录 Ubuntu 系统安装 ShadowsocksR / SSR 后启动失败的修复方法。本站在 Ubuntu 22.04.5 LTS 环境测试 hijk 的 ubuntu_install_ssr.sh 脚本时，脚本可以完成下载、安装和配置文件生成，但最后启动 shadowsocksR.service 失败，终端提示 ssr启动失败，请检查端口是否被占用。

实际排查后发现，这次并不是端口占用，而是 ShadowsocksR 老代码和当前 Python 环境存在兼容问题，关键报错为 AttributeError: module 'collections' has no attribute 'MutableMapping'。如果您在 Ubuntu 系统中遇到同样的 MutableMapping 报错，也可以参考本文的修复方法。

还没有执行 Ubuntu SSR 一键脚本的用户，可以先参考本站主教程：Ubuntu 系统 ShadowsocksR / SSR 一键脚本安装教程。已经遇到 ShadowsocksR 启动失败的用户，可以直接按本文步骤排查。

如果您的服务器使用的是 CentOS 系统，不建议直接套用本文的 Ubuntu 修复步骤，可以参考 CentOS 系统 ShadowsocksR 一键脚本安装教程 (支持CentOS 9)，先按 CentOS 环境完成 SSR 服务端安装。

一、ShadowsocksR 启动失败现象

在 Ubuntu 系统上运行 hijk 的 SSR 一键脚本：

bash <(curl -sL https://raw.githubusercontent.com/hijkpw/scripts/master/ubuntu_install_ssr.sh)

安装前半段可以正常进行，脚本会提示设置 SSR 密码、端口、加密方式、协议和混淆模式。本文测试时使用的参数如下：

• 端口：12345
• 密码：bwgss
• 加密方式：aes-256-cfb
• 协议：origin
• 混淆：plain

但安装结束时，终端出现下面的启动失败提示：

Job for shadowsocksR.service failed because the control process exited with error code.
See "systemctl status shadowsocksR.service" and "journalctl -xeu shadowsocksR.service" for details.
Ubuntu 22.04.5 LTS ssr启动失败，请检查端口是否被占用！

安装结束后 shadowsocksR.service 启动失败，提示检查端口占用

二、查看 shadowsocksR.service 启动失败原因

遇到 ShadowsocksR 启动失败后，不建议先重复运行脚本，也不要马上更换端口。先查看服务状态，确认失败原因：

systemctl status shadowsocksR.service --no-pager -l

本文测试环境返回的关键错误如下：

AttributeError: module 'collections' has no attribute 'MutableMapping'

服务日志显示 collections.MutableMapping 报错，导致 ShadowsocksR 启动失败

这张图里可以看到 shadowsocksR.service 已经进入失败状态，真正需要关注的是 AttributeError: module 'collections' has no attribute 'MutableMapping'，不是脚本末尾提示的端口占用。

如果还需要查看更完整的 systemd 日志，可以继续执行：

journalctl -xeu shadowsocksR.service --no-pager -n 80

日志内容较长，排查时重点看 Traceback 后面的报错。本文测试环境中的关键错误如下：

Traceback (most recent call last):
  File "/usr/local/shadowsocks/../shadowsocks/lru_cache.py", line 44, in <module>
    class LRUCache(collections.MutableMapping):
AttributeError: module 'collections' has no attribute 'MutableMapping'

这个报错的意思是：ShadowsocksR 老代码还在使用 collections.MutableMapping，但新版本 Python 环境已经不再支持这种旧写法，需要改成 collections.abc.MutableMapping。

三、修复 MutableMapping 报错

确认是 MutableMapping 报错后，不需要重装系统，也不需要重新运行 Ubuntu SSR 一键脚本。直接修改 ShadowsocksR 的 lru_cache.py 文件即可。

执行下面两条命令：

sed -i '/^import collections$/a import collections.abc' /usr/local/shadowsocks/../shadowsocks/lru_cache.py
sed -i 's/collections.MutableMapping/collections.abc.MutableMapping/g' /usr/local/shadowsocks/../shadowsocks/lru_cache.py

第一条命令是在 import collections 后面增加 import collections.abc；第二条命令是把旧写法 collections.MutableMapping 替换成 collections.abc.MutableMapping。

执行 sed 命令修改 lru_cache.py，修复 MutableMapping 兼容问题

正常情况下，命令执行后不会输出额外内容，只要没有报错，就可以继续重启 ShadowsocksR 服务。

四、重启 ShadowsocksR 服务并检查状态

修复完成后，重启 ShadowsocksR 服务：

systemctl restart shadowsocksR

然后查看服务状态：

systemctl status shadowsocksR --no-pager -l

如果看到 Active: active (running)，说明 ShadowsocksR 服务已经正常运行。

本文实测修复后的服务状态如下：

● shadowsocksR.service - shadowsocksR
     Loaded: loaded (/lib/systemd/system/shadowsocksR.service; enabled; vendor preset: enabled)
     Active: active (running)
       Docs: https://hijk.art/
    Process: 1032 ExecStart=/usr/local/shadowsocks/server.py -c /etc/shadowsocksR.json -d start
   Main PID: 1040 (python)
     CGroup: /system.slice/shadowsocksR.service
             └─1040 python /usr/local/shadowsocks/server.py -c /etc/shadowsocksR.json -d start

修复后 shadowsocksR.service 显示 active running，服务已正常运行

五、检查 SSR 端口监听状态

服务状态正常后，还需要检查 SSR 端口是否已经监听。本文演示端口是 12345，执行：

ss -tulnp | grep 12345

本文实测返回结果如下：

udp   UNCONN 0      0                  *:12345            *:*    users:(("python",pid=1040,fd=5))
tcp   LISTEN 0      1024               *:12345            *:*    users:(("python",pid=1040,fd=4))

TCP 和 UDP 都在监听 SSR 端口，进程为 python

如果服务状态已经是 active (running)，但端口监听命令没有任何输出，需要回到 /etc/shadowsocksR.json 检查端口配置是否一致。

六、查看 ShadowsocksR 配置文件

hijk 的 Ubuntu SSR 一键脚本安装完成后，配置文件路径为：

/etc/shadowsocksR.json

可以执行下面命令查看：

cat /etc/shadowsocksR.json

本文测试环境配置如下：

{
    "server":"0.0.0.0",
    "server_ipv6":"::",
    "server_port":12345,
    "local_port":1080,
    "password":"bwgss",
    "timeout":600,
    "method":"aes-256-cfb",
    "protocol":"origin",
    "protocol_param":"",
    "obfs":"plain",
    "obfs_param":"",
    "redirect":"",
    "dns_ipv6":false,
    "fast_open":false,
    "workers":1
}

查看 /etc/shadowsocksR.json，确认 SSR 端口、加密方式、协议和混淆参数

本文中的 bwgss 只是测试密码，正式使用时请改成自己的复杂密码。

客户端添加 SSR 节点时，需要重点核对这些字段：

如果客户端仍然无法连接，先确认客户端填写的端口、密码、加密方式、协议和混淆是否与 /etc/shadowsocksR.json 一致，再检查 VPS 商家后台的防火墙、安全组或入站规则。

Windows 用户修复服务后，可以参考 Windows 系统 ShadowsocksR / SSR 客户端配置教程，把 /etc/shadowsocksR.json 中的端口、密码、加密方式、协议和混淆参数填入客户端。

Android 手机用户修复 ShadowsocksR 服务后，可以参考 Android（安卓）系统 ShadowsocksR / SSR 客户端配置教程，重点核对服务器地址、端口、密码、加密方式、协议和混淆是否填写一致。

七、常见问题

下面整理几个 Ubuntu 修复 ShadowsocksR 启动失败时容易遇到的问题。遇到服务无法启动时，建议按服务状态、日志、修复命令、端口监听、配置文件这个顺序检查。

1、提示 SSR 启动失败，一定是端口被占用吗？

不一定。hijk 脚本最后提示“请检查端口是否被占用”是通用提示。本文测试中，真正导致启动失败的是 collections.MutableMapping 报错。遇到启动失败时，应先执行：

systemctl status shadowsocksR.service --no-pager -l

如果日志里出现 AttributeError: module 'collections' has no attribute 'MutableMapping'，就按本文第三节修复。

2、修复后还需要重新运行 Ubuntu SSR 一键脚本吗？

不需要。本文的修复方式是在脚本已经安装完成、配置文件已经生成的前提下修改 Python 兼容问题。修复后直接重启 shadowsocksR 服务即可。

3、libsodium18 没有候选包会影响使用吗？

本文测试过程中出现过 Package 'libsodium18' has no installation candidate。使用默认 aes-256-cfb 加密方式时，修复 MutableMapping 报错后 ShadowsocksR 服务可以正常启动。如果您选择的是依赖 libsodium 的加密方式，可能还需要额外处理依赖问题。

4、其他 Ubuntu 版本也需要修复 MutableMapping 吗？

本文实测环境为 Ubuntu 22.04.5 LTS。其它 Ubuntu 版本如果出现同样的 MutableMapping 报错，也可以参考本文修复方法；如果没有出现该报错，不需要主动修改文件。

5、修复后客户端仍然连不上怎么办？

先确认服务是否运行：

systemctl status shadowsocksR --no-pager -l

再确认端口是否监听：

ss -tulnp | grep 12345

如果服务和端口都正常，继续检查 VPS 商家后台安全组、防火墙或入站规则，确认 SSR 端口的 TCP 和 UDP 已放行。

八、总结

Ubuntu 安装 ShadowsocksR 后提示启动失败，不一定是端口被占用。本站实测 hijk 的 Ubuntu SSR 一键脚本可以完成安装和配置文件生成，但在新版本 Python 环境下可能因为 collections.MutableMapping 兼容问题导致 shadowsocksR.service 启动失败。

解决方法是修改 /usr/local/shadowsocks/../shadowsocks/lru_cache.py，把 collections.MutableMapping 替换为 collections.abc.MutableMapping，然后重启 shadowsocksR 服务。修复后如果看到 Active: active (running)，并且 SSR 端口的 TCP 和 UDP 都在监听，就说明 ShadowsocksR 服务端已经恢复运行。