photography/docs/deployment/CLAUDE.md

Deployment Module - CLAUDE.md

此文件为 Claude Code 在部署模块中工作时提供指导。

模块说明

这是摄影作品集项目的部署配置模块，包含 Web 服务器配置、权限脚本和部署文档。

部署架构

当前部署方案

• 前端: 静态文件部署到 /home/gitea/www/photography/
• Web 服务器: Caddy (自动 HTTPS + Let's Encrypt)
• 域名: https://photography.iriver.top
• CI/CD: Gitea Actions 自动部署

文件说明

配置文件

• Caddyfile - Caddy Web 服务器配置文件
• fix-caddy-permissions.sh - Caddy 权限修复脚本

文档

• caddy-setup.md - Caddy 服务器配置和部署指南
• README.md - 部署文档概览

部署流程

自动部署（推荐）

# 1. 推送代码触发 CI/CD
git push origin main

# CI/CD 会自动执行：
# - 安装依赖 (bun install)
# - 类型检查 (bun run type-check)  
# - 代码检查 (bun run lint)
# - 构建项目 (bun run build)
# - 部署到服务器 (rsync 到 ~/www/photography/)

手动部署

# 1. 构建前端项目
cd frontend && make build

# 2. 上传静态文件
rsync -avz frontend/out/ user@server:~/www/photography/

# 3. 设置权限
ssh user@server 'chmod -R 755 ~/www/photography'

Caddy 配置

主要功能

• 自动 HTTPS: Let's Encrypt 证书自动获取和续期
• 静态文件服务: 直接提供 HTML/CSS/JS/图片
• Gzip 压缩: 减少传输大小
• 缓存控制: 静态资源长期缓存，HTML 短期缓存
• 安全头: XSS 保护、防点击劫持等
• 错误处理: 404 重定向到 404.html

配置特点

# 域名
photography.iriver.top

# 根目录  
root * /home/gitea/www/photography

# 安全和性能优化
encode gzip
header Cache-Control "public, max-age=31536000" @static
header X-Frame-Options "SAMEORIGIN"

服务器配置

初次配置（仅需一次）

# 1. 上传 Caddy 配置
scp docs/deployment/Caddyfile user@server:/etc/caddy/Caddyfile

# 2. 修复权限问题
scp docs/deployment/fix-caddy-permissions.sh user@server:~/
ssh user@server './fix-caddy-permissions.sh'

# 3. 重新加载 Caddy
ssh user@server 'sudo systemctl reload caddy'

# 4. 验证状态
ssh user@server 'sudo systemctl status caddy'

权限修复脚本功能

fix-caddy-permissions.sh 脚本会：

• 设置 /home/gitea 目录权限为 755
• 设置 /home/gitea/www 权限为 755
• 设置 /home/gitea/www/photography 权限为 755
• 确保 caddy 用户可以访问所有必要文件

故障排除

常见问题

1. Permission denied 错误

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

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

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

2. 404 Not Found 错误

# 检查文件是否存在
ls -la /home/gitea/www/photography/index.html

# 检查 Caddy 配置
sudo caddy validate --config /etc/caddy/Caddyfile

3. SSL 证书问题

# 检查域名 DNS 记录
dig photography.iriver.top

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

日志查看

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

# Caddy 访问日志
sudo tail -f /var/log/caddy/photography.log

安全配置

SSL/TLS

• 自动获取 Let's Encrypt 证书
• 强制 HTTPS 重定向
• HSTS 头启用（max-age=31536000）

安全头

• X-Frame-Options: SAMEORIGIN - 防止点击劫持
• X-Content-Type-Options: nosniff - 防止 MIME 嗅探
• X-XSS-Protection: 1; mode=block - XSS 保护

访问控制

• 静态文件直接服务，无需特殊权限
• 目录浏览禁用
• 隐藏服务器版本信息

性能优化

缓存策略

# 静态资源（1年缓存）
*.css, *.js, *.png, *.jpg, *.woff2
Cache-Control: public, max-age=31536000, immutable

# HTML 文件（1小时缓存）  
*.html
Cache-Control: public, max-age=3600

压缩

• Gzip 压缩所有文本文件
• 自动内容编码协商

日志轮转

• 日志文件大小：10MB 轮转
• 保留文件数：5个
• JSON 格式便于分析

监控

健康检查

# 检查服务状态
sudo systemctl status caddy

# 检查端口监听
sudo netstat -tulpn | grep :443

# 测试 HTTPS 连接
curl -I https://photography.iriver.top

性能监控

• 访问日志分析
• 响应时间监控
• 错误率统计

备份策略

配置备份

• Caddyfile 版本控制（Git）
• 自动配置备份到 S3/对象存储

数据备份

• 静态文件通过 CI/CD 自动同步
• 日志文件定期归档

扩展计划

支持的部署平台

• ✅ Caddy + Static Files (当前)
• 📋 Vercel (计划)
• 📋 Netlify (计划)
• 📋 Docker (计划)
• 📋 Kubernetes (长期计划)

功能扩展

• CDN 集成
• 多区域部署
• 蓝绿部署
• 自动回滚机制