# 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`** - 部署文档概览

## 部署流程

### 自动部署（推荐）
```bash
# 1. 推送代码触发 CI/CD
git push origin main

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

### 手动部署
```bash
# 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

### 配置特点
```bash
# 域名
photography.iriver.top

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

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

## 服务器配置

### 初次配置（仅需一次）
```bash
# 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 错误
```bash
# 检查权限
ls -la /home/gitea/www/photography

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

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

#### 2. 404 Not Found 错误
```bash
# 检查文件是否存在
ls -la /home/gitea/www/photography/index.html

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

#### 3. SSL 证书问题
```bash
# 检查域名 DNS 记录
dig photography.iriver.top

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

### 日志查看
```bash
# 系统日志
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 保护

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

## 性能优化

### 缓存策略
```bash
# 静态资源（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 格式便于分析

## 监控

### 健康检查
```bash
# 检查服务状态
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 集成
- 多区域部署
- 蓝绿部署
- 自动回滚机制