4.8 KiB
4.8 KiB
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 集成
- 多区域部署
- 蓝绿部署
- 自动回滚机制