benyoo/squid repository overview

⁠SquidDocker

⁠🚀 概述

本项目基于 benyoo/rockylinux:9-20260615 把生产环境 Squid 5.5 的运行方式容器化，并保留按客户端 IP 管理域名白名单的 squid-node-whitelist。

生产配置不写入镜像。镜像只包含一份安全的首次启动模板；当挂载目录没有 squid.conf 时，容器会自动初始化模板，已有生产配置绝不覆盖。容器只挂载 /data/squid-docker/ 下的生产运行数据；配置文件发生变化后，会先执行语法检查，检查通过才热重载 Squid。Git 项目文件不作为生产容器的挂载源。

⁠📦 当前版本

推荐使用日期标签 benyoo/squid:rockylinux9-20261030；latest 对应同一双架构镜像。本次增加日志治理参数，生产升级需要另行安排。

源码：DSTW-Squid-Proxy⁠；完整使用文档⁠。维护者：Manta [email protected]⁠。许可证遵循源码及所包含软件各自的既有声明，本次未新增或变更授权。

2026-10-30 参数化版本发布记录：镜像源码提交 d69cdeddf1e0e8b117248905b8451ef35702d95e；rockylinux9-20261030 与 latest 的索引 digest 均为 sha256:79619c4c332dff2a0894ae12585d3644760b81c968955b991c0dfa7b41c273ce。每架构 8 项回归及自定义策略运行验证通过；发布后已按 digest 拉取 amd64、arm64（QEMU），健康、源码标识、参数化自动轮转及代理请求均通过。原同名镜像已留存备份，未部署生产。

2026-10-30 首版发布记录：rockylinux9-20261030 的镜像源码提交为 5ef194ee25f5c6a3215f1de5a7dc38b60e5e8718，索引 digest 为 sha256:8423c6248a4e6dc42f2a6bb970a3910bff5420b0c9a8ea9173a83fa2323576fe；该版曾作为 latest。两个架构均已通过发布检查，未部署生产。

⁠✨ 能力矩阵

⁠🧩 目录与挂载

DSTW-Squid-Proxy/
├── SquidDocker/
│   ├── Dockerfile
│   ├── Dockerfile.dockerignore
│   ├── docker-compose.yml
│   ├── build-multiarch.sh
│   ├── runtime/
│   │   ├── squid-entrypoint
│   │   ├── squid-reload-watch
│   │   └── supervisord.conf
│   └── docker-compose.yml
└── squid/

Git 项目目录和生产运行目录相互独立。Compose 按公司规范只使用 /data/squid-docker/ 下的生产绝对路径：

/data/squid-docker/
├── docker-compose.yml
├── etc/
│   └── squid/                -> /etc/squid (rw)
└── var/
    ├── log/squid/            -> /var/log/squid (rw)
    └── spool/squid/          -> /var/spool/squid (rw)

配置目录使用读写挂载，是因为 squid-node-whitelist 需要更新：

/etc/squid/node-rules.d/
/etc/squid/node-domains.d/
/etc/squid/backups/node-whitelist/

squid-node-whitelist 不由 Compose 从 Git 项目挂载。Dockerfile 会把 Git 管理的 squid/squid-node-whitelist 安装到镜像内的 /usr/local/sbin/squid-node-whitelist。脚本变更必须构建并发布新镜像，生产环境再切换镜像版本，避免生产容器依赖 Git 工作区。

CA 私钥只允许通过运行时配置目录挂载。Dockerfile.dockerignore 已将整个生产配置树排除在构建上下文之外，镜像中不包含任何证书、私钥或白名单数据。

⁠▶️ 启动

在生产主机准备独立运行目录：

install -d \
    /data/squid-docker/etc/squid \
    /data/squid-docker/var/log/squid \
    /data/squid-docker/var/spool/squid

把当前生产机 /etc/squid/ 的有效配置通过受控发布流程同步到 /data/squid-docker/etc/squid/，并把发布版本中的 docker-compose.yml 放到 /data/squid-docker/docker-compose.yml。不要用 Git 仓库中的配置快照覆盖生产配置。

随本版本提供的 Compose 已固定镜像标签：

image: benyoo/squid:rockylinux9-20261030

