logo
darc.pro/CaddyHelper
Public
0
0
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
main
CaddyHelper/README_CN.md
DarcJC
feat: Add systemd service management for CaddyHelper with installation, uninstallation, and testing scripts
987eb08c

CaddyHelper

一个用于安全编辑和管理 Caddy Caddyfile 配置的强大 CLI 工具。

功能特性

✅ DNS Challenge 配置 - 支持 AliDNS 和 Cloudflare DNS Challenge 用于 ACME 证书申请
✅ HTTPS 站点配置 - 在自定义端口上配置 HTTPS 站点
✅ 静态站点 - 配置静态文件服务，包含路径验证和权限检查
✅ 反向代理 - 支持多个上游和负载均衡（round_robin, least_conn, ip_hash）
✅ 守护进程管理 - 通过 start/stop 命令管理 Caddy 进程
✅ Layer4 协议转发 - 支持 TCP/UDP 流量转发（基于 Caddy L4 模块）
✅ 自动验证 - 每次修改后自动验证 Caddyfile 正确性

安装

从源码构建

# 克隆仓库
git clone https://github.com/yourusername/CaddyHelper.git
cd CaddyHelper

# 构建发布版本
cargo build --release

# 二进制文件位于 target/release/CaddyHelper

Windows

构建后的可执行文件: target\release\CaddyHelper.exe

Linux

构建后的可执行文件: target/release/CaddyHelper

快速开始

1. 配置 DNS Challenge

AliDNS (阿里云 DNS)

# 为特定域名配置 (site-specific)
CaddyHelper dns alidns \
  --domain example.com \
  --access-key-id your_access_key \
  --access-key-secret your_secret

# 全局配置
CaddyHelper dns alidns \
  --domain example.com \
  --access-key-id your_access_key \
  --access-key-secret your_secret \
  --global

# 使用环境变量
export ALIYUN_ACCESS_KEY_ID=your_access_key
export ALIYUN_ACCESS_KEY_SECRET=your_secret
CaddyHelper dns alidns --domain example.com

Cloudflare

# 为特定域名配置
CaddyHelper dns cloudflare \
  --domain example.com \
  --api-token your_cf_token

# 全局配置
CaddyHelper dns cloudflare \
  --domain example.com \
  --api-token your_cf_token \
  --global

# 使用环境变量
export CF_API_TOKEN=your_token
CaddyHelper dns cloudflare --domain example.com

2. 配置 HTTPS 站点

静态站点

# 在默认 443 端口
CaddyHelper site static \
  --domain blog.example.com \
  --root /var/www/html

# 在自定义端口
CaddyHelper site static \
  --domain blog.example.com \
  --port 8443 \
  --root /var/www/html

反向代理

# 单个上游
CaddyHelper site proxy \
  --domain api.example.com \
  --upstream 127.0.0.1:8080

# 多个上游，使用 round_robin (默认)
CaddyHelper site proxy \
  --domain api.example.com \
  --upstream 192.168.1.10:8080 \
  --upstream 192.168.1.11:8080 \
  --upstream 192.168.1.12:8080

# 使用 least_conn 负载均衡
CaddyHelper site proxy \
  --domain api.example.com \
  --upstream 192.168.1.10:8080 \
  --upstream 192.168.1.11:8080 \
  --lb-policy least_conn

# 使用 ip_hash 负载均衡
CaddyHelper site proxy \
  --domain api.example.com \
  --upstream 192.168.1.10:8080 \
  --upstream 192.168.1.11:8080 \
  --lb-policy ip_hash

# 自定义端口
CaddyHelper site proxy \
  --domain api.example.com \
  --port 8443 \
  --upstream 127.0.0.1:8080

3. 配置 Layer4 协议转发

TCP 转发

# 单个上游
CaddyHelper layer4 tcp \
  --listen 0.0.0.0:3306 \
  --upstream 192.168.1.100:3306

# 多个上游（自动负载均衡）
CaddyHelper layer4 tcp \
  --listen 0.0.0.0:3306 \
  --upstream 192.168.1.100:3306 \
  --upstream 192.168.1.101:3306

