Plane + Gitea + GitHub 全链路集成系统

完整的任务管理、代码托管、CI/CD 和 AI 辅助开发解决方案

---

🚀 当前部署状态

部署时间: 2025-11-25 | 环境: macOS Development | 状态: ✅ 运行中

快速访问

服务	地址	状态	说明
Gitea	http://192.168.1.83:33000	✅ 运行中	Git 代码托管
同步服务	http://localhost:8828/health	✅ 健康	Gitea ↔ GitHub 自动同步
Plane DB	localhost:5432	✅ 健康	PostgreSQL 数据库
Plane Redis	localhost:6379	✅ 健康	缓存服务
Plane MinIO	http://localhost:9000	✅ 健康	对象存储

核心功能状态

• ✅ Gitea → GitHub 镜像同步: 已部署，5分钟自动同步
• ✅ 用户名自动检测: GitHub (BrunoGao) / Gitea (gao)
• ⚠️ Plane 完整部署: 基础设施就绪，需配置 API Token
• 📝 Webhook 集成: 待配置

详细状态: 查看 DEPLOYMENT-STATUS.md

---

📋 目录

• 系统概述
• 架构图
• 核心功能
• 快速开始
• 完整部署
• 配置指南
• 使用文档
• 故障排查

---

系统概述

这是一个生产级、企业级的全链路 DevOps 集成系统，整合了:

• Plane: 现代化任务管理平台 (类似 Jira/Linear)
• Gitea: 轻量级 Git 服务器 (自托管 GitHub)
• GitHub: 公开镜像仓库 (可选)
• Claude AI: AI 辅助开发 (代码生成、Review、测试)

核心价值

✅ 统一工作流: 任务 → 代码 → CI/CD → 部署 → 反馈，全流程打通 ✅ AI 增强: Claude AI 辅助需求分析、代码实现、测试生成 ✅ 双向同步: Plane ↔ Gitea ↔ GitHub 实时同步 ✅ 质量保证: 自动化测试、代码审查、安全扫描 ✅ 自托管: 完全掌控数据，无依赖外部服务

---

架构图

总体架构

graph TB
    subgraph "任务管理层"
        P[Plane<br/>任务管理]
    end

    subgraph "代码管理层"
        G[Gitea<br/>Git 服务器]
        GH[GitHub<br/>公开镜像]
    end

    subgraph "同步服务层"
        PS[Plane-Gitea<br/>Sync]
        PGH[Plane-GitHub<br/>Sync]
        GS[Gitea-GitHub<br/>Mirror]
    end

    subgraph "CI/CD 层"
        GA[Gitea Actions]
        GHA[GitHub Actions]
    end

    subgraph "容器平台"
        H[Harbor<br/>镜像仓库]
        K[K3s<br/>Kubernetes]
    end

    subgraph "AI 层"
        C[Claude AI<br/>开发助手]
    end

    P <--> PS <--> G
    P <--> PGH <--> GH
    G <--> GS <--> GH
    G --> GA
    GH --> GHA
    GA --> H
    GHA --> H
    H --> K
    C -.辅助.-> P
    C -.辅助.-> G
    C -.辅助.-> GH

    style P fill:#6366f1
    style G fill:#609926
    style GH fill:#24292e
    style C fill:#d4a574
    style K fill:#326ce5

数据流图

sequenceDiagram
    actor User
    participant Plane
    participant Claude
    participant Gitea
    participant GitHub
    participant CI/CD
    participant K8s

    User->>Plane: 1. 创建 Issue
    Plane-->>Claude: 2. 触发分析
    Claude->>Claude: 3. 生成技术方案
    Claude->>Gitea: 4. 创建分支 & 提交代码
    Gitea-->>GitHub: 5. 镜像同步
    Gitea->>CI/CD: 6. 触发 Pipeline
    CI/CD->>CI/CD: 7. 测试 & 构建
    CI/CD->>K8s: 8. 部署应用
    K8s-->>Plane: 9. 更新 Issue 状态
    Plane-->>User: 10. 通知完成

网络拓扑

┌─────────────────────────────────────────────────────────┐
│                     Host Network                        │
│                   192.168.1.83                          │
└─────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────▼─────┐  ┌──────▼─────┐  ┌──────▼─────┐
    │   Plane    │  │   Gitea    │  │   Harbor   │
    │  :8000     │  │  :33000    │  │   :8080    │
    │            │  │  SSH:32222 │  │            │
    └────────────┘  └────────────┘  └────────────┘
           │               │               │
           └───────────────┼───────────────┘
                           │
                  ┌────────▼────────┐
                  │   Sync Services │
                  │   :8001, :8002  │
                  └─────────────────┘
                           │
                  ┌────────▼────────┐
                  │  K3s Cluster    │
                  │  Applications   │
                  └─────────────────┘

