企业官网建设流程全解析

• 后端
• 存储
• 运维

导读

本指南基于 Backrest 官方 Cookbook 中的 Reverse Proxy Examples（docs/src/cookbooks/reverse-proxy-examples.md），完整讲解如何用 Caddy 反向代理来"前置保护" Backrest 的 Web 端点：包括 docker-compose 编排、Caddyfile 配置、TLS 证书策略与安全注意点。读完你将掌握：Backrest 的端口与环境变量机制、Caddy 与 Backrest 容器同栈部署的完整模板，以及反向代理场景下容易被忽略的保活与安全细节。

1. 为什么需要给 Backrest 配反向代理

Backrest 是一个面向 restic 备份的 Web UI 与编排器。它默认只监听本机回环地址，端口为9898，这一点可以从源码得到直接印证：internal/env/environment.go中BindAddress()的默认返回值是127.0.0.1:9898，只有当显式设置BACKREST_PORT环境变量或--bind-address命令行参数时才会改变绑定地址（例如设为0.0.0.0:9898才会监听所有网卡，install.sh 也提供了--allow-remote-access作为一键开启远程监听的快捷方式）。

也就是说：开箱即用的 Backrest 只对本地用户开放。如果你希望：

• 在公网或内网其他设备上安全地访问备份管理界面；
• 统一由域名、HTTPS 证书、认证入口来管控流量；
• 把 Web UI 和其他服务收敛到同一个网关后面；

那么就需要一个反向代理（reverse proxy）把外部的 HTTPS 请求转发给 Backrest 的9898端口。官方 Cookbook 以 Caddy 和 Traefik 为例说明这类配置——本文详细展开 Caddy 的完整落地配置。

2. 方案总览：Caddy + Backrest 同栈部署

官方示例的思路很清晰：通过 docker-compose 把 Backrest 和 Caddy 编排在同一个网络中，Caddy 对外暴露443端口并终结 TLS，Backrest 不对外暴露端口，只接受来自 Caddy 容器内部的转发请求。这样即使后续要给 Caddy 加认证、限流等能力，Backrest 本身也始终处于代理的保护之后。

下面的 docker-compose.yaml 是 Cookbook 中的原始示例，配上了逐项注释：

version: "3.2" services: backrest: image: garethgeorge/backrest container_name: backrest hostname: <YOUR PROXIED FQDN HERE (example: backrest.example.com)> volumes: - ./backrest/data:/data - ./backrest/config:/config - ./backrest/cache:/cache - /MY-BACKUP-DATA:/userdata # 把你需要备份的目录挂载进容器文件系统 - /MY-REPOS:/repos # (可选) 把 restic 仓库挂载到容器文件系统中 environment: - BACKREST_DATA=/data # backrest 数据目录：restic 二进制和数据库存放在这里 - BACKREST_CONFIG=/config/config.json # backrest 配置文件路径 - XDG_CACHE_HOME=/cache # restic 缓存目录，能显著提升备份性能 restart: unless-stopped depends_on: - caddy caddy: image: caddy container_name: caddy ports: - "443:443" - "443:443/udp" volumes: - ./caddy/Caddyfile:/etc/caddy/Caddyfile restart: unless-stopped

几个关键点值得展开说明：

• hostname要与反代域名一致：示例用<YOUR PROXIED FQDN HERE>占位，实际部署时填写你要暴露的域名（如backrest.example.com），这会让容器内生成的自签名证书 CN/SAN 与访问域名匹配，避免证书告警。
• BACKREST_DATA/BACKREST_CONFIG/XDG_CACHE_HOME与 Docker 默认值的对应关系：镜像内的入口程序 cmd/docker-entrypoint/main.go 会在这些环境变量为空时自动补默认值——BACKREST_PORT=0.0.0.0:9898、BACKREST_DATA=/data、BACKREST_CONFIG=/config/config.json、XDG_CACHE_HOME=/cache、TMPDIR=/tmp。也就是说，Docker 容器里的 Backrest 默认就监听所有接口的9898端口，供同网络内的 Caddy 转发；你在 compose 里显式声明这些变量，本质上是在覆盖镜像的默认值并让路径与卷挂载点对齐。
• restart: unless-stopped+depends_on: caddy：确保 Caddy 先启动、Backrest 后启动，且任意一方异常退出都会自动拉起，符合长期运行的服务型容器预期。
• 镜像仓库说明：官方 Cookbook 示例使用 Docker Hub 的garethgeorge/backrest；README.md 中的 Docker 示例则使用ghcr.io/garethgeorge/backrest:latest，二者指向同一个项目镜像，另有一个精简版ghcr.io/garethgeorge/backrest:scratch可供选择。

3. Caddyfile：最小可用配置

对应的 Caddyfile 内容如下：

