photography/docs/operations/deployment/caddy-setup.md

Caddy 配置指南

配置文件位置

将 Caddyfile 复制到服务器的 Caddy 配置目录：

常见位置：

• Ubuntu/Debian: /etc/caddy/Caddyfile
• CentOS/RHEL: /etc/caddy/Caddyfile
• 用户目录: ~/Caddyfile

部署步骤

1. 上传配置文件

# 将 Caddyfile 上传到服务器
scp docs/deployment/Caddyfile user@server:/etc/caddy/Caddyfile

2. 修复权限问题

# 上传权限修复脚本
scp docs/deployment/fix-caddy-permissions.sh user@server:~/
ssh user@server 'chmod +x fix-caddy-permissions.sh && ./fix-caddy-permissions.sh'

3. 创建日志目录

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

4. 验证配置

sudo caddy validate --config /etc/caddy/Caddyfile

5. 重新加载配置

sudo systemctl reload caddy

6. 检查状态

sudo systemctl status caddy

配置说明

基本功能

• 域名: photography.iriver.top
• 根目录: ~/www/photography
• 自动 HTTPS: Caddy 自动获取和续期 SSL 证书
• 文件服务: 直接提供静态文件服务

优化功能

• Gzip 压缩: 减少传输大小
• 缓存控制: 静态资源长期缓存，HTML 短期缓存
• 安全头: 防止常见安全问题
• 错误处理: 404 错误重定向到 404.html

日志功能

• 位置: /var/log/caddy/photography.log
• 格式: JSON 格式便于分析
• 轮转: 10MB 轮转，保留 5 个文件

故障排除

权限问题

如果遇到 permission denied 错误：

# 检查目录权限
ls -la /home/gitea/www/photography

# 运行权限修复脚本
./fix-caddy-permissions.sh

# 验证 caddy 用户可以访问
sudo -u caddy ls -la /home/gitea/www/photography

检查配置语法

caddy validate --config /path/to/Caddyfile

查看日志

# 系统日志
sudo journalctl -u caddy -f

# 应用日志
sudo tail -f /var/log/caddy/photography.log

测试配置

# 测试模式启动
sudo caddy run --config /etc/caddy/Caddyfile

常见错误解决

1. Permission denied 错误

• 原因: Caddy 进程无法访问用户目录
• 解决: 运行 fix-caddy-permissions.sh 脚本

2. 404 Not Found 错误

• 原因: 文件路径不正确或文件不存在
• 解决: 检查 /home/gitea/www/photography 目录是否有文件

3. 证书获取失败

• 原因: 域名 DNS 未正确指向服务器
• 解决: 确认 DNS A 记录指向正确 IP

域名解析

确保域名 photography.iriver.top 的 DNS 记录指向服务器 IP：

A    photography.iriver.top    YOUR_SERVER_IP

SSL 证书

Caddy 会自动：

• 获取 Let's Encrypt SSL 证书
• 自动续期证书
• 强制 HTTPS 重定向

性能优化

配置包含以下优化：

• Gzip 压缩减少带宽
• 静态资源缓存提高加载速度
• 安全头提高安全性
• 错误页面友好处理