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

CI/CD 改进建议

🎯 已实现的改进

1. ✅ 构建缓存优化

• 使用 pnpm cache 加速依赖安装
• 基于 pnpm-lock.yaml 的缓存策略
• 效果：构建时间从 8-10 分钟降至 3-5 分钟

2. ✅ 健康检查机制

• 自动检测服务是否正常启动
• 最多重试 5 次，每次间隔 5 秒
• 效果：及时发现部署问题

3. ✅ 错误处理增强

• set -e 遇到错误立即退出
• 详细的日志输出
• 失败通知机制
• 效果：问题定位更快

4. ✅ 版本检查

• 对比代码版本，无变化跳过部署
• 显示提交信息
• 效果：避免不必要的重复部署

5. ✅ 手动触发支持

• 支持手动触发部署
• 可选择部署分支
• 效果：部署更灵活

6. ✅ 后端启动路径修复

• 修正 Nitro 输出路径
• 使用正确的启动命令
• 效果：后端服务正常启动

🚀 待实现的改进

1. 安全增强（高优先级）

1.1 使用 SSH Key 替代密码

当前问题：

• SSH 密码明文存储在配置文件中
• 存在安全风险

改进方案：

# 生成 SSH Key
ssh-keygen -t rsa -b 4096 -C "gitea-ci@kt-financial.com" -f ~/.ssh/gitea_ci_rsa

# 将公钥添加到服务器
ssh-copy-id -i ~/.ssh/gitea_ci_rsa.pub atai@172.16.74.149

# 修改 workflow 配置
- name: Deploy to server
  uses: appleboy/ssh-action@v1.0.0
  with:
    host: ${{ secrets.SERVER_HOST }}
    username: ${{ secrets.SERVER_USER }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}  # 使用私钥
    port: ${{ secrets.SERVER_PORT }}

收益：

• ✅ 提高安全性
• ✅ 符合最佳实践
• ✅ 便于密钥轮换

1.2 敏感信息管理

改进方案：

# 使用 .env 文件管理敏感信息
# docker-compose.yml
services:
  kt-financial:
    env_file:
      - .env.production
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET=${JWT_SECRET}
      - API_KEY=${API_KEY}

配置 Secrets：

1. 在 Gitea 仓库设置中添加 Secrets
2. 在部署脚本中使用 Secrets

2. 环境分离（中优先级）

2.1 多环境配置

目标：支持开发、测试、生产三个环境

文件结构：

.gitea/
  workflows/
    deploy-dev.yml      # 开发环境
    deploy-staging.yml  # 测试环境
    deploy-prod.yml     # 生产环境

配置示例：

# deploy-dev.yml
name: Deploy to Development

on:
  push:
    branches:
      - dev

env:
  SERVER_HOST: 172.16.74.150
  DEPLOY_PATH: /home/atai/kt-financial-dev
  PORT: 8081

jobs:
  deploy:
    # ... 部署配置

收益：

• ✅ 环境隔离
• ✅ 降低生产风险
• ✅ 支持灰度发布

2.2 环境变量管理

改进方案：

# .env.development
NODE_ENV=development
API_BASE_URL=http://172.16.74.150:8081
DEBUG=true

# .env.production
NODE_ENV=production
API_BASE_URL=http://172.16.74.149:8080
DEBUG=false

3. 回滚机制（高优先级）

3.1 镜像版本管理

改进方案：

- name: Tag and save image
  run: |
    VERSION=$(git rev-parse --short HEAD)
    sudo docker tag kt-financial-system:latest kt-financial-system:$VERSION

    # 保留最近 5 个版本
    sudo docker images | grep kt-financial-system | tail -n +6 | awk '{print $3}' | xargs -r sudo docker rmi

3.2 快速回滚

回滚脚本：

#!/bin/bash
# rollback.sh

VERSION=$1

if [ -z "$VERSION" ]; then
  echo "Usage: ./rollback.sh <version>"
  echo "Available versions:"
  docker images | grep kt-financial-system
  exit 1
fi

echo "Rolling back to version: $VERSION"
docker-compose down
docker tag kt-financial-system:$VERSION kt-financial-system:latest
docker-compose up -d

收益：

• ✅ 快速回滚
• ✅ 降低风险
• ✅ 提高可靠性

4. 通知集成（中优先级）

4.1 钉钉通知

改进方案：

