Shadowsocks Docker Compose 部署指南

目标：使用官方 shadowsocks/shadowsocks-libev 镜像，通过 Docker Compose 一条命令编排 Shadowsocks 服务端（ss-server）与客户端（ss-local）。覆盖镜像选型、编排文件、环境变量、配置持久化、等价 docker run、运维命令与常见问题。已在 Docker Daemon（29.8.0）上实测通过。

一、环境信息

项目	值
镜像	shadowsocks/shadowsocks-libev:latest
镜像内版本	3.3.4（shadowsocks-libev）
服务端端口	8388（TCP/UDP）
本地 socks5 端口	1080
编排工具	docker compose / docker-compose v1

二、镜像选型说明

Shadowsocks 官方维护 shadowsocks/shadowsocks-libev 镜像，镜像由整理仓库自动构建，内含 ss-server / ss-local / ss-tunnel 等完整工具套件，是社区使用最广的 Docker 形态。

镜像内部自带默认启动命令，等价执行：

ss-server -s $SERVER_ADDR -p $SERVER_PORT -k $PASSWORD -m $METHOD -t $TIMEOUT -d $DNS_ADDRS -u $ARGS

也就是说，镜像默认命令会读取同名环境变量；若未设置 $PASSWORD，镜像会以容器 hostname 兜底作为密码。即使不修改任何配置，直接 docker run 也能以默认参数启动，只需通过环境变量注入密钥/端口/加密方式。

镜像大小约 32.9MB（linux/amd64），默认加密方式为 aes-256-gcm。

💡 说明：镜像版本（3.3.4）略旧于 Ubuntu apt 源当前版本（3.3.5），两者命令行与配置文件完全兼容。生产若需最新版，可改用 Ubuntu 编译镜像或自行构建。

三、前置条件

已安装 Docker Engine（18.06+，支持 compose 语法）与 docker compose 插件（或 docker-compose v1）。
服务端需确保 8388 端口未被占用，并在安全组放行 TCP/UDP。
能拉取 docker.io/shadowsocks/shadowsocks-libev 镜像（离线环境需提前 docker load 导入）。

如下确认 docker 可用：

docker version --format "server={{.Server.Version}}"
docker compose version

四、部署步骤（服务端 ss-server）

4.1 编写 compose 文件

创建编排目录与文件：

mkdir -p /opt/shadowsocks && cd /opt/shadowsocks
vi docker-compose.yml

services:
  ss-server:
    image: shadowsocks/shadowsocks-libev:latest
    container_name: ss-server
    environment:
      - SERVER_ADDR=0.0.0.0
      - SERVER_PORT=8388
      - PASSWORD=q1w2e3r4
      - METHOD=aes-256-gcm
      - TIMEOUT=300
      - DNS_ADDRS=8.8.8.8,8.8.4.4
    ports:
      - "8388:8388"
      - "8388:8388/udp"
    restart: unless-stopped

⚠️ 注意：示例演示密码固定使用 q1w2e3r4；生产请改为强密码。若要对外提供 DNS 解析，DNS_ADDRS 可填云厂商内网 DNS；TIMEOUT 单位是秒。

4.2 拉起服务

docker compose up -d

实测回显：

 Network shadowsocks_default Creating
 Network shadowsocks_default Created
 Container ss-server Creating
 Container ss-server Created
 Container ss-server Starting
 Container ss-server Started

4.3 查看状态

docker compose ps

实测回显：

NAME        IMAGE                                  COMMAND                  SERVICE     CREATED        STATUS                  PORTS
ss-server   shadowsocks/shadowsocks-libev:latest   "/bin/sh -c 'exec ss…"   ss-server   1 second ago   Up Less than a second   0.0.0.0:8388->8388/tcp, 0.0.0.0:8388->8388/udp, [::]:8388->8388/tcp, [::]:8388->8388/udp

4.4 查看启动日志

docker logs ss-server

