使用 Quadlet 部署 Warpgate 无根容器的踩坑总结

记录了在使用 Podman以无根容器（Rootless）方式部署 Warpgate 时遇到的坑.

目标环境:

• 容器引擎: Podman (无根模式)
• 服务管理: Systemd / Quadlet
• 反向代理: Caddy (同样为无根容器)
• 网络: Caddy 和 Warpgate 位于同一个自定义 Podman 网络中。

坑一：服务无法启动，提示 warpgate.yaml 配置文件不存在

#

这是部署过程中的第一个障碍。通过 systemctl 启动服务后，日志反复显示 Warpgate 因找不到 /data/warpgate.yaml 配置文件而失败退出。

解决方案：使用 podman run 执行一次性 setup 命令

#

Warpgate 的设计是在首次运行时，通过一个交互式的 setup 命令来生成配置文件，而不是手动创建。Quadlet 用于管理长期服务，因此需要先用 podman run 手动完成这个一次性的设置任务。

1. 执行 setup 命令: 该命令会启动一个临时容器，运行交互式设置向导，并将生成的配置存入一个 Podman 卷中。

   1	podman run -it --rm --name warpgate-setup -v warpgate-data:/data --network=caddy ghcr.io/warp-tech/warpgate:latest setup

   • -it: 启用交互式终端，用于回答设置向导的问题。
   • --rm: 命令结束后自动删除这个临时容器。
   • -v warpgate-data:/data: 使用名为 warpgate-data 的卷来持久化配置，这个卷之后会被 Quadlet 服务使用。

2. 使用 Quadlet 运行服务: setup 完成后，warpgate-data 卷里就已经有配置文件了。此时 systemctl 启动的服务就可以找到配置，并正常运行了。

坑二：服务正常运行，但 Caddy 反向代理报 502 Bad Gateway

#

Warpgate 容器成功启动并监听端口，但在通过 Caddy 反代访问时，浏览器显示 502 错误。

解决方案：将 Caddy 反代协议从 HTTP 修改为 HTTPS

#

经排查，问题的根源在于 Warpgate 内部的 8888 端口正在监听 HTTPS 流量，而不是常规的 HTTP。这很可能是在交互式 setup 过程中，当被问及 Public URL 时，输入了 https:// 开头的地址，Warpgate 据此自动启用了内部 TLS。

Caddy 默认使用 HTTP 连接后端，因此连接被 Warpgate 拒绝，导致 502 错误。

解决方案是修改 Caddyfile，让它使用 HTTPS 连接到 Warpgate，并忽略其内部自签名证书的验证错误。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<your-domain> {
    # ... 其他配置 ...

    # 使用 https 协议反代到 warpgate，并跳过内部通信的 TLS 证书验证
    reverse_proxy https://warpgate:8888 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}

• https://warpgate:8888: 告诉 Caddy 上游是 HTTPS 服务。
• tls_insecure_skip_verify: 告诉 Caddy 忽略上游证书的验证错误，这在反向代理到使用自签名证书的内部服务时是标准做法。

最终配置总结

#

~/.config/containers/systemd/warpgate.container

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[Unit]
Description=Warpgate Secure Access Gateway


[Container]
ContainerName=warpgate
Image=ghcr.io/warp-tech/warpgate:latest
AutoUpdate=image
PodmanArgs=--network=caddy
Volume=warpgate-data:/data

[Service]
Restart=on-failure

[Install]
WantedBy=default.target

Caddyfile 中的相关配置

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<your-domain> {


    encode zstd gzip

    reverse_proxy https://warpgate:8888 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}