Debian Shadowsocks 教程：apt 安装、配置与连接排查
简答：如果你要在 Debian 服务器上部署 Shadowsocks，优先使用 Debian 软件源中的 shadowsocks-libev：先确认系统和公网 IP，再执行 apt 安装、创建 JSON 配置、启动 shadowsocks-libev-server 实例，最后同时检查 systemd 状态、TCP/UDP 监听、云安全组和客户端参数。本文只讲授权服务器和个人设备之间的合法网络连接，不建议使用来源不明的一键脚本。
定义：Shadowsocks 是一种基于 SOCKS5 工作方式的加密转发工具，服务端运行 ss-server，客户端通过本地代理组件连接服务端并转发请求。
先看最短路径：Debian Shadowsocks 部署检查表
本文以能使用 root 或 sudo 的 Debian VPS 为前提，优先覆盖 Debian 12/13 中可通过软件源获取的 shadowsocks-libev。Shadowsocks 官方文档列出 Debian/Ubuntu 的 apt 安装方式；Debian 软件包页面也显示 shadowsocks-libev 属于官方软件包。查看 Shadowsocks 官方部署文档、查看 Debian 软件包信息。
| 检查项 | 成功标准 | 失败时先看哪里 |
|---|---|---|
| 系统与权限 | 能输出 Debian 版本，sudo 命令可用 | SSH 用户权限、系统版本和架构 |
| 软件包 | ss-server 命令存在 | apt 源、软件包名称和网络连接 |
| 配置文件 | JSON 校验通过，密码和端口已替换 | 逗号、引号、字段名和文件权限 |
| 服务状态 | 对应 systemd 实例为 active | journalctl 日志 |
| 端口 | 服务器同时按需求监听 TCP/UDP | 配置 mode、本机防火墙、云安全组 |
| 客户端 | 服务器地址、端口、密码、加密方式完全一致 | 导入格式、代理模式和 DNS 请求链路 |
不要把“服务显示运行中”单独当作可用证明。至少还要确认端口监听、云端入站规则和客户端实际请求。
第一步：确认 Debian、架构和公网地址
先登录服务器执行以下检查。命令在服务器 SSH 终端中运行：
cat /etc/os-release
uname -m
id
ip -br address
重点确认三点：第一，系统确实是 Debian；第二，当前账号具备 root 或 sudo 权限；第三，云平台分配了可从客户端访问的公网 IPv4 或 IPv6。若服务器位于路由器后面，还需要在上游路由器做端口转发；Debian Wiki 的 Shadowsocks 说明也把端口转发列为独立网络条件。查看 Debian Wiki 的 Shadowsocks 说明。
建议先确定一个端口，例如 8388。如果云厂商有安全组，稍后只放行该端口以及你实际使用的 SSH 端口，不要为了排错直接放开全部入站端口。
第二步：通过 apt 安装 shadowsocks-libev
官方部署页给出的 Debian/Ubuntu 路线是先更新软件索引，再安装 shadowsocks-libev。在 Debian 服务器执行：
sudo apt update
sudo apt install shadowsocks-libev
安装后确认程序和 Debian 软件包提供的 systemd 单元：
command -v ss-server
ss-server --help | head -n 20
systemctl list-unit-files | grep shadowsocks-libev
Debian 软件包文件列表包含 /usr/bin/ss-server、[email protected] 以及示例配置文件路径。查看 Debian 软件包文件列表。不同 Debian 发布版的默认模板内容可能不同，所以启动前建议执行：
systemctl cat [email protected]
确认模板的配置文件路径和启动参数。若模板使用 /etc/shadowsocks-libev/%i.json，下面的 server.json 示例可以直接对应使用；如果输出显示了不同路径，以本机模板为准。
第三步：创建配置文件并做 JSON 校验
先创建配置目录并生成随机密码。密码不要复用 SSH 密码、面板密码或邮箱密码：
sudo install -d -m 0755 /etc/shadowsocks-libev
openssl rand -base64 24
把命令输出的随机字符串复制到配置文件中的 password 字段，然后创建文件：
sudo nano /etc/shadowsocks-libev/server.json
写入以下最小配置，并替换 CHANGE_THIS_TO_A_RANDOM_PASSWORD：
{
"server": "0.0.0.0",
"server_port": 8388,
"password": "CHANGE_THIS_TO_A_RANDOM_PASSWORD",
"method": "chacha20-ietf-poly1305",
"mode": "tcp_and_udp"
}
server 是服务端监听地址，server_port 是服务端口，password 和 method 必须与客户端一致，mode 用于指定 TCP、UDP 或两者。Debian 的 shadowsocks-libev 手册列出了这些命令行参数与 JSON 字段的对应关系，并说明默认模式是不启用 UDP 的 TCP 模式。查看 shadowsocks-libev 手册。
保存后检查 JSON 格式和权限：
sudo python3 -m json.tool /etc/shadowsocks-libev/server.json
sudo chown root:root /etc/shadowsocks-libev/server.json
sudo chmod 600 /etc/shadowsocks-libev/server.json
如果当前版本不接受某个字段，先查看 ss-server --help 和本机 man 手册，不要直接复制其他实现的配置。shadowsocks-libev、go-shadowsocks2 和 outline-ss-server 不是同一个二进制程序，配置格式不能默认互换。
第四步：启动 systemd 服务并查看日志
如果前面确认模板使用 /etc/shadowsocks-libev/%i.json，可将 server.json 作为实例启动：
sudo systemctl enable --now [email protected]
sudo systemctl status [email protected] --no-pager
如果状态不是 active (running)，立即查看日志：
sudo journalctl -u [email protected] -n 80 --no-pager
常见方向包括：配置文件路径不匹配、JSON 语法错误、端口已被其他程序占用、加密方式在当前构建中不可用，以及实例单元名称与配置文件名不一致。不要反复重启掩盖首条错误，先修正日志中最早出现的配置或绑定失败信息。
如果你的 Debian 包没有使用实例模板，而是使用统一服务单元，执行 systemctl cat shadowsocks-libev.service 查看它读取的配置位置，再按该路径放置配置文件。服务单元名称和配置路径必须以本机安装结果为准。
第五步：放行必要端口，但保留 SSH 防护
端口需要同时通过云厂商安全组和服务器本机防火墙。两层规则只放行你实际使用的端口。假设 SSH 使用默认端口、Shadowsocks 使用 TCP/UDP 8388，可在确认 SSH 端口无误后使用 UFW：
sudo apt install ufw
sudo ufw allow 22/tcp
sudo ufw allow 8388/tcp
sudo ufw allow 8388/udp
sudo ufw status verbose
如果你确认规则正确，再执行：
sudo ufw enable
若 SSH 不是 22 端口，必须把示例中的 22 换成真实端口；否则启用防火墙可能导致自己无法再次登录。云安全组也要放行相同的 Shadowsocks 端口。若只配置 TCP，可只放行 TCP；配置为 tcp_and_udp 时，建议同时检查 TCP 和 UDP 规则。
不建议通过关闭防火墙来“验证是否能用”。正确做法是临时增加一条最小规则，测试后删除，并保留 SSH 的管理通道。
第六步：按五层验收，而不是只看节点显示
先确认本机监听：
sudo ss -lntup | grep -E ':(8388)\b'
ps -ef | grep '[s]s-server'
如果配置了 tcp_and_udp，应结合 ss 输出和日志确认 TCP/UDP 是否都按当前实现启动。仅有 TCP 监听不一定代表 UDP 配置已经生效；反过来，端口监听也不等于云安全组允许外部访问。
- 服务层：systemd 为 active，日志没有持续报错。
- 监听层：服务绑定了预期地址和端口，没有被其他进程占用。
- 网络层：云安全组、本机防火墙和上游路由均允许必要端口。
- 参数层：客户端的服务器地址、端口、密码、加密方式与服务端逐项一致。
- 请求层：客户端启用代理后，用固定的 HTTPS 页面做实际请求测试，再恢复原有代理、PAC、TUN 或 DNS 设置。
客户端侧通常选择 SOCKS5 类型，填入服务器公网地址、8388 端口、相同密码和相同加密方式。具体菜单名称随 Windows、macOS、Android、Linux 客户端而变，不能把某一个客户端的按钮路径当成通用标准。
连接失败速查：现象、优先判断与下一步
| 现象或提示 | 优先判断 | 操作与验证 |
|---|---|---|
| Connection refused | 目标端口没有服务监听，或服务绑定失败 | 查看 systemctl status、journalctl 和 ss -lntup；确认客户端端口没有写错 |
| Timeout | 云安全组、本机防火墙、路由或地址不可达 | 确认公网 IP、云端入站规则和 UFW；不要先关闭全部防护 |
| Authentication failed | 密码不一致或导入内容被截断 | 重新复制密码，检查服务端 JSON 和客户端字段；不要把密码发布到公共页面 |
| 启动后立即退出 | 配置格式、字段或端口占用问题 | 运行 python3 -m json.tool，查看日志首条错误，并用 ss 检查端口占用 |
| TCP 能用、UDP 不通 | mode、UDP 防火墙规则或客户端未启用 UDP | 确认服务端为 tcp_and_udp，云安全组和 UFW 都放行 UDP，客户端也支持并启用 UDP |
| 客户端导入成功但没有连接 | 订阅或导入格式成功，不代表服务端可达 | 逐项核对地址、端口、密码、method、代理模式和 DNS；再看服务端日志是否出现连接记录 |
| 浏览器无效但命令行有效 | 浏览器代理、系统代理、PAC、TUN 或其他代理软件冲突 | 暂时只保留一个代理链路做对照测试，测试后恢复原设置 |
错误提示只能作为排查方向，不能直接证明唯一原因。每次只改一个变量，并记录改动前后的服务状态、监听结果和客户端表现。
shadowsocks-libev、其他实现与一键脚本怎么选
对于第一次在 Debian 上部署、只需要一个基础服务端的用户，apt 安装 shadowsocks-libev 的优点是来源清晰、可由 Debian 软件包管理器更新，且官方文档明确给出了 Debian/Ubuntu 的安装方式。
Shadowsocks 官方部署页同时列出 go-shadowsocks2 和 outline-ss-server。官方说明中，outline-ss-server 支持多用户、多端口、监控和配置热更新等能力；这些能力并不意味着它与 shadowsocks-libev 的配置文件或 systemd 单元可以直接互换。查看官方实现对比。
一键脚本适合已经核对来源、代码和适用系统的用户，不适合作为新手默认路线。脚本可能固定旧版系统、旧服务名、旧加密方式或非 Debian 软件源路径。若脚本没有提供可审计的安装内容、卸载方法和配置位置，建议回到 apt 软件包路线。
另外，插件、伪装或额外封装属于独立配置主题，不能把它们当成真实 HTTPS 服务，也不能据此承诺隐私、稳定性或兼容性。本文先完成基础 TCP/UDP 服务验收，插件问题应以对应实现和插件的官方文档为准。
运维与安全清单：部署完成后还要做什么
- 保存配置备份，但不要把包含密码的 JSON 上传到公开代码仓库、工单或聊天群。
- 只开放必要端口，保留 SSH 管理通道，并定期检查云安全组和本机防火墙。
- 升级前先查看当前软件包版本、服务单元和配置备份，升级后重新检查 systemd、监听和日志。
- 更换密码后，要同步更新所有客户端；旧密码不应继续长期有效。
- 如果服务器不再使用，先停止并禁用服务，再删除防火墙和云安全组中的对应规则。
- 不要把“端口开放”“客户端显示已连接”或单次测速结果单独当作长期稳定性证明。
完成基础部署后，如果你只是需要在电脑或手机上使用现成的网络加速服务，不一定需要自己维护 VPS；可以先比较配置导入、客户端支持、备份和故障迁移成本。
常见问题
Debian 12 或 13 应该安装哪个 Shadowsocks 实现？
如果你只需要基础服务端，优先先检查 Debian 软件源是否提供 shadowsocks-libev，并使用 apt 安装。go-shadowsocks2 和 outline-ss-server 是不同实现，适合需要不同部署方式或多用户能力的场景，不能直接套用同一份配置。具体版本和字段以当前系统的软件包、命令帮助和官方文档为准。
为什么 systemd 显示服务运行，但客户端仍然连接不上？
服务运行只说明进程没有退出，不代表外部端口可达。按顺序检查监听地址和端口、云安全组、本机防火墙、服务器公网 IP，以及客户端的密码、加密方式和端口。若这些都通过，再查看服务日志是否出现客户端连接记录。
Shadowsocks 服务端是否必须放行 UDP？
不一定。如果配置和使用场景只需要 TCP，可以按当前配置只开放 TCP；如果 JSON 中使用了 <code>tcp_and_udp</code>，则应同时检查服务端监听、云安全组、本机防火墙和客户端是否支持 UDP。不能仅凭 TCP 连接成功推断 UDP 正常。
配置文件应该放在哪里？
Debian 软件包提供了 shadowsocks-libev 的 systemd 模板和示例配置，但不同 Debian 版本或服务单元可能使用不同路径。先执行 <code>systemctl cat [email protected]</code> 查看 ExecStart 和配置文件路径，再创建对应实例文件，不要盲目套用其他教程的固定路径。
可以直接使用一键脚本安装 Debian Shadowsocks 吗？
可以自行审查来源和脚本内容后再决定，但不建议新手把一键脚本作为默认方案。优先使用 Debian 软件源更容易确认软件包、服务单元和卸载路径；脚本若固定旧系统、旧加密方式或隐藏配置位置，后续排错和迁移会更困难。
相关阅读
参考资料
- Shadowsocks 官方部署文档（shadowsocks.org）
- Shadowsocks 官方定义与工作方式（shadowsocks.org）
- Debian stable shadowsocks-libev 软件包信息（packages.debian.org）
- Debian shadowsocks-libev 命令与配置手册（manpages.debian.org）
- Debian Wiki Shadowsocks 说明（wiki.debian.org）