init

2026-06-09 23:08:10 +08:00
commit b0907649b1
5 changed files with 247 additions and 0 deletions
@@ -0,0 +1,200 @@
+# Caddy L4 Proxy Server
+
+一个基于 Caddy 2.11.4 和 caddy-l4 模块的容器化反向代理服务器，支持 HTTP/HTTPS 应用层反代和 TCP/UDP 四层转发。
+
+## 特性
+
+- **Layer 4 代理**：通过 `caddy-l4` 模块支持 TCP/UDP 四层转发，适合 SSH、MySQL、Redis 等非 HTTP 服务
+- **自动 HTTPS**：Caddy 自动申请和续期 Let's Encrypt 证书，无需手动配置
+- **国内优化**：构建阶段配置了国内 Go 代理源 (`goproxy.cn`)，加速镜像构建
+- **容器化部署**：使用 Docker 和 Docker Compose 快速部署，支持数据和配置持久化
+- **管理 API**：Caddy 管理 API 监听在 2019 端口
+
+## 系统要求
+
+- Docker 20.10+ 或 Docker Desktop
+- Docker Compose 2.0+（如使用 Compose 启动）
+- Linux 主机（推荐）或 macOS/Windows with Docker Desktop
+
+## 快速开始
+
+### 1. 构建镜像
+
+```bash
+docker build -t caddy-l4:local .
+```
+
+### 2. 使用 Docker Compose 运行
+
+```bash
+docker compose up -d
+```
+
+### 3. 使用 Docker 直接运行
+
+```bash
+docker run -d \
+  -p 80:80 \
+  -p 443:443 \
+  -p 2222:2222 \
+  -v "$PWD/Caddyfile:/etc/caddy/Caddyfile:ro" \
+  -v caddy_data:/data \
+  -v caddy_config:/config \
+  -e ACME_AGREE=true \
+  --restart unless-stopped \
+  --name caddy_l4 \
+  caddy-l4:local
+```
+
+## 配置
+
+### Caddyfile 示例
+
+#### HTTPS 反向代理（应用层）
+
+```caddyfile
+git.example.com {
+  reverse_proxy 10.8.0.15:3000
+}
+```
+
+Caddy 会自动：
+- 申请 Let's Encrypt 证书
+- 监听 443 (HTTPS)
+- 将 HTTP 流量重定向到 HTTPS
+- 反代请求到 10.8.0.15:3000
+
+#### TCP 四层转发（Layer 4）
+
+```caddyfile
+{
+  layer4 {
+    :2222 {
+      route {
+        proxy 127.0.0.1:22
+      }
+    }
+  }
+}
+```
+
+监听 2222 端口，直接转发 TCP 流量到本地 22 端口（SSH）
+
+### 环境变量
+
+- `ACME_AGREE=true`：同意 Let's Encrypt 服务条款，启用自动 HTTPS
+
+### 持久化存储
+
+- `caddy_data:/data`：存储 ACME 证书和其他数据
+- `caddy_config:/config`：存储 Caddy 运行时配置
+
+## 常见命令
+
+### 查看容器日志
+
+```bash
+docker compose logs -f caddy
+```
+
+### 重启服务
+
+```bash
+docker compose restart caddy
+```
+
+### 停止服务
+
+```bash
+docker compose down
+```
+
+### 验证 Caddyfile 语法
+
+```bash
+docker run --rm -v "$PWD/Caddyfile:/etc/caddy/Caddyfile:ro" caddy-l4:local \
+  caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
+```
+
+### 查看 Caddy 版本和模块
+
+```bash
+docker run --rm caddy-l4:local caddy version
+```
+
+## 网络配置
+
+### Docker Compose 中的 host 网络模式
+
+当前 `docker-compose.yml` 使用 `network_mode: host`，这意味着：
+
+- 容器直接使用宿主机网络栈
+- 无需进行 -p 端口映射
+- 容器内 `127.0.0.1` 指向宿主机本地地址
+- 适合需要访问宿主机服务的场景
+
+如果使用桥接网络（默认），需要修改配置：
+
+```yaml
+ports:
+  - "80:80"
+  - "443:443"
+  - "2222:2222"
+  - "2019:2019"
+```
+
+## 云服务器部署
+
+### 镜像推送到 Docker Hub
+
+```bash
+docker build -t yourusername/caddy-l4:latest .
+docker push yourusername/caddy-l4:latest
+```
+
+### 服务器端拉取和运行
+
+```bash
+docker pull yourusername/caddy-l4:latest
+docker compose up -d
+```
+
+### 重要提示
+
+- **防火墙**：云服务器需要开放相应端口（80、443、2222 等）
+- **域名 DNS**：HTTPS 反代的域名需要提前解析到云服务器 IP
+- **证书申请**：首次启动会自动从 Let's Encrypt 申请证书，需要互联网连接和正确的 DNS 解析
+
+## 故障排查
+
+### 证书无法申请
+
+- 检查域名 DNS 是否正确解析到服务器 IP：`ndig yourdomain.com`
+- 检查 80 和 443 端口是否对外开放
+- 查看日志：`docker compose logs caddy`
+
+### 反代无法连接
+
+- 确认目标服务地址是否正确（特别是 host 网络模式下的 localhost 问题）
+- 使用 `docker exec caddy_l4 curl http://target:port` 在容器内测试连通性
+
+### L4 转发无法工作
+
+- 确认 TCP 转发目标服务已启动
+- 测试：`telnet localhost 2222` 或 `ssh user@localhost -p 2222`
+
+## 文件说明
+
+- `Dockerfile`：基于 caddy:2.11.4 镜像，集成 caddy-l4 模块
+- `docker-compose.yml`：一键启动配置
+- `Caddyfile`：Caddy 配置文件（需自行编写或修改）
+- `README.md`：本文件
+
+## 许可
+
+Caddy 采用 Apache 2.0 许可，详见 [Caddy 官方文档](https://caddyserver.com)
+
+## 参考资源
+
+- [Caddy 官方文档](https://caddyserver.com/docs/)
+- [caddy-l4 模块](https://github.com/mholt/caddy-l4)