实测回显：

 2026-10-09 02:21:29 INFO: UDP relay enabled
 2026-10-09 02:21:29 INFO: initializing ciphers... aes-256-gcm
 2026-10-09 02:21:29 INFO: using nameserver: 8.8.8.8,8.8.4.4
 2026-10-09 02:21:29 INFO: tcp server listening at 0.0.0.0:8388
 2026-10-09 02:21:29 INFO: udp server listening at 0.0.0.0:8388

看到 tcp/udp server listening at 0.0.0.0:8388 即服务已就绪。

4.5 校验环境变量注入

docker exec ss-server env | grep -E "SERVER_PORT|METHOD|PASSWORD"

实测回显：

SERVER_PORT=8388
METHOD=aes-256-gcm
PASSWORD=q1w2e3r4

五、客户端编排（ss-local）

需要把服务端流量转成本地 socks5（如本机浏览器/应用使用）时，增加一个 ss-local 服务。以普通用户进程方式访问服务端 8388，本地暴露 1080：

services:
  ss-local:
    image: shadowsocks/shadowsocks-libev:latest
    container_name: ss-local
    command: ss-local -s 127.0.0.1 -p 8388 -l 1080 -k q1w2e3r4 -m aes-256-gcm -t 300
    network_mode: host
    restart: unless-stopped

⚠️ 注意：network_mode: host 让 ss-local 直接监听宿主机 1080，便于本机程序通过 127.0.0.1:1080 使用；-s 127.0.0.1 为单机演示值（服务端即本机），跨机部署时换成服务端公网/内网 IP。若改用默认 bridge，则需将 -l 端口映射 1080:1080 到宿主机。

六、数据持久化说明

Shadowsocks 本身是无状态代理，不写业务数据，因此一般无需数据持久化卷。仅需关注三类持久化：

对象	是否需要持久化	处理方式
配置（JSON 文件）	建议	挂载 `-v /opt/shadowsocks:/etc/shadowsocks-libev` 见第八节
密码/端口等	随环境变量	写入 compose 的 `environment` 或 `.env` 文件
日志	可选	用 `docker logs` 查看，无需挂载

容器重启会沿用 compose 声明的环境变量自动重建，无需额外持久化即可保证「重启后配置不变」。

七、常用环境变量表

镜像内置默认值如下（docker inspect 实测）：

环境变量	默认值	说明
SERVER_ADDR	0.0.0.0	服务端监听地址
SERVER_PORT	8388	服务端端口（TCP/UDP）
PASSWORD	`$(hostname)`	密码；不设时用容器 hostname 兜底，务必显式设置
METHOD	aes-256-gcm	加密方式
TIMEOUT	300	socket 超时（秒）
DNS_ADDRS	8.8.8.8,8.8.4.4	内部 DNS 服务器，逗号分隔
TZ	UTC	时区，可设 `Asia/Shanghai`
ARGS	空	追加到启动命令尾部的额外参数

💡 说明：所有变量均可在 compose 的 environment: 中逐项覆盖；ARGS 常用来追加 -v（verbose 日志）或 --reuse-port。

八、常用配置参数说明（command）与配置持久化

镜像的默认 command 由 GitHub 上模板脚本拼装而成（见第二节等价命令）。要精细控制，可在 compose 中显式覆盖 command。例如把配置文件方式改为走 JSON 并开启 UDP 中继：

services:
  ss-server:
    image: shadowsocks/shadowsocks-libev:latest
    container_name: ss-server
    command: ss-server -c /etc/shadowsocks-libev/config.json -u
    volumes:
      - /opt/shadowsocks/conf:/etc/shadowsocks-libev
    ports:
      - "8388:8388"
      - "8388:8388/udp"
    restart: unless-stopped

宿主机侧配置 /opt/shadowsocks/conf/config.json：

{
    "server":"0.0.0.0",
    "server_port":8388,
    "mode":"tcp_and_udp",
    "password":"q1w2e3r4",
    "method":"aes-256-gcm",
    "timeout":300
}