自行构建时，构建脚本按 Asia/Shanghai 当天日期生成标签；请根据实际产物更新 Compose 的 image。升级已有部署时保留配置、日志与缓存目录。新的 Docker 日志限制需要重建容器才会生效，不能只执行热重载。

启动：

cd /data/squid-docker
docker compose up -d

如果 /data/squid-docker/etc/squid/squid.conf 不存在，入口脚本会自动初始化一份默认拒绝外部代理访问、但支持 squid-node-whitelist 的安全配置。生产 SSL-Bump 配置仍需通过受控流程部署 CA 文件和正式配置。

当正式配置包含 generate-host-certificates=on 且缓存卷是空目录时，入口脚本会自动初始化 /var/spool/squid/ssl_db；已有数据库不会重复创建。

查看状态：

docker compose ps
docker logs squid
docker inspect --format '{{.State.Health.Status}}' squid
docker exec squid supervisorctl status

项目使用 network_mode: host，Squid 直接监听宿主机 3128。启动容器前必须先停止或迁移宿主机上占用该端口的 Squid；不要让宿主机服务和容器同时监听 3128。

⁠🔁 配置自动生效

容器递归监听 /etc/squid。检测到配置变化后执行：

squid -k parse -f /etc/squid/squid.conf
squid -k reconfigure -f /etc/squid/squid.conf

语法检查失败时不会热重载，当前 Squid 进程继续使用已加载的旧配置。查看失败原因：

docker logs --tail 100 squid

备份目录 /etc/squid/backups/ 不参与监听，避免白名单工具生成备份时触发无意义重载。

⁠🗜️ 日志轮转与空间限制

Supervisor 管理 squid-logrotate，启动时立即检查，之后按配置间隔执行。仅管理 /var/log/squid/ 中的 access.log、cache.log 和可选的 store.log。默认策略如下：

⁠参数配置

更新后的 rockylinux9-20261030 支持下列参数；早期同名镜像尚不支持，需要重新拉取并重建容器才会生效。Squid 策略通过容器环境变量配置，Docker 日志限制通过 Compose 所在目录的 .env 或宿主机环境变量配置。

Squid 的整数字段及大小的数字部分范围为 1 至 999999999，不接受 0、负数、小数或前导零。未设置时使用默认值；直接设置为空或非法值会在启动 Squid 前报错退出。maxage 始终以天为单位，不随 PERIOD 变化；归档份数与保留天数同时约束，先达到的限制先清理。

Compose 中的 ${变量-默认值} 是合法插值语法，只在变量未定义时使用默认值；这里保留显式空值以触发启动校验。${变量:-默认值} 则在未定义或为空时都使用默认值，Docker 日志的两个参数沿用这种写法。

本次参数化候选镜像已在指定 Rocky Linux 10.2 节点完成 amd64、arm64（QEMU）构建，每架构 8 项回归通过（含 17 组非法参数）。实测一秒检查、1 KiB 提前轮转、两份未压缩归档及重启状态复用；Compose 的默认值、自定义值和两种空值插值语义均已验证。生产部署需要另行授权。

例如在 Compose 所在目录的 .env 中配置：

SQUID_LOGROTATE_INTERVAL=60
SQUID_LOGROTATE_PERIOD=daily
SQUID_LOGROTATE_MAXSIZE=50M
SQUID_LOGROTATE_COUNT=30
SQUID_LOGROTATE_MAXAGE=7
SQUID_LOGROTATE_COMPRESS=true
DOCKER_LOG_MAX_SIZE=20m
DOCKER_LOG_MAX_FILE=5

此示例表示每分钟检查，每日或超过 50 MiB 轮转，压缩归档，最多保留 30 份并在轮转时清理超过 7 天的归档。修改参数后需要在获授权部署时重建容器。入口脚本验证参数并生成 /run/logrotate-squid.conf，不会修改挂载的 Squid 配置；状态仍保存在日志卷。Docker 的两个参数属于宿主机 Compose 插值，单纯用 docker run -e 设置它们不会改变日志驱动，直接运行时应使用 --log-opt。

大小阈值（默认 100 MiB）在定期检查时生效，不是实时磁盘硬上限；高流量时文件可能在两次检查之间超过该值。归档份数（默认 14 份）包含大小触发的轮转，因此高流量时可能保留不到指定天数；过期清理在轮转时执行，不是精确到秒的删除。

