kt-financial-system/.gitea/TEST_GUIDE.md

CI/CD 测试指南

📝 测试前准备

1. 确认 Gitea 配置

确保 Gitea 已经安装并配置了 Actions：

# 检查 Gitea Actions 是否启用
# 在 Gitea 管理界面检查：Site Administration → Configuration → Actions

2. 确认服务器环境

确保目标服务器已安装必要的软件：

ssh atai@172.16.74.149

# 检查 Docker
docker --version

# 检查 Docker Compose
docker-compose --version

# 检查 Git
git --version

# 检查端口是否可用
sudo netstat -tulpn | grep 8080

🧪 测试步骤

测试 1: 本地构建测试

在推送到 Gitea 之前，先在本地测试构建：

cd /Users/hahaha/projects/kt-financial-system

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 检查构建产物
ls -la apps/web-antd/dist/
ls -la apps/backend/.output/

预期结果：

• ✅ 构建成功，无错误
• ✅ apps/web-antd/dist/ 目录存在
• ✅ apps/backend/.output/ 目录存在

测试 2: 本地 Docker 构建测试

cd /Users/hahaha/projects/kt-financial-system

# 构建 Docker 镜像
docker build -t kt-financial-test .

# 查看镜像大小
docker images | grep kt-financial-test

# 运行容器测试
docker run -d -p 8081:80 --name kt-financial-test kt-financial-test

# 等待启动
sleep 10

# 测试访问
curl -I http://localhost:8081

# 清理测试容器
docker stop kt-financial-test
docker rm kt-financial-test
docker rmi kt-financial-test

预期结果：

• ✅ 镜像构建成功
• ✅ 容器启动成功
• ✅ HTTP 响应 200/301/302

测试 3: Git 推送触发自动部署

cd /Users/hahaha/projects/kt-financial-system

# 添加修改
git add .
git commit -m "test: 测试 CI/CD 自动部署"

# 推送到 main 分支
git push origin main

验证步骤：

1. 查看 Actions 执行情况

   • 打开 Gitea 仓库页面
   • 点击 Actions 标签
   • 查看最新的 workflow run

2. 检查 Build and Test 阶段

   • ✅ Checkout code - 成功
   • ✅ Setup Node.js - 成功
   • ✅ Setup pnpm - 成功
   • ✅ Install dependencies - 成功
   • ✅ Build project - 成功
   • ✅ Run tests - 成功（或跳过）

3. 检查 Deploy 阶段

   • ✅ SSH 连接成功
   • ✅ 代码拉取成功
   • ✅ Docker 镜像构建成功
   • ✅ 容器启动成功

4. 检查 Health Check 阶段

   • ✅ 服务健康检查通过

测试 4: 手动触发部署

1. 打开 Gitea 仓库页面
2. 点击 Actions 标签
3. 点击 Deploy to Production workflow
4. 点击 Run workflow 按钮
5. 选择 main 分支
6. 点击确认

预期结果：

• ✅ Workflow 成功触发
• ✅ 所有阶段都成功完成

测试 5: 服务器验证

# SSH 登录服务器
ssh atai@172.16.74.149

# 切换到部署目录
cd /home/atai/kt-financial-system

# 检查容器状态
sudo docker-compose ps

# 检查容器日志
sudo docker-compose logs --tail=50

# 检查 Nginx 日志
sudo docker exec kt-financial-system tail -f /var/log/nginx/access.log

# 检查后端日志
sudo docker exec kt-financial-system tail -f /var/log/backend/stdout.log

预期结果：

• ✅ 容器状态为 Up
• ✅ 无错误日志
• ✅ Nginx 正常运行
• ✅ 后端正常运行

测试 6: 功能测试

# 测试前端访问
curl -I http://172.16.74.149:8080

# 测试 API 访问
curl http://172.16.74.149:8080/api/ping

预期结果：

• ✅ HTTP 200/301/302
• ✅ 页面正常加载
• ✅ API 正常响应

测试 7: 浏览器访问测试

1. 打开浏览器
2. 访问：http://172.16.74.149:8080
3. 检查页面是否正常显示
4. 测试登录功能
5. 测试主要功能模块

预期结果：

• ✅ 页面加载正常
• ✅ 样式显示正常
• ✅ 功能运行正常
• ✅ 无控制台错误

⚠️ 常见问题

问题 1: Actions 无法触发

原因：

• Gitea Actions 未启用
• Runner 未配置

解决：

1. 检查 Gitea 配置文件 app.ini
2. 确认 Actions 功能已启用
3. 配置并启动 Runner

问题 2: 构建失败

可能原因：

• 依赖安装失败
• 构建脚本错误
• 内存不足

解决：

# 检查 Actions 日志
# 根据错误信息调整构建配置

# 如果是内存问题，可以增加 Node.js 内存限制
NODE_OPTIONS=--max-old-space-size=8192 pnpm build

问题 3: SSH 连接失败

可能原因：

• 服务器 IP 地址错误
• SSH 端口不对
• 认证信息错误

解决：

# 手动测试 SSH 连接
ssh atai@172.16.74.149

# 检查 Secrets 配置
# 确认 SERVER_HOST, SERVER_USER, SERVER_PASSWORD 正确

问题 4: Docker 构建失败

可能原因：

• 依赖下载失败
• 构建超时
• 磁盘空间不足

解决：

# 登录服务器
ssh atai@172.16.74.149

# 检查磁盘空间
df -h

# 清理 Docker 缓存
sudo docker system prune -a

# 手动构建测试
cd /home/atai/kt-financial-system
sudo docker-compose build --no-cache

问题 5: 健康检查失败

可能原因：

• 服务启动慢
• 端口未开放
• 容器未正常运行

解决：

# 检查容器状态
sudo docker-compose ps

# 检查容器日志
sudo docker-compose logs

# 检查端口
sudo netstat -tulpn | grep 8080

# 手动测试访问
curl -I http://localhost:8080

📊 性能测试

测试构建时间

time pnpm build

预期：

• 首次构建：5-10 分钟
• 缓存构建：2-5 分钟

测试部署时间

观察 Actions 执行时间：

• Build and Test: 3-8 分钟
• Deploy: 2-5 分钟
• Health Check: 30 秒

总计：约 5-15 分钟

✅ 测试清单

• 本地构建测试通过
• 本地 Docker 测试通过
• Git 推送触发自动部署成功
• 手动触发部署成功
• 服务器容器正常运行
• 前端页面正常访问
• API 接口正常响应
• 浏览器功能测试通过
• 健康检查通过
• 日志无错误信息

📝 测试报告模板

## 测试报告

**测试日期**：2025-01-XX

**测试人员**：XXX

**测试结果**：✅ 通过 / ❌ 失败

### 测试详情

| 测试项 | 状态 | 备注 |
|--------|------|------|
| 本地构建 | ✅ | 无问题 |
| Docker 构建 | ✅ | 无问题 |
| 自动部署 | ✅ | 无问题 |
| 健康检查 | ✅ | 无问题 |
| 功能测试 | ✅ | 无问题 |

### 问题记录

1. 无

### 改进建议

1. 考虑添加更多测试用例
2. 增加性能监控

🎯 下一步

测试通过后，可以考虑：

1. ✅ 添加更多环境（dev, staging）
2. ✅ 集成通知系统（钉钉、企业微信）
3. ✅ 添加回滚功能
4. ✅ 增加监控告警
5. ✅ 优化构建缓存策略