⚠️ 注意：使用 command 覆盖后，环境变量（SERVER_ADDR 等）不再自动生效，需统一用配置文件或 -s/-p/-k 命令行参数指定，避免两套配置冲突。配置文件目录挂载路径对应镜像内 /etc/shadowsocks-libev。

九、等价 docker run 运行方式

不写 compose 时，可用单条 docker run 达到相同效果：

docker run -d \
  --name ss-equiv-run \
  -e SERVER_ADDR=0.0.0.0 \
  -e SERVER_PORT=8388 \
  -e PASSWORD=q1w2e3r4 \
  -e METHOD=aes-256-gcm \
  -e TIMEOUT=300 \
  -e DNS_ADDRS=8.8.8.8,8.8.4.4 \
  -p 8388:8388 \
  -p 8388:8388/udp \
  --restart unless-stopped \
  shadowsocks/shadowsocks-libev:latest

实测回显（查看进程）：

docker ps --filter name=ss-equiv-run --format "{{.Names}} | {{.Status}} | {{.Ports}}"

ss-equiv-run | Up 1 second | 0.0.0.0:8388->8388/tcp, 0.0.0.0:8388->8388/udp, [::]:8388->8388/tcp, [::]:8388->8388/udp

实测回显（日志）：

 2026-10-09 02:21:54 INFO: UDP relay enabled
 2026-10-09 02:21:54 INFO: initializing ciphers... aes-256-gcm
 2026-10-09 02:21:54 INFO: using nameserver: 8.8.8.8,8.8.4.4
 2026-10-09 02:21:54 INFO: tcp server listening at 0.0.0.0:8388
 2026-10-09 02:21:54 INFO: udp server listening at 0.0.0.0:8388

十、常用运维命令

# 查看编排中定义的服务
docker compose config --services

# 查看镜像与版本
docker compose images

# 滚动查看实时日志（后 N 行）
docker compose logs -f --tail 100

# 重启服务
docker compose restart

# 停止（保留容器）
docker compose stop

# 完整移除容器与网络，再重新拉起
docker compose down
docker compose up -d

# 停止并删除名为 ss-server 的容器
docker stop ss-server && docker rm ss-server

docker compose down 实测回显：

 Container ss-server Stopping
 Container ss-server Stopped
 Container ss-server Removing
 Container ss-server Removed
 Network shadowsocks_default Removing
 Network shadowsocks_default Removed

十一、常见问题（FAQ）

Q1：docker compose up -d 报 failed to resolve reference ... registry-1.docker.io？

拉不动公共仓库镜像。用 docker pull shadowsocks/shadowsocks-libev:latest 单独拉取确认网络可通，失败则通过 docker save | docker load 从内网镜像源导入，或将 compose 的 image: 改为内网私有仓库地址。

Q2：docker run 报 Bind for 0.0.0.0:8388 failed: port is already allocated？

端口已被占用。用 ss -tlnp | grep 8388（或 docker compose down）释放端口，或改 SERVER_PORT/映射端口。

Q3：容器起来了但连不上？

先 docker logs ss-server 看是否出现 tcp server listening at 0.0.0.0:8388；再检查宿主机安全组是否放行 8388 TCP/UDP；最后确认两端 PASSWORD 与 METHOD 一致。若用 command 覆盖了启动方式，注意环境变量不再生效。

Q4：PASSWORD 未设置导致用 $(hostname) 兜底？

默认镜像在未设 PASSWORD 时用容器 hostname 作密码，极易在重建容器后因 hostname 变化导致对端连不上。务必在 compose/docker run 中显式设置 PASSWORD。

Q5：如何同时提供 socks5 给本机使用？

启用客户端的 ss-local 服务并映射/复用本机 1080 端口（见第五节客户端编排）。

十二、参考链接

shadowsocks-libev 官方 Docker 镜像：https://hub.docker.com/r/shadowsocks/shadowsocks-libev
shadowsocks-libev 官方仓库：https://github.com/shadowsocks/shadowsocks-libev