zzzgr/eddy-proxy repository overview

⁠Eddy Proxy

Eddy Proxy 是一个带 Web 控制台的 HTTP(S) 抓包与调试代理，适合调试浏览器、移动端、桌面应用和后端服务的网络请求。

镜像内已经包含前端和 Go 后端，不需要安装 Node.js、pnpm 或额外的 Web 服务器。

官方镜像提供 linux/amd64 和 linux/arm64 架构：

zzzgr/eddy-proxy:latest

⁠功能

• HTTP/1.1、HTTPS MITM 和 WebSocket 抓包
• 一个端口同时接入 HTTP 代理和 SOCKS5，自动识别协议
• Web 控制台实时查看请求、响应、Header 和 Body
• Map Remote、Map Local、Rewrite、Breakpoint、Throttle、Block
• Repeat、Compose、HAR 和 cURL 导出
• 可选代理鉴权、上游代理和持久化存储
• 有界缓存、流式转发和内存水位控制，适合长时间运行

⁠快速开始

docker run -d \
  --name eddy-proxy \
  --restart unless-stopped \
  -p 8888:8888 \
  -p 9090:9090 \
  -v eddy-proxy-data:/data \
  zzzgr/eddy-proxy:latest

启动后：

• Web 控制台：http://127.0.0.1:9090⁠
• HTTP 代理：http://127.0.0.1:8888
• SOCKS5 代理：socks5://127.0.0.1:8888
• 健康检查：http://127.0.0.1:9090/healthz

首次启动如果没有设置密码，随机密码只会打印在容器日志中：

docker logs eddy-proxy

请登录后立即修改密码。密码哈希保存在 /data/eddy.db 中，重启容器不会重新生成密码。

⁠配置 HTTPS 抓包

1. 打开 Web 控制台，按页面提示生成 Eddy Proxy CA 根证书。
2. 访问 http://<主机地址>:9090/cert 下载证书。
3. 在被调试设备或浏览器中安装并信任该 CA。
4. 将设备代理设置为 <主机地址>:8888。

HTTPS 抓包需要在客户端信任该 CA。对于移动设备，还需要按照系统要求开启用户证书信任；部分 App 使用证书锁定，无法直接进行 MITM。

⁠端口和数据卷

/data 是必须持久化的数据目录，包含：

• SQLite 数据库
• 抓包 Body 文件
• CA 根证书和私钥
• 运行期间保存的管理设置

生产环境建议使用 Docker named volume：

docker volume create eddy-proxy-data

不要删除该卷，否则会丢失抓包记录、密码哈希和 CA 私钥。CA 私钥具有敏感性，请限制卷的访问权限。

⁠修改外部端口

容器内端口默认固定为 8888 和 9090，只需要修改端口映射左侧：

docker run -d \
  --name eddy-proxy \
  --restart unless-stopped \
  -p 18888:8888 \
  -p 19090:9090 \
  -v eddy-proxy-data:/data \
  zzzgr/eddy-proxy:latest

此时访问控制台使用 http://127.0.0.1:19090，客户端代理使用 127.0.0.1:18888。

⁠自定义配置

可以将配置文件挂载为 /data/config.yaml：

docker run -d \
  --name eddy-proxy \
  --restart unless-stopped \
  -p 8888:8888 \
  -p 9090:9090 \
  -v eddy-proxy-data:/data \
  -v "$PWD/config.yaml:/data/config.yaml:ro" \
  zzzgr/eddy-proxy:latest

配置示例见项目中的 config.example.yaml。镜像默认使用以下部署配置：

Web 控制台：0.0.0.0:9090
HTTP 代理：0.0.0.0:8888
SOCKS5 代理：0.0.0.0:8888
数据目录：/data

也可以直接从镜像中导出配置模板：

docker run --rm --entrypoint /bin/cat zzzgr/eddy-proxy:latest \
  cat /etc/eddy-proxy/config.example.yaml > config.example.yaml

镜像中的部署环境变量会覆盖 YAML 中同名配置。需要改变容器内监听地址时，请显式传入环境变量，并同步修改端口映射；通常只修改 -p 左侧即可满足部署需求。

Docker 镜像默认设置 EDDY_PROXY_PORTS_LOCKED=true，因此 Web 控制台不会修改容器内的代理端口；端口由 Docker 的 -p 参数管理。

常用环境变量示例：

docker run -d \
  --name eddy-proxy \
  -p 8888:8888 -p 9090:9090 \
  -v eddy-proxy-data:/data \
  -e EDDY_AUTH_PASSWORD='change-this-password' \
  -e EDDY_CAPTURE_PERSIST=meta \
  -e EDDY_RUNTIME_MEMLIMITMB=1024 \
  zzzgr/eddy-proxy:latest

环境变量名称按配置的 YAML 路径转换，例如：

auth.password              → EDDY_AUTH_PASSWORD
capture.maxFlows           → EDDY_CAPTURE_MAXFLOWS
runtime.memLimitMB         → EDDY_RUNTIME_MEMLIMITMB
log.level                  → EDDY_LOG_LEVEL

直接通过 -e EDDY_AUTH_PASSWORD=... 设置密码时，密码可能出现在 Shell 历史或容器检查信息中；更安全的做法是使用首次启动时生成的随机密码，登录后在控制台修改。

⁠反向代理和公网部署

Web 管理端口拥有控制台和管理 API。不要在不设防的情况下将 9090 暴露到公网。

推荐方案：

• 代理端口 8888 仅开放给需要抓包的客户端或内网
• 使用 Nginx、Caddy 或 Traefik 为 Web 控制台提供 HTTPS
• 使用强密码，并保护 /data 卷和 CA 私钥
• 如果不需要持久化 Body，可将 capture.persist 设置为 none 或 meta

Eddy Proxy 只能用于你有权调试的设备、服务和网络流量。

⁠升级

数据保存在独立的 Docker volume 中，升级镜像不会自动删除数据：

docker pull zzzgr/eddy-proxy:latest
docker rm -f eddy-proxy
docker run -d \
  --name eddy-proxy \
  --restart unless-stopped \
  -p 8888:8888 -p 9090:9090 \
  -v eddy-proxy-data:/data \
  zzzgr/eddy-proxy:latest

正式环境建议固定到具体版本标签，并在升级前备份 /data。

⁠本地构建

docker build -t eddy-proxy:local .

运行本地镜像时，将上面命令中的 zzzgr/eddy-proxy:latest 替换为 eddy-proxy:local。

⁠故障排查

查看启动日志：

docker logs -f eddy-proxy

检查容器状态：

docker inspect --format='{{.State.Health.Status}}' eddy-proxy
curl http://127.0.0.1:9090/healthz

如果 HTTP 请求可以通过代理但 HTTPS 没有明文内容，通常是客户端尚未安装并信任 Eddy Proxy CA，或目标 App 启用了证书锁定。