Files

Deploy Frontend / deploy (push) Successful in 2m38s

Details

## 📁 模块化重构

### 新增模块 CLAUDE.md
- `frontend/CLAUDE.md` - 前端开发指导 (Next.js, React, TypeScript)
- `docs/deployment/CLAUDE.md` - 部署配置指导 (Caddy, 服务器配置)
- `.gitea/workflows/CLAUDE.md` - CI/CD 流程指导 (Gitea Actions)

### 根目录 CLAUDE.md 优化
- 重构为项目概览和模块导航
- 提供模块选择指导
- 减少单个文件的上下文长度

### 自动化机制
- 创建 `scripts/update-claude-docs.sh` 自动更新脚本
- 集成到 pre-commit hooks 中
- 文件变更时自动更新对应模块的 CLAUDE.md

## 🎯 优化效果

### 上下文优化
- 每个模块独立的 CLAUDE.md 文件
- 大幅减少单次处理的上下文长度
- 提高 Claude 处理效率和准确性

### 开发体验
- 根据工作内容选择对应模块
- 模块化的文档更聚焦和专业
- 自动维护文档时间戳

### 项目结构
```
photography/
├── CLAUDE.md                    # 项目概览和模块导航
├── frontend/CLAUDE.md          # 前端开发指导
├── docs/deployment/CLAUDE.md   # 部署配置指导
├── .gitea/workflows/CLAUDE.md  # CI/CD 流程指导
└── scripts/update-claude-docs.sh # 自动更新脚本
```

现在 Claude 工作时只需关注单个模块的文档，大幅提升处理效率！

2025-07-09 10:54:08 +08:00

5.3 KiB

Raw Permalink Blame History

CI/CD Module - CLAUDE.md

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

模块说明

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

工作流程

主要流程文件

deploy-frontend.yml - 前端项目自动部署工作流

触发条件

on:
  push:
    branches: [ main ]
    paths: [ 'frontend/**' ]
  pull_request:
    branches: [ main ]  
    paths: [ 'frontend/**' ]

部署流程

自动化步骤

代码检出 - actions/checkout@v4
环境设置 - 配置 Bun 运行环境
依赖安装 - bun install
类型检查 - bun run type-check
代码检查 - bun run lint
项目构建 - bun run build
服务器部署 - rsync 同步到服务器
权限设置 - 确保文件权限正确

详细执行流程

# 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 连接配置

使用密码认证连接到阿里云服务器：

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')

质量检查

代码质量门禁

# TypeScript 类型检查
bun run type-check

# ESLint 代码检查  
bun run lint

# 构建验证
bun run build

检查失败处理

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

部署策略

部署方式

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

安全措施

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

监控和通知

部署状态

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

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

部署信息

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

故障排除

常见部署错误

1. SSH 连接失败

# 检查网络连接
ping ${{ secrets.ALIYUN_IP }}

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

2. 权限错误

# 检查目标目录权限
ssh gitea@server "ls -la ~/www/"

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

3. 构建失败

# 本地测试构建
cd frontend
bun install
bun run build

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

4. rsync 同步失败

# 测试 rsync 连接
rsync --dry-run -avz frontend/out/ gitea@server:~/www/photography/

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

调试技巧

# 查看工作流日志
- 在 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 本地验证
自动化测试覆盖 (计划)

5.3 KiB Raw Permalink Blame History Unescape Escape