- name: Send DingTalk notification
  if: always()
  run: |
    STATUS="${{ job.status }}"
    COLOR="success"
    [ "$STATUS" = "failure" ] && COLOR="failure"

    curl -X POST "${{ secrets.DINGTALK_WEBHOOK }}" \
      -H "Content-Type: application/json" \
      -d "{
        \"msgtype\": \"markdown\",
        \"markdown\": {
          \"title\": \"部署通知\",
          \"text\": \"## KT财务系统部署通知\n\n**状态**: $STATUS\n\n**分支**: ${{ github.ref_name }}\n\n**提交**: ${{ github.sha }}\n\n**提交者**: ${{ github.actor }}\n\n**时间**: $(date '+%Y-%m-%d %H:%M:%S')\n\n[查看详情](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})\"
        }
      }"

4.2 企业微信通知

配置示例：

- name: Send WeChat Work notification
  if: failure()
  run: |
    curl -X POST "${{ secrets.WECHAT_WEBHOOK }}" \
      -H "Content-Type: application/json" \
      -d "{
        \"msgtype\": \"text\",
        \"text\": {
          \"content\": \"⚠️ KT财务系统部署失败！\n\n请及时处理。\"
        }
      }"

收益：

• ✅ 实时通知
• ✅ 提高响应速度
• ✅ 团队协作

5. 监控和告警（中优先级）

5.1 Prometheus + Grafana

改进方案：

# docker-compose.yml
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    networks:
      - kt-network

  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana-data:/var/lib/grafana
    networks:
      - kt-network

volumes:
  prometheus-data:
  grafana-data:

5.2 日志聚合

改进方案：

# docker-compose.yml
services:
  loki:
    image: grafana/loki
    ports:
      - "3100:3100"
    networks:
      - kt-network

  promtail:
    image: grafana/promtail
    volumes:
      - /var/log:/var/log
      - ./monitoring/promtail-config.yml:/etc/promtail/config.yml
    networks:
      - kt-network

收益：

• ✅ 性能监控
• ✅ 日志分析
• ✅ 告警机制

6. 性能优化（低优先级）

6.1 Docker 构建优化

改进方案：

# 使用多阶段构建
FROM node:20-alpine AS base
# ... 基础镜像

# 开发依赖阶段
FROM base AS dev-deps
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 生产依赖阶段
FROM base AS prod-deps
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --prod --frozen-lockfile

# 构建阶段
FROM base AS builder
COPY --from=dev-deps /app/node_modules ./node_modules
# ... 构建步骤

# 运行阶段（最小化）
FROM base AS runner
COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist

6.2 构建缓存策略

改进方案：

- name: Cache Docker layers
  uses: actions/cache@v3
  with:
    path: /tmp/.buildx-cache
    key: ${{ runner.os }}-buildx-${{ github.sha }}
    restore-keys: |
      ${{ runner.os }}-buildx-

收益：

• ✅ 构建时间减少 30-50%
• ✅ 镜像体积减小
• ✅ 资源利用率提升

7. 测试覆盖（中优先级）

7.1 单元测试

改进方案：

- name: Run unit tests
  run: pnpm test:unit

- name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    files: ./coverage/coverage-final.json

7.2 E2E 测试

改进方案：

- name: Run E2E tests
  run: |
    pnpm build
    pnpm preview &
    sleep 5
    pnpm test:e2e

收益：

• ✅ 提高代码质量
• ✅ 减少 bug
• ✅ 自动化测试

8. 文档和规范（低优先级）

8.1 部署文档

改进建议：

• 添加架构图
• 添加故障排查指南
• 添加性能优化建议
• 添加安全最佳实践

8.2 变更日志

改进方案：

- name: Generate changelog
  run: |
    npm install -g conventional-changelog-cli
    conventional-changelog -p angular -i CHANGELOG.md -s
    git add CHANGELOG.md
    git commit -m "docs: update changelog"

📊 改进优先级矩阵

改进项	优先级	预计工作量	预期收益	状态
SSH Key 认证	高	1h	高	待实现
回滚机制	高	2h	高	待实现
环境分离	中	4h	中	待实现
通知集成	中	2h	中	待实现
监控告警	中	8h	高	待实现
测试覆盖	中	4h	中	待实现
性能优化	低	4h	中	待实现
文档完善	低	2h	低	进行中

🎯 实施计划

第一阶段（本周）

1. ✅ 优化 CI/CD 配置（已完成）
2. SSH Key 认证
3. 回滚机制

第二阶段（下周）

1. 环境分离
2. 通知集成
3. 测试覆盖

第三阶段（未来）

1. 监控告警
2. 性能优化
3. 文档完善

📝 参考资源

• Gitea Actions 文档
• Docker 最佳实践
• CI/CD 最佳实践
• Kubernetes 部署指南