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

# CI/CD 测试指南

## 📝 测试前准备

### 1. 确认 Gitea 配置

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

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

### 2. 确认服务器环境

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

```bash
ssh atai@172.16.74.149

# 检查 Docker
docker --version

# 检查 Docker Compose
docker-compose --version

# 检查 Git
git --version

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

## 🧪 测试步骤

### 测试 1: 本地构建测试

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

```bash
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 构建测试

```bash
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 推送触发自动部署

```bash
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: 服务器验证

```bash
# 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: 功能测试

```bash
# 测试前端访问
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: 构建失败

**可能原因**：
- 依赖安装失败
- 构建脚本错误
- 内存不足

**解决**：
```bash
# 检查 Actions 日志
# 根据错误信息调整构建配置

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

### 问题 3: SSH 连接失败

**可能原因**：
- 服务器 IP 地址错误
- SSH 端口不对
- 认证信息错误

**解决**：
```bash
# 手动测试 SSH 连接
ssh atai@172.16.74.149

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

### 问题 4: Docker 构建失败

**可能原因**：
- 依赖下载失败
- 构建超时
- 磁盘空间不足

**解决**：
```bash
# 登录服务器
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: 健康检查失败

**可能原因**：
- 服务启动慢
- 端口未开放
- 容器未正常运行

**解决**：
```bash
# 检查容器状态
sudo docker-compose ps

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

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

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

## 📊 性能测试

### 测试构建时间

```bash
time pnpm build
```

**预期**：
- 首次构建：5-10 分钟
- 缓存构建：2-5 分钟

### 测试部署时间

观察 Actions 执行时间：
- Build and Test: 3-8 分钟
- Deploy: 2-5 分钟
- Health Check: 30 秒

**总计**：约 5-15 分钟

## ✅ 测试清单

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

## 📝 测试报告模板

```markdown
## 测试报告

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

**测试人员**：XXX

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

### 测试详情

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

### 问题记录

1. 无

### 改进建议

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

## 🎯 下一步

测试通过后，可以考虑：

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