张翔
a003f1192e
- 字体加载优化: 添加 font-display: block 策略，创建 useFontLoading hook - 色彩对比度: 调整 text-muted 和 text-tertiary 颜色值确保 WCAG AA 合规 - 滚动进度条: 新增 ScrollProgress 组件，支持 reduced motion - 表单自动保存: 新增 useFormAutosave hook，防止用户数据丢失 - 返回顶部按钮: 新增 BackToTop 组件，提升长页面导航体验 - 图片懒加载: 优化 OptimizedImage 组件，添加 blur placeholder 和加载动画 所有新组件均包含完整测试，1450+ 测试通过
358 lines
7.1 KiB
Markdown
358 lines
7.1 KiB
Markdown
# 🚀 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
|