UDP 转发

# DNS 转发示例
CaddyHelper layer4 udp \
  --listen 0.0.0.0:53 \
  --upstream 8.8.8.8:53 \
  --upstream 8.8.4.4:53

4. 守护进程管理

# 启动 Caddy 守护进程
CaddyHelper start

# 使用自定义配置文件
CaddyHelper start --config /path/to/Caddyfile

# 指定 Caddy 可执行文件路径
CaddyHelper start --caddy-path /usr/local/bin/caddy

# 停止 Caddy 守护进程
CaddyHelper stop

5. 验证配置

# 验证 Caddyfile
CaddyHelper validate

# 验证自定义配置文件
CaddyHelper validate --config /path/to/Caddyfile

# 使用特定 Caddy 可执行文件验证
CaddyHelper validate --config Caddyfile --caddy-path ./caddy

工作原理

配置管理

CaddyHelper 维护两个文件:

  1. caddyhelper.json - 内部配置文件，存储所有配置的结构化数据
  2. Caddyfile - 由 CaddyHelper 生成的 Caddy 配置文件

每次运行命令后:

  1. 配置被添加到 caddyhelper.json
  2. 根据配置生成新的 Caddyfile
  3. 使用 caddy validate 自动验证生成的配置
  4. 如果验证失败，更改会被回滚

守护进程管理

Windows

  • PID 文件位置: %APPDATA%\CaddyHelper\caddyhelper.pid
  • 进程管理: 使用 Windows Task Manager API

Linux/Unix

  • PID 文件位置: /run/caddy/CaddyHelper/caddyhelper.pid
  • 进程管理: 使用标准的 UNIX 信号 (SIGTERM)

守护进程互斥检查确保同一时间只有一个 Caddy 实例运行。

生成的 Caddyfile 示例

完整示例

{
    # Global DNS configuration
    acme_dns alidns {
        access_key_id {env.ALIYUN_ACCESS_KEY_ID}
        access_key_secret {env.ALIYUN_ACCESS_KEY_SECRET}
    }

    layer4 {
        0.0.0.0:3306 {
            route {
                proxy 192.168.1.100:3306 192.168.1.101:3306
            }
        }
    }
}

example.com {
    root * /var/www/html
    file_server
}

api.example.com {
    reverse_proxy {
        lb_policy least_conn
        to 192.168.1.10:8080
        to 192.168.1.11:8080
        to 192.168.1.12:8080
    }
}

secure.example.com:8443 {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    reverse_proxy 127.0.0.1:8080
}

高级用法

环境变量

CaddyHelper 支持通过环境变量传递敏感信息:

# AliDNS
export ALIYUN_ACCESS_KEY_ID=your_key
export ALIYUN_ACCESS_KEY_SECRET=your_secret

# Cloudflare
export CF_API_TOKEN=your_token

# 然后直接使用命令，无需传递凭证
CaddyHelper dns alidns --domain example.com
CaddyHelper dns cloudflare --domain example.com

Caddy 可执行文件检测

CaddyHelper 会自动在以下位置搜索 Caddy 可执行文件:

Windows:

  • caddy.exe
  • caddy_windows_amd64_custom.exe
  • .\bin\caddy_windows_amd64_custom.exe
  • C:\Program Files\Caddy\caddy.exe

Linux:

  • caddy
  • ./caddy
  • ./bin/caddy_linux_amd64_custom
  • /usr/local/bin/caddy
  • /usr/bin/caddy

你也可以通过 --caddy-path 参数手动指定路径。

日志

使用 RUST_LOG 环境变量控制日志级别:

# 调试模式
RUST_LOG=debug CaddyHelper site static --domain example.com --root /var/www

# 仅显示信息
RUST_LOG=info CaddyHelper start

# 详细日志
RUST_LOG=trace CaddyHelper validate

systemd 服务管理 (Linux)

CaddyHelper 提供完整的 systemd 服务配置，适用于生产环境。

快速安装

# 1. 进入 systemd 目录
cd systemd

# 2. 运行自动安装脚本
sudo bash install.sh /path/to/caddy

