lsiodev/swag

SWAG (Secure Web Application Gateway)

概述

SWAG（Secure Web Application Gateway，前身为letsencrypt，与Let's Encrypt™无关联）是一个集成Nginx Web服务器、反向代理、PHP支持、Certbot客户端及fail2ban入侵防护的安全Web应用网关。Certbot客户端可自动完成免费SSL服务器证书（Let's Encrypt和ZeroSSL）的生成与续期流程，为Web应用提供安全访问能力。

核心功能和特性

• Nginx集成：内置Nginx作为Web服务器和反向代理，支持PHP环境
• 自动SSL管理：通过Certbot客户端自动生成、续期Let's Encrypt和ZeroSSL免费SSL证书
• 入侵防护：集成fail2ban工具，提供基础入侵检测与防护
• 灵活验证方式：支持HTTP和DNS两种证书验证方式
• 证书兼容性：自动生成PFX和PEM格式证书，适用于Emby、Znc等其他应用
• 安全增强：默认使用符合RFC7919标准的ffdhe4096作为dhparams.pem
• 预设反向代理配置：提供常用应用的预设反向代理配置文件

使用场景

• 需要为多个Web应用提供统一反向代理的场景
• 需自动管理SSL证书的个人或小型企业Web服务
• 希望增强Web服务安全性（含入侵防护、HTTPS强制）的部署环境
• 需要跨容器共享SSL证书的多容器应用架构

使用方法和配置说明

验证和初始设置

运行前准备

• 确保域名及子域名已正确转发至容器所在主机，且主机上443端口（及80端口，如使用）未被其他服务占用（如NAS管理界面、其他Web服务器等）
• 若需动态DNS，可使用免费服务duckdns.org，配合linuxserver/duckdns镜像更新IP。URL格式为yoursubdomain.duckdns.org，子域名可设为www,ftp,cloud（HTTP验证）或wildcard（DNS验证）

证书验证方式

• HTTP验证：需将路由器互联网侧的80端口转发至容器的80端口
• DNS验证：需在/config/dns-conf目录下对应插件的ini（或部分插件的json）文件中填入凭据
  • Cloudflare提供免费DNS管理服务，建议设置为"仅DNS"模式（而非"DNS+代理"）
  • Google DNS插件适用于"Google Cloud DNS"（付费企业服务），不支持"Google Domains DNS"
  • DuckDNS仅支持两种DNS验证证书：主域名证书（SUBDOMAINS留空）或通配符证书（SUBDOMAINS设为wildcard）

必要配置

• 必须添加--cap-add=NET_ADMIN参数，确保fail2ban能修改iptables规则
• 容器启动后，通过https://yourdomain.url访问默认主页（HTTP访问默认禁用，可编辑/config/nginx/site-confs/default.conf启用）
• 证书每日检查，过期前30天自动尝试续期。建议配置***参数，接收Let's Encrypt的证书过期通知

Certbot插件

SWAG内置多种Certbot插件，若需额外插件，可通过以下步骤安装：

1. 使用Universal Package Install Docker Mod，设置容器环境变量：

   yaml
   DOCKER_MODS=linuxserver/mods:universal-package-install
   INSTALL_PIP_PACKAGES=certbot-dns-<插件名>
   

2. 在/config/dns-conf/<插件名>.ini中填入插件所需凭据（参考插件文档）

3. 建议先设置STAGING=true测试插件功能，确认正常后再正式申请证书

安全和密码保护

证书自动更新

容器启动时会检测URL和子域名变化，自动吊销旧证书并生成新证书

密码保护（htpasswd）

• 生成密码文件：在主机执行docker exec -it swag htpasswd -c /config/nginx/.htpasswd <用户名>（首次创建用户，-c为创建文件）
• 添加其他用户：执行docker exec -it swag htpasswd /config/nginx/.htpasswd <用户名>（不含-c，避免覆盖现有文件）

LDAP认证

可通过LDAP进行安全和访问控制，需配合独立镜像linuxserver/ldap-auth与LDAP服务器通信。容器提供可配置的示例ldap.conf文件

站点配置和反向代理

默认配置

• 默认站点配置位于/config/nginx/site-confs/default.conf，可修改此文件或添加其他.conf文件至该目录。若删除default.conf，容器启动时会自动生成新文件

预设反向代理配置

• 容器提供常用应用的预设反向代理配置，存放于/config/nginx/proxy_confs目录，参考该目录下README.md启用方法。预设配置来源于https://github.com/linuxserver/reverse-proxy-confs