---

核心功能

1. 任务管理 (Plane)

• ✅ Epic / Feature / Task / Bug 管理
• ✅ Sprint 计划和跟踪
• ✅ 看板视图 (Kanban)
• ✅ 甘特图 (Gantt)
• ✅ 团队协作
• ✅ 自定义字段和工作流

2. 代码托管 (Gitea + GitHub)

• ✅ Git 仓库管理
• ✅ Pull Request / Code Review
• ✅ Issue 跟踪
• ✅ Wiki 文档
• ✅ Gitea ↔ GitHub 双向镜像
• ✅ Webhook 集成

3. 双向同步

源	目标	触发方式	同步内容
Plane	Gitea	Webhook / 定时	Issue → Gitea Issue
Gitea	Plane	Webhook	PR/Commit → Plane Activity
Plane	GitHub	Webhook / 定时	Issue → GitHub Issue
GitHub	Plane	Webhook	PR/Commit → Plane Activity
Gitea	GitHub	Push / 定时	代码镜像
GitHub	Gitea	Webhook	反向同步 (可选)

4. CI/CD 流水线

• ✅ Gitea Actions (GitOps)
• ✅ 自动化测试
• ✅ 代码质量检查
• ✅ 安全扫描
• ✅ Docker 镜像构建
• ✅ 自动部署到 K3s

5. AI 辅助开发 (Claude)

• ✅ 需求分析和技术方案生成
• ✅ 代码实现 (支持多语言)
• ✅ 单元测试和集成测试生成
• ✅ Code Review 辅助
• ✅ Bug 分析和修复建议
• ✅ 文档生成

---

快速开始

前置条件

• Docker 20.10+
• Docker Compose 2.0+
• Git 2.30+
• kubectl (可选,用于 K8s 部署)
• 8GB+ RAM 推荐

5 分钟快速部署

# 1. 克隆仓库
git clone https://github.com/your-repo/plane-gitea-github-infra.git
cd plane-gitea-github-infra

# 2. 配置环境变量
cp plane/env.example plane/.env
# 编辑 plane/.env,填入你的 Token

# 3. 启动 Plane
cd plane
docker-compose up -d

# 4. 访问 Plane
open http://localhost:8000

# 5. 配置 Gitea 集成 (见下文)

验证部署

# 检查服务状态
docker ps

# 应该看到:
# - plane-web
# - plane-api
# - plane-worker
# - plane-db
# - plane-redis
# - plane-minio

---

完整部署

部署选项

部署方式	适用场景	复杂度
Docker Compose	本地开发、小团队	⭐ 简单
K3s	生产环境、多节点	⭐⭐⭐ 中等
K8s (完整)	大型企业、高可用	⭐⭐⭐⭐⭐ 复杂

方式 1: Docker Compose 部署 (推荐新手)

1.1 部署 Plane

cd plane
docker-compose up -d

# 初始化 Plane
docker-compose exec plane-api python manage.py migrate
docker-compose exec plane-api python manage.py createsuperuser

1.2 部署 Gitea (如已有,跳过)

cd ../gitea
# 编辑 docker-compose.yaml 配置
docker-compose up -d

1.3 部署同步服务

# Gitea ↔ GitHub 同步
cd ../gitea-to-github-sync
docker build -t gitea-github-sync .
docker-compose up -d

# Plane ↔ Gitea 同步
cd ../plane-integration/gitea-sync
docker build -t plane-gitea-sync .
docker-compose up -d

# Plane ↔ GitHub 同步
cd ../github-sync
docker build -t plane-github-sync .
docker-compose up -d

1.4 验证

# 检查所有服务健康状态
curl http://localhost:8000/api/health/
curl http://192.168.1.83:33000/api/v1/version
curl http://localhost:8828/health   # Gitea-GitHub sync
curl http://localhost:8001/health   # Plane-Gitea sync
curl http://localhost:8002/health   # Plane-GitHub sync

方式 2: K3s 部署 (生产环境)

2.1 安装 K3s

# 安装 K3s
curl -sfL https://get.k3s.io | sh -

# 验证安装
kubectl get nodes

2.2 部署应用

# 部署 Plane
kubectl apply -f k3s/plane.yaml

# 检查状态
kubectl get pods -n plane-system

# 等待所有 Pod 就绪
kubectl wait --for=condition=ready pod -l app=plane-web -n plane-system --timeout=300s

2.3 配置 Ingress

# 安装 Traefik (如果需要)
kubectl apply -f k3s/gateway.yaml

