software

🚀 SWAG：将彻底革新您的 homelab 的 Reverse Proxy Docker！

发布: (2025年12月7日 GMT+8 16:14)
7 min read
原文: Dev.to

Source: Dev.to

那么 SWAG 到底是什么？

SWAG 是一个基于 nginx 的一体化反向代理，能够自动管理 Let’s Encrypt SSL 证书。简而言之，它就是你的数字门卫，能够：

  • 🔒 自动使用 SSL 证书为你的服务加密
  • 🌐 在干净的子域名上公开 Docker 服务
  • 🛡️ 通过集中式认证保护你的应用
  • 📋 用简洁的配置完成以上所有工作

为什么选择 SWAG 而不是别的方案？

在使用 SWAG 之前，我一直在用普通的 nginx 加 certbot……真是麻烦！证书续期经常出错、nginx 配置需要手动维护、域名管理也很头疼。SWAG 一次性解决了这些问题：

  • 自动通配符证书
  • 为流行服务预置的配置
  • 与 Docker 原生集成
  • 支持多种认证方式（Authelia、OAuth 等）

我们的目标架构

在你的运营商处的配置（以 Free 为例）

  1. 登录 Freebox 管理界面：
  2. Freebox 参数 → 端口管理
  3. 创建端口转发：
外部端口内部端口目标 IP协议
443 (HTTPS)443192.168.1.100（示例）TCP
80 (HTTP)80192.168.1.100TCP

💡 安全小贴士：不要直接暴露 80/443 端口，可以使用自定义端口（例如 8443）并进行转发。

DuckDNS 配置

  1. 在 DuckDNS 注册账号
  2. 创建你的域名：monhomelab.duckdns.org
  3. 记录下你的 token（后面会在 Docker 中使用）

其他 DNS 提供商

免费收费
DuckDNSCloudflare
FreeDNSOVH
No‑IPGandi
Route53
DigitalOcean
Namecheap

Cloudflare 示例配置：

environment:
  - URL=mondomaine.com
  - VALIDATION=dns
  - DNSPLUGIN=cloudflare
  - EMAIL=votre-email@example.com
  - CLOUDFLARETOKEN=votre-api-token-cloudflare

公网 IP 检查

# 检查你的公网 IP
curl ifconfig.me
# 检查 DuckDNS 是否指向该 IP
nslookup monhomelab.duckdns.org

如果两者 IP 一致，说明配置正确 🎯

连通性测试

# 在本地服务器启动一个简易的 Web 服务
python3 -m http.server 8080
# 从外部使用域名进行访问测试
curl http://monhomelab.duckdns.org:8080

如果能够正常返回，则可以继续部署 SWAG！

使用 Docker Compose 安装

环境变量准备

version: "3.8"

networks:
  web-proxy:
    external: false

services:
  swag:
    image: lscr.io/linuxserver/swag:latest
    container_name: swag
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - URL=monhomelab.duckdns.org      # 你的 DuckDNS 域名
      - VALIDATION=duckdns              # 使用 DuckDNS 进行验证
      - DUCKDNSTOKEN=12345678-1234-1234-1234-123456789012  # 你的 DuckDNS token
      - SUBDOMAINS=wildcard             # 生成 *.monhomelab.duckdns.org 通配符证书
      - EMAIL=votre-email@example.com
      - ONLY_SUBDOMAINS=false           # 让主域名也能正常工作
    volumes:
      - ./swag/data:/config
    ports:
      - "80:80"     # HTTP（会重定向到 HTTPS）
      - "443:443"   # HTTPS（你的服务将通过此端口安全访问）
    networks:
      - web-proxy
    restart: unless-stopped

关键变量说明

  • URL ：完整域名（DuckDNS、Cloudflare 等）
  • VALIDATION ：根据 DNS 提供商选择的验证方式
  • SUBDOMAINS=wildcard ：为所有子域名生成证书
  • DUCKDNSTOKEN ：DNS 提供商的 token/API key
  • ONLY_SUBDOMAINS=false ：同时支持根域名访问

启动 SWAG

docker-compose up -d swag
docker logs swag   # 你应该能看到 “Server ready” 与 “Certificate renewal successful”

创建的目录结构

swag/data/
├── nginx/
│   ├── nginx.conf
│   ├── site-confs/
│   └── proxy-confs/     # ← 各服务的代理配置
├── keys/
│   └── letsencrypt/     # ← SSL 证书存放位置
└── log/

添加我们的第一个服务

服务 1 ：Home Assistant

在同一个 docker‑compose.yml 中加入以下内容：

  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./homeassistant/data:/config
    networks:
      - web-proxy
    ports:
      - "8123:8123"   # 可选，供本地直接访问
    restart: unless-stopped

在 SWAG 中配置代理

在 swag/data/nginx/proxy-confs/ 目录下创建文件 homeassistant.subdomain.conf：

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name homeassistant.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

    # 支持 WebSocket（Home Assistant 必需）
    location /api/websocket {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

配置测试

# 确认容器已启动
docker ps | grep homeassistant

# 从外部访问测试
curl -k https://homeassistant.monhomelab.duckdns.org

如果返回 Home Assistant 的登录页面，说明配置成功。

网络故障排查

专用 Docker 网络

确保所有服务（SWAG、Home Assistant 等）都在同一个 Docker 网络 web-proxy 中。这样代理才能通过容器名称（homeassistant、swag 等）直接访问，而无需在外部暴露端口。

日志管理

docker logs swag          # 反向代理日志
docker logs homeassistant

SWAG 的日志同样会写入 swag/data/log/ 目录。

配置检查

  • 确认证书已生成：
    ls swag/data/keys/letsencrypt/live/monhomelab.duckdns.org/
  • 测试 HTTP → HTTPS 重定向：
    curl -I http://monhomelab.duckdns.org

通配符证书

SWAG 会自动为 *.monhomelab.duckdns.org 生成通配符证书，无需为每个子域单独申请。

使用 Authelia 加固（可选）

可以将 Authelia 作为身份验证中间件加入：

  authelia:
    image: authelia/authelia
    container_name: authelia
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./authelia/config:/config
    networks:
      - web-proxy
    restart: unless-stopped

随后在对应服务的代理配置中加入：

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        auth_request /authelia;
        auth_request_set $user $upstream_http_remote_user;
        proxy_set_header Remote-User $user;
        # …
    }

详细配置请参考 Authelia 官方文档。

最终效果

  • 唯一入口 https://monhomelab.duckdns.org，通过子域名分发到各个服务
  • SSL 证书自动续期
  • 日志与 Docker 网络统一管理

常见调试表

问题检查项解决方案
证书未生成docker logs swag检查 DuckDNS token 与网络连通性
443 端口被阻断nc -zv your-ip 443确认运营商盒子上的端口转发
服务不可访问curl -I https://homeassistant.monhomelab.duckdns.org确认容器在同一 Docker 网络
DNS 未指向正确 IPnslookup monhomelab.duckdns.org更新 DuckDNS 或其他 DNS 提供商的记录

结论

SWAG 极大简化了在 homelab 中部署带 SSL 的反向代理。结合 Docker、DuckDNS（或其他 DNS）以及预置配置，你可以省时、省力并提升安全性与灵活性。

延伸阅读

  • SWAG 官方文档
  • 支持的 DNS 提供商完整列表
  • Authelia 教程
  • 完整示例栈（Traefik、Portainer 等）
Back to Blog

相关文章

阅读更多 »