搜索引擎隐藏

在站点配置的server块中、ssl.conf引用行上方添加：

nginx
add_header X-Robots-Tag "noindex, nofollow, nosnippet, noarchive";

可请求搜索引擎不索引站点，注意：长期启用会导致站点从搜索引擎中移除

HTTP转HTTPS重定向

需暴露80端口并配置相应重定向规则

使用 certs 在其他容器中

容器自动生成其他应用（如Emby、Znc）所需的证书文件，包括：

• Certbot生成的cert.pem、chain.pem、fullchain.pem、privkey.pem
• 自动转换的privkey.pfx（Windows/.NET应用支持，无密码）
• priv-fullchain-bundle.pem（私钥与证书链捆绑，适用于Znc等应用）

证书共享方法

1. 简易方式：将SWAG的/config目录挂载至其他容器（如-v /path-to-swag-config:/swag-ssl），证书路径为/swag-ssl/keys/letsencrypt/
2. 安全方式：仅挂载/config/etc目录（如-v /path-to-swag-config/etc:/swag-ssl），证书路径为/swag-ssl/letsencrypt/live/<your.domain.url>/（仅共享证书，不暴露完整配置）

使用 fail2ban

默认启用的Jail

容器默认启用5个fail2ban jail：

1. nginx-http-auth
2. nginx-badbots
3. nginx-botsearch
4. nginx-deny
5. nginx-unauthorized

常用命令

• 查看所有活跃jail：docker exec -it swag fail2ban-client status
• 查看特定jail状态：docker exec -it swag fail2ban-client status <jail名称>
• 解封IP：docker exec -it swag fail2ban-client set <jail名称> unbanip <IP>
• 更多命令参考fail2ban官方文档

配置修改

• 修改jail规则：编辑/config/fail2ban/jail.local（而非.conf文件，.conf会在更新时被覆盖，.local文件优先级更高）
• 修改过滤器/动作：创建与.conf同名的.local文件（如nginx-http-auth.conf对应nginx-http-auth.local），.local内容会追加至.conf

更新配置

配置文件更新策略

• 容器创建的配置文件（如Nginx配置、代理示例）不会自动更新，更新说明见更新日志
• 若已修改的文件在更新日志中有变更：
  1. 保持现有配置（若功能正常）
  2. 参考仓库提交记录手动应用变更
  3. 删除该文件后重启容器，重新生成默认配置并重新应用自定义修改
• 若未修改的文件有变更：删除文件后重启容器，自动生成更新后的配置

反向代理配置更新

• 预设反向代理配置更新不记录在更新日志，可通过https://github.com/linuxserver/reverse-proxy-confs/commits/master%E6%9F%A5%E7%9C%8B%E5%8F%98%E6%9B%B4
• 已重命名启用的代理配置文件（如app.subdomain.conf.sample重命名为app.subdomain.conf）不会自动更新，需手动对比新示例文件调整

从旧镜像迁移

从旧版linuxserver/letsencrypt镜像迁移，请参考官方博客指南

Docker部署示例

docker run命令

bash
docker run -d \
  --name=swag \
  --cap-add=NET_ADMIN \
  -e PUID=1000 \  # 用户ID，默认1000
  -e PGID=1000 \  # 组ID，默认1000
  -e TZ=Etc/UTC \  # 时区，如Asia/Shanghai
  -e URL=yourdomain.url \  # 主域名
  -e VALIDATION=http \  # 验证方式：http或dns
  -e SUBDOMAINS=www, `# 可选，子域名列表，逗号分隔` \
  -e CERTPROVIDER= `# 可选，证书提供商，默认Let's Encrypt` \
  -e DNSPLUGIN=cloudflare `# 可选，DNS验证插件，如cloudflare` \
  -e PROPAGATION= `# 可选，DNS传播等待时间（秒）` \
  -e EMAIL= `# 可选，接收证书通知的***` \
  -e ONLY_SUBDOMAINS=false `# 可选，是否仅为子域名生成证书` \
  -e EXTRA_DOMAINS= `# 可选，额外域名，逗号分隔` \
  -e STAGING=false `# 可选，是否使用测试环境（避免证书申请限制）` \
  -p 443:443 \  # HTTPS端口
  -p 80:80 `# 可选，HTTP端口（用于验证或重定向）` \
  -v /path/to/appdata/config:/config \  # 配置文件挂载路径
  --restart unless-stopped \  # 重启策略
  lscr.io/linuxserver/swag:latest