# 🚀 CI/CD流水线快速设置指南

## 📋 前置条件

- ✅ Gitea已部署并配置 (https://git.f.novalon.cn)
- ✅ Woodpecker CI已部署并配置 (https://ci.f.novalon.cn)
- ✅ Docker Registry已部署并配置 (https://registry.f.novalon.cn)
- ✅ 服务器已配置SSH免密登录

## 🔧 快速配置步骤

### 步骤1: 配置Woodpecker CI密钥

#### 方式A: 使用自动化脚本 (推荐)

```bash
# 1. 上传脚本到服务器
scp scripts/setup-woodpecker-secrets.sh root@139.155.109.62:/home/novalon/scripts/

# 2. SSH到服务器
ssh root@139.155.109.62

# 3. 运行配置脚本
chmod +x /home/novalon/scripts/setup-woodpecker-secrets.sh
/home/novalon/scripts/setup-woodpecker-secrets.sh
```

#### 方式B: 手动配置

```bash
# 1. SSH到服务器
ssh root@139.155.109.62

# 2. 设置SSH私钥
woodpecker-cli secret add \
  --repository novalon/novalon-website \
  --name ssh_private_key \
  --value @- <<< "$(cat ~/.ssh/id_rsa)"

# 3. 设置Webhook URL (可选)
woodpecker-cli secret add \
  --repository novalon/novalon-website \
  --name webhook_url \
  --value @- <<< "YOUR_WEBHOOK_URL"
```

### 步骤2: 在Gitea中创建仓库

```bash
# 1. 访问 https://git.f.novalon.cn
# 2. 使用管理员账户登录
#    用户名: novalon-admin
#    密码: Novalon@Admin2026
# 3. 创建新仓库: novalon/novalon-website
# 4. 添加远程仓库
git remote add origin https://git.f.novalon.cn/novalon/novalon-website.git
```

### 步骤3: 在Woodpecker CI中激活仓库

```bash
# 1. 访问 https://ci.f.novalon.cn
# 2. 使用Gitea账户登录 (自动SSO)
# 3. 点击"Add Repository"
# 4. 选择 novalon/novalon-website 仓库
# 5. 点击"Activate"
```

### 步骤4: 配置服务器部署目录

```bash
# SSH到服务器
ssh root@139.155.109.62

# 创建部署目录
mkdir -p /home/novalon/docker-app/novalon-website
cd /home/novalon/docker-app/novalon-website

# 创建docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  novalon-website:
    image: registry.f.novalon.cn/novalon-website:latest
    container_name: novalon-website
    restart: always
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=file:/app/data/local.db
    volumes:
      - ./data:/app/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - novalon-network

networks:
  novalon-network:
    external: true
EOF

# 创建数据目录
mkdir -p data
```

### 步骤5: 提交代码并触发CI/CD

```bash
# 在本地项目目录
cd /Users/zhangxiang/Codes/Gitee/home-page/novalon-website

# 添加所有文件
git add .

# 提交代码
git commit -m "feat: 配置全自动CI/CD工作流

- 添加完整的CI/CD流水线配置
- 配置代码质量检查(lint, type-check, security)
- 配置分层测试策略(fast, standard, deep)
- 配置Docker镜像构建和推送
- 配置自动部署到staging和production环境
- 配置健康检查和自动回滚
- 配置成功/失败通知
- 添加健康检查API端点
- 创建CI/CD配置文档"

# 推送到develop分支
git push -u origin develop

# 或者推送到main分支
git push -u origin main
```

## 📊 验证CI/CD流水线

### 1. 查看构建状态

```bash
# 访问Woodpecker CI
https://ci.f.novalon.cn/novalon/website

# 查看构建日志
# 每个步骤都有详细的日志输出
```

### 2. 验证部署

#### Staging环境 (develop分支)
```bash
# 检查容器状态
ssh root@139.155.109.62
docker ps | grep novalon-website

# 查看容器日志
docker logs novalon-website -f

# 健康检查
curl http://localhost:3000/api/health
```

#### Production环境 (main分支)
```bash
# 检查容器状态
ssh root@139.155.109.62
docker ps | grep novalon-website

# 查看容器日志
docker logs novalon-website -f

# 健康检查
curl https://novalon.cn/api/health
```

### 3. 验证通知

如果配置了Webhook，您应该会收到通知：
- ✅ 成功通知：绿色，包含构建信息
- ❌ 失败通知：红色，包含错误信息和构建链接

## 🔄 日常使用流程

### 开发新功能

```bash
# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 开发并提交
git add .
git commit -m "feat: 添加新功能"

# 3. 推送到远程
git push origin feature/new-feature

# 4. 在Gitea创建Pull Request
#    访问: https://git.f.novalon.cn/novalon/novalon-website/pulls

# 5. CI自动运行测试
#    - Lint检查
#    - 类型检查
#    - 单元测试
#    - Smoke测试

# 6. 代码审查通过后合并到develop
#    - 自动触发完整测试
#    - 自动构建Docker镜像
#    - 自动部署到Staging环境

# 7. 测试通过后合并到main
#    - 自动触发完整测试
#    - 自动构建Docker镜像
#    - 自动部署到Production环境
```

### 紧急修复

```bash
# 1. 创建hotfix分支
git checkout -b hotfix/critical-fix main

# 2. 修复并提交
git add .
git commit -m "fix: 修复关键问题"

# 3. 推送并创建PR
git push origin hotfix/critical-fix

# 4. 快速审查并合并到main
#    - 自动部署到Production
#    - 自动回滚机制保障
```

## 🛠️ 故障排查

### 构建失败

```bash
# 1. 查看Woodpecker CI日志
https://ci.f.novalon.cn/novalon/novalon-website

# 2. 常见原因
#    - 依赖安装失败
#    - TypeScript类型错误
#    - 测试失败
#    - Docker构建失败

# 3. 本地重现
npm ci
npm run lint
npm run type-check
npm run test:coverage:check
npm run build
```

### 部署失败

```bash
# 1. SSH到服务器
ssh root@139.155.109.62

# 2. 检查容器状态
docker ps -a | grep novalon-website

# 3. 查看容器日志
docker logs novalon-website

# 4. 检查健康状态
curl http://localhost:3000/api/health

# 5. 手动回滚
docker images | grep novalon-website
docker tag novalon-website:backup-<commit-sha> novalon-website:latest
cd /home/novalon/docker-app/novalon-website
docker-compose up -d --no-deps novalon-website
```

### 测试失败

```bash
# 1. 本地运行测试
npm run test:smoke          # Smoke测试
npm run test:tier:standard  # 标准测试
npm run test:tier:deep      # 深度测试

# 2. 查看测试报告
npm run test:allure:open

# 3. 调试特定测试
npx playwright test --debug
```

## 📈 性能优化建议

### 1. 加速构建

```yaml
# 在.woodpecker.yml中添加缓存
cache:
  - name: npm-cache
    paths:
      - node_modules
      - e2e/node_modules
```

### 2. 并行执行

```yaml
# Woodpecker CI自动并行执行独立步骤
# 无需额外配置
```

### 3. 增量构建

```yaml
# 利用Docker层缓存
# 在Dockerfile中优化层顺序
```

## 🔐 安全最佳实践

### 1. 密钥管理

- ✅ 所有密钥存储在Woodpecker CI中
- ✅ 不在代码中硬编码
- ✅ 定期轮换密钥

### 2. 访问控制

- ✅ main分支受保护
- ✅ PR需要代码审查
- ✅ 部署需要审批

### 3. 安全扫描

- ✅ npm audit自动扫描
- ✅ 定期更新依赖
- ✅ 修复高危漏洞

## 📞 获取帮助

如有问题，请：
1. 查看 [CI/CD配置文档](./CICD_GUIDE.md)
2. 检查Woodpecker CI日志
3. 联系运维团队: ops@novalon.cn

---

**最后更新**: 2026-03-27
**版本**: 1.0.0