{ https_port 443 } backrest.example.com { tls internal reverse_proxy backrest:9898 }

逐行拆解：

• https_port 443：显式声明 Caddy 的 HTTPS 监听端口为443，与 docker-compose 中"443:443"的端口映射对应。
• backrest.example.com：站点地址（替换成你自己的 FQDN），Caddy 会自动为该域名申请/管理证书。
• tls internal：让 Caddy生成并使用自签名证书，适用于内网、测试或尚未接入公网 CA 的场景。
• reverse_proxy backrest:9898：把该站点的所有请求反向代理到backrest容器（compose 服务名/容器名）的9898端口。

关于这条配置，Cookbook 特别提醒了三件事：

1. reverse_proxy后面的地址必须和 Backrest 容器名一致。backrest:9898是 Docker 网络内的服务发现名称，如果容器名或 compose 服务名变了，这里必须同步修改，否则会 502。
2. 可以配合 acme-dns（caddy-dns）扩展，通过 DNS 方式为端点获取正式证书，适合没有开放 HTTP-01 端口的场景。
3. 可以给站点叠加一个 Caddy 的认证门户（auth portal），支持 Google 等第三方登录，从而为 Backrest 再加一层身份认证。

此外，https_port 443还顺带说明了为什么示例把 Caddy 的端口映射只开了443（含 UDP 用于 HTTP/3）——不建议让 Caddy 以 HTTP 明文方式监听 80 端口，出于安全考虑应保持纯 HTTPS 暴露。

4. 从源码确认：端口与环境变量机制

反向代理配置之所以成立，前提是正确理解 Backrest 的网络绑定模型。结合源码可以确认如下事实链：

• internal/env/environment.go 定义了BACKREST_PORT（EnvVarBindAddress，注释"port to bind to (default 9898)"）、BACKREST_CONFIG、BACKREST_DATA、BACKREST_RESTIC_COMMAND等环境变量；
• 命令行参数--bind-address的优先级高于BACKREST_PORT环境变量，其默认行为是绑定127.0.0.1:9898，文档注释还提示"Use:9898to listen on all interfaces"；
• formatBindAddress会把不带冒号的输入自动补成:端口形式，方便用户直接写端口号；
• 镜像入口 cmd/docker-entrypoint/main.go 在 Docker 环境下把默认值调整为0.0.0.0:9898，这正是 compose 里无需给 Backrest 单独映射ports的原因——它只暴露在 compose 内部网络中，由 Caddy 代劳对外服务。

这套机制说明："Backrest 只监听回环、由反向代理对外暴露"是官方推荐的安全默认形态，反向代理是补全其外部访问能力、TLS 终结与认证能力的标准手段。

5. 进阶注意事项

5.1 多主机/长连接场景下的保活

如果 Backrest 开启了多主机（multihost）同步，且网关对空闲连接有超时策略（例如部分反向代理会激进地切断空闲长连接），可以调低心跳间隔来保活。internal/env/environment.go 中定义了--multihost-heartbeat-interval参数（对应BACKREST_MULTIHOST_HEARTBEAT_INTERVAL环境变量），默认600秒，源码注释明确说明"可以设低一点，以保持与激进超时空闲连接的反向代理之间的连接存活"。这是反向代理场景下非常有价值的调优项，具体机制可进一步参考 docs/src/docs/multihost.md。

5.2 关于 Traefik

Cookbook 开篇同时提到了 Caddy 和 Traefik 两个反向代理，正文以 Caddy 为例给出了完整配置。若你使用 Traefik，思路完全一致：让 Traefik 对外提供 HTTPS，通过服务发现把请求路由到backrest:9898，并让 Backrest 容器保持在内部网络中。具体路由标签语法请以你所用 Traefik 版本的官方文档为准。

5.3 安全性补充

• 反向代理前面的每一层（TLS 终结、认证门户、访问控制）都不能替代 Backrest 自身的登录体系：首次访问 Backrest 时仍会引导创建用户名和密码（见 docs/src/introduction/getting-started.md）。
• 除非确有需要，不要让 Backrest 以0.0.0.0:9898直接暴露到公网；把外部访问收敛到反向代理是更稳妥的做法。
• 生产环境建议用正式的 ACME 证书（公网域名）或妥善管理的内部 CA，而不是长期依赖tls internal的自签名证书。

6. 相关参考

• 本文主出处：Cookbook 反向代理示例 docs/src/cookbooks/reverse-proxy-examples.md
• 环境变量与绑定地址实现：internal/env/environment.go
• Docker 入口默认环境变量：cmd/docker-entrypoint/main.go
• Docker Compose 官方示例与安装说明：README.md
• 多主机同步（涉及心跳与保活）：docs/src/docs/multihost.md
• 入门指引：docs/src/introduction/getting-started.md

• 后端
• 存储
• 运维