.gitea/
├── workflows/                          # Gitea Actions workflow 文件
│   ├── ci-cd.yml                       # ⭐ 主 CI/CD 流水线
│   ├── test-runner.yml                 # Runner 连接测试
│   └── openapi-contract.yml            # API 契约检查
│
├── workflows-backup/                   # 旧配置备份
│   ├── build-and-deploy.yml
│   ├── ci-test.yml
│   ├── ci-cd.yml
│   └── README.md
│
├── runner-config/                      # Runner 配置文件
│   ├── config.yaml                     # ⭐ Runner 配置（使用 Harbor 镜像）
│   └── daemon.json                     # Docker daemon 配置
│
├── harbor-ca.crt                       # ⭐ Harbor CA 证书
├── verify-harbor-cert.sh               # ⭐ 验证 Harbor 证书配置（推荐）
├── sync-all-images.sh                  # 同步所有镜像到 Harbor
├── update-dockerfiles-proxy.sh         # 更新 Dockerfile 使用 Harbor Proxy
├── preheat-proxy-gitea.sh              # 预热 Harbor proxy-gitea 镜像
├── update-runner-config.sh             # 更新 Runner 配置
├── check-runner-registration.sh        # 检查 Runner 注册状态
├── check-runner-status.sh              # 检查 Runner 状态
├── remove-proxy-from-runner.sh         # 移除 Runner 代理配置
├── verify-no-proxy.sh                  # ⭐ 验证无代理配置
│
├── HARBOR_CERT_SETUP.md                # 📖 ⭐ Harbor 证书配置（必读）
├── QUICK_START.md                      # 📖 快速启动指南
├── GITEA_CI_CD_SETUP.md               # 📖 详细配置文档
├── HARBOR_CACHE_SETUP.md              # 📖 Harbor 缓存配置
├── IMAGE_REGISTRY.md                   # 📖 镜像清单和说明
└── README.md                           # 📖 本文档

🚀 快速开始

步骤 0：验证 Harbor 证书配置（必须）

cd /Users/brunogao/work/codes/ljwx/ljwx-health

# 验证 Harbor 证书和认证配置
./.gitea/verify-harbor-cert.sh

预期输出（全部 ✅）:

✅ Docker certs.d 证书存在
✅ 系统 CA 证书存在
✅ Docker 认证配置已加载
✅ 镜像拉取成功
✅ Runner 注册成功

重要: 如果有任何 ❌，请先参考 HARBOR_CERT_SETUP.md 解决证书问题

方式 1：一键配置（推荐）

cd /Users/brunogao/work/codes/ljwx/ljwx-health

# 一键完成所有配置
./.gitea/setup-harbor-cache.sh

耗时: 15-20 分钟（首次同步镜像）

完成后:

所有镜像已同步到 Harbor
Dockerfile 已更新使用 Harbor 镜像
Runner 已配置使用 Harbor 镜像
Harbor CA 证书已配置

方式 2：分步配置

# 步骤 1: 同步镜像到 Harbor (15-20 分钟)
./.gitea/sync-all-images.sh

# 步骤 2: 更新 Dockerfile
./.gitea/update-dockerfiles.sh

# 步骤 3: 更新 Runner 配置
./.gitea/update-runner-config.sh

# 步骤 4: 提交变更
git add .
git commit -m "chore: use Harbor registry for all base images"
git push origin main

📊 CI/CD 功能特性

主 CI/CD 流水线 (ci-cd.yml)

触发条件:

推送到 main 或 develop 分支
Pull Request
手动触发

构建组件:

ljwx-boot (Spring Boot 后端)
ljwx-admin (Vue3 前端)
ljwx-bigscreen (Python 监控面板)

部署目标:

Harbor 镜像仓库: harbor.omniverseai.net/ljwx-health/
K8s 集群: namespace ljwx-health

镜像管理

Runner 镜像 (Gitea Actions 执行环境):

ubuntu-latest
ubuntu-24.04
ubuntu-22.04

构建基础镜像 (Dockerfile 中使用):

eclipse-temurin:21-jdk-alpine (ljwx-boot 构建)
eclipse-temurin:21-jre-alpine (ljwx-boot 运行)
node:18-alpine (ljwx-admin 构建)
nginx:alpine (ljwx-admin 运行)
python:3.12-slim (ljwx-bigscreen)

总计: ~3.2 GB

⚙️ 配置要求

Gitea Secrets

在 Gitea 仓库设置中配置：

Secret 名称	说明	值
`HARBOR_USERNAME`	Harbor 用户名	`admin`
`HARBOR_PASSWORD`	Harbor 密码	`admin123`

配置路径: http://192.168.1.83:33000/gao/ljwx-health/settings/secrets

K8s Resources

必需的 namespace:

kubectl create namespace ljwx-health
kubectl create namespace gitea-runner  # 如果不存在

必需的 secrets:

# Harbor 拉取密钥
kubectl create secret docker-registry harbor-secret \
  --docker-server=harbor.omniverseai.net \
  --docker-username=admin \
  --docker-password=admin123 \
  --namespace=ljwx-health

