novalon-website/docs/CICD_QUICK_START.md

🚀 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: 使用自动化脚本 (推荐)

# 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: 手动配置

# 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中创建仓库

# 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中激活仓库

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

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

# 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

# 在本地项目目录
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. 查看构建状态

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

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

2. 验证部署

Staging环境 (develop分支)

# 检查容器状态
ssh root@139.155.109.62
docker ps | grep novalon-website

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

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

Production环境 (main分支)

# 检查容器状态
ssh root@139.155.109.62
docker ps | grep novalon-website

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

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

3. 验证通知

如果配置了Webhook，您应该会收到通知：

• ✅ 成功通知：绿色，包含构建信息
• ❌ 失败通知：红色，包含错误信息和构建链接

🔄 日常使用流程

开发新功能

# 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环境

紧急修复

# 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
#    - 自动回滚机制保障

🛠️ 故障排查

构建失败

# 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

部署失败

# 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

测试失败

# 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. 加速构建

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

2. 并行执行

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

3. 增量构建

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

🔐 安全最佳实践

1. 密钥管理

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

2. 访问控制

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

3. 安全扫描

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

📞 获取帮助

如有问题，请：

1. 查看 CI/CD配置文档
2. 检查Woodpecker CI日志
3. 联系运维团队: ops@novalon.cn

---

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