# 3. 服务会自动启动并设置开机自启

手动安装

# 1. 创建用户和目录
sudo groupadd --system caddy
sudo useradd --system --gid caddy --home-dir /var/lib/caddy caddy
sudo mkdir -p /etc/caddy /var/lib/caddy /var/log/caddy

# 2. 安装 Caddy 二进制
sudo cp caddy /usr/local/bin/
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy

# 3. 复制配置和服务文件
sudo cp Caddyfile /etc/caddy/
sudo cp systemd/caddy-secure.service /etc/systemd/system/caddy.service

# 4. 启动服务
sudo systemctl daemon-reload
sudo systemctl enable caddy
sudo systemctl start caddy

服务管理命令

# 启动服务
sudo systemctl start caddy

# 停止服务
sudo systemctl stop caddy

# 重启服务
sudo systemctl restart caddy

# 平滑重载配置（零停机）
sudo systemctl reload caddy

# 查看状态
sudo systemctl status caddy

# 查看日志
sudo journalctl -u caddy -f

# 开机自启
sudo systemctl enable caddy

配置更新工作流

# 1. 使用 CaddyHelper 修改配置
CaddyHelper site proxy --domain api.example.com --upstream 127.0.0.1:8080

# 2. 验证配置
CaddyHelper validate

# 3. 复制到系统目录
sudo cp Caddyfile /etc/caddy/Caddyfile

# 4. 平滑重载（无需停机）
sudo systemctl reload caddy

开发 vs 生产环境

特性CaddyHelper (start/stop)systemd
适用场景开发、测试生产环境
进程管理手动自动守护
开机自启✗✓
日志管理文件journald
自动重启✗✓
权限隔离当前用户专用用户

建议：

  • 开发环境使用 CaddyHelper start/stop，快速迭代
  • 生产环境使用 systemd，稳定可靠

详细文档请参阅 systemd/README.md

故障排除

验证失败

如果 Caddyfile 验证失败:

  1. 检查生成的 Caddyfile 内容
  2. 确保所有路径存在且有正确的权限
  3. 验证上游地址格式正确 (IP:PORT 或 DOMAIN:PORT)
  4. 手动运行 caddy validate --config Caddyfile 查看详细错误

守护进程问题

如果无法启动或停止守护进程:

Windows:

# 检查 PID 文件
cat $env:APPDATA\CaddyHelper\caddyhelper.pid

# 手动清理
del $env:APPDATA\CaddyHelper\caddyhelper.pid

Linux:

# 检查 PID 文件
cat /run/caddy/CaddyHelper/caddyhelper.pid

# 手动清理
sudo rm /run/caddy/CaddyHelper/caddyhelper.pid

权限问题

Linux:

  • 确保对静态文件目录有读权限
  • Layer4 端口 < 1024 需要 root 权限或 capabilities: 
    sudo setcap CAP_NET_BIND_SERVICE=+eip /path/to/caddy

Windows:

  • 某些端口可能需要管理员权限
  • 以管理员身份运行 PowerShell/CMD

依赖要求

  • Rust 1.70+ (仅构建时)
  • Caddy 2.x 与以下模块:
    • dns.providers.alidns (用于 AliDNS)
    • dns.providers.cloudflare (用于 Cloudflare)
    • layer4 (用于 Layer4 转发)

构建 Caddy 与所需模块

xcaddy build \
  --with github.com/caddy-dns/alidns \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/mholt/caddy-l4

项目结构

CaddyHelper/
├── src/
│   ├── main.rs         # 入口点和命令处理
│   ├── cli.rs          # CLI 参数定义
│   ├── config.rs       # 配置结构和 Caddyfile 生成
│   ├── daemon.rs       # 守护进程管理
│   ├── error.rs        # 错误类型定义
│   ├── layer4.rs       # Layer4 配置
│   ├── site.rs         # 站点配置和验证
│   └── validator.rs    # Caddyfile 验证
├── Cargo.toml
└── README.md

贡献

欢迎贡献! 请随时提交 Pull Request。

许可证

本项目基于 MIT 许可证开源。

致谢

© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号