🔧 常用命令

检查 Runner 状态

# 使用检查脚本
./.gitea/check-runner-status.sh

# 或手动检查
kubectl get pods -n gitea-runner
kubectl logs -n gitea-runner -l app=gitea-runner -c runner -f

验证无代理配置

重要: 本服务器不使用代理，如果出现 "dial tcp 192.168.1.83:7890: connect: connection refused" 错误，需要移除代理配置。

# 验证当前没有使用代理
./.gitea/verify-no-proxy.sh

# 如果发现代理配置，移除它
kubectl set env deployment/gitea-runner -n gitea-runner HTTP_PROXY- HTTPS_PROXY-

# 等待 deployment 更新
kubectl rollout status deployment/gitea-runner -n gitea-runner

手动触发 Workflow

访问: http://192.168.1.83:33000/gao/ljwx-health/actions

选择 workflow
点击 "Run workflow"
选择分支和参数
点击确认

查看构建日志

# Runner 日志
kubectl logs -n gitea-runner -l app=gitea-runner -c runner -f

# 应用部署日志
kubectl logs -n ljwx-health -l app=ljwx-boot -f

重新同步镜像

# 同步所有镜像
./.gitea/sync-all-images.sh

# 或同步特定镜像
docker pull docker.gitea.com/runner-images:ubuntu-latest
docker tag docker.gitea.com/runner-images:ubuntu-latest \
    harbor.omniverseai.net/ljwx-health/runner-images:ubuntu-latest
docker push harbor.omniverseai.net/ljwx-health/runner-images:ubuntu-latest

📈 性能提升

使用 Harbor 镜像缓存后：

指标	优化前	优化后	改善
Runner 镜像拉取	3-5 分钟	10-30 秒	~10倍
构建基础镜像	5-8 分钟	30-60 秒	~8倍
CI/CD 总耗时	8-12 分钟	3-5 分钟	~60%

🐛 故障排查

问题 0: TLS 证书验证失败（最常见）

症状:

tls: failed to verify certificate: x509: certificate signed by unknown authority

原因: Harbor CA 证书未正确配置或过期

解决:

# 1. 运行验证脚本
./.gitea/verify-harbor-cert.sh

# 2. 如果验证失败，查看详细解决方案
cat ./.gitea/HARBOR_CERT_SETUP.md

详细文档: HARBOR_CERT_SETUP.md

问题 1: Workflow 等待中

原因: Runner 标签不匹配或未运行

解决:

# 检查 runner 状态
./.gitea/check-runner-status.sh

# 检查 runner 注册
./.gitea/check-runner-registration.sh

# 重新配置 runner
./.gitea/update-runner-config.sh

问题 2: 镜像拉取慢

原因: 未使用 Harbor 镜像

解决:

# 同步镜像到 Harbor
./.gitea/sync-all-images.sh

# 更新配置
./.gitea/update-dockerfiles.sh
./.gitea/update-runner-config.sh

问题 3: Harbor 推送失败

原因: 登录失败或权限不足

解决:

# 测试登录
docker login harbor.omniverseai.net
# 用户名: admin
# 密码: admin123

# 检查项目权限
# 访问: https://harbor.omniverseai.net/harbor/projects/14/members

📚 详细文档

HARBOR_CERT_SETUP.md - ⭐ Harbor 证书配置完整指南（解决 TLS 错误）
QUICK_START.md - 5 分钟快速启动
GITEA_CI_CD_SETUP.md - 完整配置指南
HARBOR_CACHE_SETUP.md - Harbor 镜像缓存配置
IMAGE_REGISTRY.md - 镜像清单和管理

🔄 更新和维护

定期维护任务

每月一次:

# 更新镜像到最新版本
./.gitea/sync-all-images.sh

每次 Gitea 升级后:

# 检查 runner 兼容性
kubectl logs -n gitea-runner -l app=gitea-runner -c runner

# 如有需要，重新注册 runner
kubectl delete pod -n gitea-runner -l app=gitea-runner

监控和告警

Harbor 存储监控:

访问: https://harbor.omniverseai.net/harbor/projects/14/repositories
检查存储使用量和镜像列表

Runner 健康检查:

# 自动化健康检查脚本（可选）
watch -n 30 './.gitea/check-runner-status.sh'

🎯 最佳实践

使用 Harbor 缓存: 所有镜像都应通过 Harbor 拉取
定期同步: 每月同步一次最新镜像
标签管理: 使用固定标签而非 latest
监控日志: 定期检查 runner 和构建日志
备份配置: 配置变更前先备份

📧 技术支持

如遇问题:

查看相关文档（上方链接）
检查 runner 和 workflow 日志
验证 Harbor 连接和权限
参考故障排查章节

最后更新: 2025-12-15 维护者: Bruno Gao 项目: LJWX Health CI/CD

README.md Unescape Escape

Gitea CI/CD 配置文件说明

📁 目录结构