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