photography/.gitea/workflows/CLAUDE.md

# CI/CD Module - CLAUDE.md

此文件为 Claude Code 在 CI/CD 模块中工作时提供指导。

## 模块说明
这是摄影作品集项目的 CI/CD 配置模块，使用 Gitea Actions 实现自动化部署。

## 工作流程

### 主要流程文件
- **`deploy-frontend.yml`** - 前端项目自动部署工作流

### 触发条件
```yaml
on:
  push:
    branches: [ main ]
    paths: [ 'frontend/**' ]
  pull_request:
    branches: [ main ]  
    paths: [ 'frontend/**' ]
```

## 部署流程

### 自动化步骤
1. **代码检出** - `actions/checkout@v4`
2. **环境设置** - 配置 Bun 运行环境
3. **依赖安装** - `bun install`
4. **类型检查** - `bun run type-check`
5. **代码检查** - `bun run lint`
6. **项目构建** - `bun run build`
7. **服务器部署** - rsync 同步到服务器
8. **权限设置** - 确保文件权限正确

### 详细执行流程
```bash
# 1. 环境准备
- Checkout code (actions/checkout@v4)
- Setup Bun (oven-sh/setup-bun@v1)

# 2. 依赖和检查
cd frontend
bun install
bun run type-check
bun run lint

# 3. 构建
bun run build  # 生成 frontend/out/ 目录

# 4. 部署
# 创建服务器目录
ssh gitea@server "mkdir -p ~/www/photography"

# 上传文件  
rsync -avz frontend/out/ gitea@server:~/www/photography/

# 设置权限
ssh gitea@server "chmod -R 755 ~/www/photography"
```

## 服务器配置

### SSH 连接配置
使用密码认证连接到阿里云服务器：
```bash
export SSHPASS=${{ secrets.ALIYUN_PWD }}
sshpass -e ssh -o StrictHostKeyChecking=no ${{ secrets.ALIYUN_USER_NAME }}@${{ secrets.ALIYUN_IP }}
```

### 必需的 Secrets
在 Gitea 仓库设置中配置：
- **`ALIYUN_IP`** - 服务器 IP 地址
- **`ALIYUN_USER_NAME`** - SSH 用户名 (gitea)
- **`ALIYUN_PWD`** - SSH 密码

### 部署目标
- **服务器路径**: `/home/gitea/www/photography/`
- **Web 服务**: Caddy (通过 photography.iriver.top 访问)
- **文件权限**: 755 (目录和文件)

## 构建配置

### Node.js 环境
- **运行环境**: ubuntu-latest
- **包管理器**: Bun (最新版本)
- **构建工具**: Next.js 15

### 构建产物
- **输出目录**: `frontend/out/`
- **文件类型**: 静态 HTML/CSS/JS/图片
- **构建模式**: 静态导出 (`output: 'export'`)

## 质量检查

### 代码质量门禁
```bash
# TypeScript 类型检查
bun run type-check

# ESLint 代码检查  
bun run lint

# 构建验证
bun run build
```

### 检查失败处理
- 任何步骤失败都会终止部署
- 失败时发送通知消息
- 日志详细记录错误信息

## 部署策略

### 部署方式
- **增量部署**: rsync --delete 确保目标目录与源目录同步
- **原子性**: 先构建成功再部署，避免部分文件更新
- **回滚**: Git 版本控制，可快速回滚到之前版本

### 安全措施
- 使用 SSH 密钥或密码认证
- 禁用主机密钥检查（CI/CD 环境）
- 限制部署用户权限

## 监控和通知

### 部署状态
```yaml
- name: Notify success
  if: success()
  run: echo "✅ 前端项目部署成功！"

- name: Notify failure  
  if: failure()
  run: echo "❌ 前端项目部署失败！"
```

### 部署信息
- **部署路径**: `~/www/photography/`
- **访问地址**: `https://photography.iriver.top`
- **部署时间**: 自动记录
- **构建日志**: 完整保留

## 故障排除

### 常见部署错误

#### 1. SSH 连接失败
```bash
# 检查网络连接
ping ${{ secrets.ALIYUN_IP }}

# 验证 SSH 凭据
ssh gitea@${{ secrets.ALIYUN_IP }} "echo 'SSH 连接测试'"
```

#### 2. 权限错误
```bash
# 检查目标目录权限
ssh gitea@server "ls -la ~/www/"

# 修复权限问题  
ssh gitea@server "chmod -R 755 ~/www/photography"
```

#### 3. 构建失败
```bash
# 本地测试构建
cd frontend
bun install
bun run build

# 检查构建输出
ls -la frontend/out/
```

#### 4. rsync 同步失败
```bash
# 测试 rsync 连接
rsync --dry-run -avz frontend/out/ gitea@server:~/www/photography/

# 检查磁盘空间
ssh gitea@server "df -h"
```

### 调试技巧
```bash
# 查看工作流日志
- 在 Gitea Actions 页面查看详细日志
- 每个步骤都有独立的日志输出
- 失败时会高亮错误信息

# 本地复现问题
- 使用相同的命令在本地测试
- 检查环境变量和依赖版本
- 验证构建产物正确性
```

## 性能优化

### 构建优化
- 使用 Bun 替代 npm (更快的包管理)
- 并行执行类型检查和代码检查
- 缓存 node_modules (计划中)

### 部署优化
- rsync 增量同步，只传输变更文件
- gzip 压缩传输内容
- 并行上传多个文件 (计划中)

## 扩展计划

### 多环境部署
- **开发环境**: dev.photography.iriver.top
- **预发布环境**: staging.photography.iriver.top  
- **生产环境**: photography.iriver.top

### 高级功能
- **蓝绿部署**: 零停机时间部署
- **自动回滚**: 部署失败时自动回滚
- **性能测试**: 自动化性能基准测试
- **安全扫描**: 静态代码安全分析

### 通知集成
- 钉钉/企微通知
- 邮件通知
- Slack 集成

## 最佳实践

### 提交规范
- 遵循 Conventional Commits 规范
- 包含清晰的提交信息
- 关联 Issue 和 PR

### 分支策略
- **main**: 生产环境分支
- **develop**: 开发环境分支 (计划)
- **feature/***: 功能分支

### 代码质量
- 强制通过所有质量检查
- Pre-commit hooks 本地验证
- 自动化测试覆盖 (计划)