# 配置域名解析
echo "127.0.0.1 plane.local" | sudo tee -a /etc/hosts

2.4 配置同步服务

# 部署 Gitea-GitHub 同步 CronJob
kubectl apply -f gitea-to-github-sync/cronjob.yaml

# 查看 CronJob
kubectl get cronjobs

---

配置指南

1. 获取 API Tokens

Plane API Token

# 方式 1: 通过 UI
1. 登录 Plane: http://localhost:8000
2. Settings → API Tokens
3. Create New Token
4. 复制 Token

# 方式 2: 通过 API
curl -X POST http://localhost:8000/api/v1/auth/api-tokens/ \
  -H "Authorization: Bearer <your-auth-token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "Sync Service"}'

Gitea Token

# 通过 UI
1. 登录 Gitea: http://192.168.1.83:33000
2. Settings → Applications
3. Generate New Token
4. 选择权限: repo, admin:org, write:issue
5. 复制 Token

# 通过 API
curl -X POST http://192.168.1.83:33000/api/v1/users/<username>/tokens \
  -u "<username>:<password>" \
  -H "Content-Type: application/json" \
  -d '{"name": "sync-service"}'

GitHub Token

# 通过 GitHub UI
1. Settings → Developer settings → Personal access tokens
2. Generate new token (classic)
3. 选择权限: repo, workflow, admin:repo_hook
4. Generate token
5. 复制 Token

2. 配置环境变量

编辑 plane/.env:

# Plane
PLANE_API_TOKEN=plane_your_token_here

# Gitea
GITEA_URL=http://192.168.1.83:33000
GITEA_TOKEN=your_gitea_token

# GitHub
GITHUB_TOKEN=ghp_your_github_token

# Webhook Secret (自己生成)
WEBHOOK_SECRET=$(openssl rand -hex 32)

3. 配置 Webhooks

3.1 Gitea Webhook

# 在 Gitea 仓库中配置
Repository Settings → Webhooks → Add Webhook

URL: http://plane-gitea-sync:8001/webhook/gitea
Content Type: application/json
Secret: <your-webhook-secret>

Events:
☑ Push
☑ Pull Request
☑ Issues
☑ Issue Comment

3.2 GitHub Webhook

# 在 GitHub 仓库中配置
Repository Settings → Webhooks → Add webhook

Payload URL: http://your-domain:8002/webhook/github
Content type: application/json
Secret: <your-webhook-secret>

Events:
☑ Pull requests
☑ Pushes
☑ Issues
☑ Issue comments
☑ Pull request reviews

4. 配置 Plane 项目

在 Plane 项目中添加自定义字段:

# 项目描述或自定义属性
gitea_integration:
  owner: your-username
  repo: your-repo
  sync_enabled: true

github_integration:
  owner: your-username
  repo: your-repo
  sync_enabled: true

---

使用文档

完整文档链接

• 📘 Plane 模板使用指南
• 📗 Claude AI 协作工作流
• 📕 Gitea Webhook 配置
• 📙 GitHub Webhook 配置

典型工作流程

# 1. 在 Plane 创建 Feature Issue
→ 使用 Feature 模板
→ 填写需求和验收标准
→ 添加标签和优先级

# 2. Claude 分析需求
→ Claude 读取 Issue
→ 生成技术方案
→ 创建 Git 分支

# 3. 开发实现
→ Claude 生成代码
→ 自动提交到 Gitea
→ 镜像同步到 GitHub

# 4. 创建 PR
→ Claude 生成 PR 描述
→ 自动触发 CI/CD
→ 代码质量检查

# 5. Code Review & 合并
→ 团队 Review 代码
→ CI 检查通过
→ 合并到主分支

# 6. 自动部署
→ 构建 Docker 镜像
→ 推送到 Harbor
→ 部署到 K3s

# 7. 验证 & 更新
→ 部署验证
→ Plane Issue 自动更新为 Done
→ 通知团队

---

故障排查

常见问题

1. Plane 无法访问

# 检查容器状态
docker ps -a | grep plane

# 查看日志
docker logs plane-web
docker logs plane-api

# 重启服务
docker-compose restart

2. Webhook 未触发

# 检查 webhook URL 是否可访问
curl -X POST http://plane-gitea-sync:8001/health

# 检查 webhook secret
# 在 Gitea/GitHub webhook 页面查看 Recent Deliveries

# 查看同步服务日志
docker logs plane-gitea-sync
docker logs plane-github-sync

3. 同步失败

# 测试 API 连接
curl -H "Authorization: token $GITEA_TOKEN" \
  http://192.168.1.83:33000/api/v1/user

curl -H "Authorization: Bearer $PLANE_API_TOKEN" \
  http://localhost:8000/api/v1/users/me/