为兼容已有挂载配置，使用 copytruncate，保留正在写入文件的 inode，无需改 Squid 配置或重启代理。复制与截断之间的短暂窗口可能丢失少量日志，不适用于要求零丢失的审计归档。轮转时还需要容纳未压缩副本的临时空间。自定义到其他路径的日志和历史上由其他工具生成的归档不在本规则管理范围内。

Docker 日志限制只影响容器标准输出/标准错误；文件日志由上述 logrotate 规则单独管理。Compose 日志配置需要在后续获授权部署时重建容器才会生效。

轮转以镜像内 squid 用户执行，已有挂载日志应保持 Squid 的文件属主与读写权限；入口脚本只校正目录属主，不递归修改历史文件。宿主机不应再对这些相同文件执行另一套轮转任务。

查看检查进程与轮转状态（新参数化镜像的规则位于 /run；已发布旧镜像仍使用 /etc/logrotate-squid.conf）：

docker exec squid supervisorctl status squid-logrotate
docker exec squid logrotate --debug \
    --state /var/log/squid/.logrotate.status /run/logrotate-squid.conf

在一次性测试容器内运行回归验证（不要针对生产容器运行）：

docker run --rm --entrypoint python3 \
    -v "$PWD/SquidDocker/tests/test-logrotate.py:/tmp/test-logrotate.py:ro" \
    <本次测试镜像> /tmp/test-logrotate.py

2026-10-30 在指定 Rocky Linux 10.2 构建节点完成 amd64 和 arm64（QEMU）构建，各架构 5 项回归通过，覆盖压缩内容、原文件句柄继续写入、归档数量与过期清理、每日/大小阈值和状态复用。两个架构均完成 Supervisor 启动、实际代理请求日志与容器重启验证；Docker 写入 35 MiB 标准输出后保留 3 份约 10 MB 的日志。发布候选镜像再次通过各架构 5 项回归；已发布镜像，未部署生产，未做 arm64 原生及生产流量验收。

⁠🧰 squid-node-whitelist

查看节点白名单：

docker exec squid \
    squid-node-whitelist --mode list 192.0.2.10

追加域名并立即检查、热重载：

docker exec squid \
    squid-node-whitelist --apply 192.0.2.10 ".example.com api.example.net"

容器内 --apply 在语法检查通过后执行 squid -k reconfigure，并通过 squid -k check 确认进程状态；在原有宿主机环境中仍使用 systemctl reload squid，不会改变当前生产机的操作方式。

完整参数见 squid-node-whitelist.md⁠。

⁠🏗️ 多架构构建

构建脚本会根据执行时 Asia/Shanghai 的当天日期自动生成镜像名：

cd DSTW-Squid-Proxy/SquidDocker
SQUID_IMAGE_TAG=rockylinux9-20261030 ./build-multiarch.sh

本次指定日期标签后生成：

benyoo/squid:rockylinux9-20261030
SquidDocker/out/squid-rockylinux9-20261030.oci.tar

从 Docker Hub 拉取：

docker pull benyoo/squid:rockylinux9-20261030

SQUID_IMAGE_TAG 可覆盖默认日期标签。本次参数化修订沿用 rockylinux9-20261030 并同步 latest；如需固定镜像内容，请使用已记录的 digest。确认需要直接推送 DockerHub 时执行 SQUID_IMAGE_TAG=rockylinux9-20261030 ./build-multiarch.sh --push。脚本只通过 Docker 已配置的登录状态认证，不读取或输出 Token。

⁠⚠️ 生产迁移门槛

• 容器使用主机网络，但 F5 到 Squid 后端仍必须保留真实客户端源 IP。
• 切换前先执行 squid -k parse，再验证容器健康状态和代理请求。
• 生产配置应从当前生产环境 /etc/squid 受控同步到 /data/squid-docker/etc/squid，不能以 Git 仓库中的旧快照覆盖生产白名单。
• 宿主机 Squid 和容器 Squid 的 3128 端口切换需要维护窗口与明确回滚步骤。

详细 HA 和 F5 约束见 Squid F5 高可用与 Docker 化架构设计⁠。

概览来源：源码仓库 SquidDocker/README.md，文档提交 085767644541399641d9660d7b41ab68b1cf7720。公开示例地址采用文档保留网段。