# 检查 Token 权限
# 确保 Token 有足够的权限 (repo, issues, etc.)

# 手动触发同步
curl -X POST http://localhost:8001/sync/manual \
  -H "Content-Type: application/json" \
  -d '{"workspace_slug": "my-workspace", "project_id": "proj_123", ...}'

4. CI/CD 失败

# 查看 Gitea Actions 日志
# Gitea → Repository → Actions → Workflows

# 查看 Runner 状态
docker ps | grep gitea-runner

# 重启 Runner
docker restart gitea-runner-docker

日志收集

# 收集所有日志用于排查
mkdir -p logs

docker logs plane-web > logs/plane-web.log 2>&1
docker logs plane-api > logs/plane-api.log 2>&1
docker logs plane-gitea-sync > logs/sync-gitea.log 2>&1
docker logs plane-github-sync > logs/sync-github.log 2>&1
docker logs gitea-github-mirror > logs/mirror.log 2>&1

# 打包日志
tar -czf logs-$(date +%Y%m%d-%H%M%S).tar.gz logs/

---

项目结构

plane-gitea-github-infra/
├── README.md                          # 本文件
├── plane/                             # Plane 部署
│   ├── docker-compose.yaml
│   └── env.example
├── gitea/                             # Gitea 配置
│   ├── docker-compose.yaml
│   ├── app.ini
│   └── gitea-mirror.sh
├── gitea-to-github-sync/             # Gitea ↔ GitHub 同步
│   ├── sync.py
│   ├── Dockerfile
│   ├── requirements.txt
│   └── cronjob.yaml
├── plane-integration/                 # Plane 集成
│   ├── gitea-sync/                   # Plane ↔ Gitea
│   │   ├── sync_service.py
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── github-sync/                  # Plane ↔ GitHub
│   │   ├── sync_service.py
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── gitea-webhook.md
│   └── github-webhook.md
├── k3s/                               # Kubernetes 部署
│   ├── plane.yaml
│   ├── gitea.yaml
│   └── gateway.yaml
├── docs/                              # 文档
│   ├── plane-templates.md            # Plane 模板
│   └── claude-dev-workflow.md        # Claude 工作流
└── examples/                          # 示例项目
    ├── health-platform/
    └── stock-ai-recommender/

---

系统要求

开发环境

• CPU: 2 cores+
• RAM: 4GB+
• Disk: 20GB+
• OS: macOS / Linux / Windows (WSL2)

生产环境

• CPU: 4 cores+
• RAM: 8GB+
• Disk: 50GB+ SSD
• OS: Ubuntu 20.04+ / Debian 11+

---

性能指标

响应时间

• Plane API: < 200ms (P95)
• Gitea API: < 150ms (P95)
• Sync Service: < 500ms (P95)

吞吐量

• Webhook 处理: 100+ req/s
• Concurrent Users: 50+
• Repository Sync: 10+ repos/min

资源使用

• Plane: ~1GB RAM
• Gitea: ~500MB RAM
• Sync Services: ~200MB RAM each
• Total: ~2GB RAM

---

安全建议

1. ✅ 使用强密码和 Token
2. ✅ 启用 HTTPS (生产环境)
3. ✅ 配置防火墙规则
4. ✅ 定期备份数据
5. ✅ 更新依赖和镜像
6. ✅ 监控异常活动
7. ✅ 使用 Webhook Secret验证
8. ✅ 限制 API 访问权限

---

备份与恢复

备份

# 备份 Plane 数据库
docker exec plane-db pg_dump -U plane plane > plane-backup.sql

# 备份 Gitea 数据
cd ~/ops/gitea
./gitea-backup.sh

# 备份配置文件
tar -czf config-backup.tar.gz \
  plane/.env \
  gitea/app.ini \
  k3s/*.yaml

恢复

# 恢复 Plane 数据库
docker exec -i plane-db psql -U plane plane < plane-backup.sql

# 恢复 Gitea
cd ~/ops/gitea
./gitea-restore.sh backup-20251124-220000

---

贡献指南

欢迎贡献! 请查看 CONTRIBUTING.md

---

许可证

MIT License - 详见 LICENSE

---

致谢

• Plane - 现代任务管理平台
• Gitea - 轻量级 Git 服务
• GitHub - 开源协作平台
• Claude AI - AI 编程助手

---

联系方式

• Issue Tracker: https://github.com/your-repo/issues
• Documentation: https://docs.your-domain.com
• Email: [email protected]

---

🎉 Happy Coding with Plane + Gitea + GitHub + Claude! 🎉

Last Updated: 2025-11-24 Version: 1.0.0