This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

开发指南

本文档将帮助您了解XUGOU项目的开发环境配置、项目结构和开发流程。

环境要求

在开始开发XUGOU项目之前，请确保您的系统满足以下要求：

• Node.js >= 18
• Go >= 1.24
• Git

项目结构

XUGOU项目分为三个主要部分：

前端 (frontend)

前端使用React + TypeScript开发，目录结构如下：

frontend/
├── public/           # 静态资源
├── src/              # 源代码
│   ├── api/          # API调用
│   ├── components/   # 通用组件
│   ├── pages/        # 页面组件
│   ├── store/        # 状态管理
│   ├── styles/       # 样式文件
│   ├── types/        # TypeScript类型定义
│   └── utils/        # 工具函数
├── .env.local        # 本地环境变量
├── package.json      # 项目依赖
├── tsconfig.json     # TypeScript配置
└── vite.config.ts    # Vite配置

后端 (backend)

后端基于Cloudflare Workers开发，目录结构如下：

backend/
├── src/              # 源代码
│   ├── controllers/  # 控制器
│   ├── models/       # 数据模型
│   ├── routes/       # 路由定义
│   └── utils/        # 工具函数
├── schema.sql        # 数据库架构
├── wrangler.toml     # Cloudflare Workers配置
└── package.json      # 项目依赖

客户端 (agent)

监控客户端使用Go语言开发，目录结构如下：

agent/
├── cmd/              # 命令行命令
│   └── agent/        # 命令行实现
├── pkg/              # 功能包
│   ├── collector/    # 数据收集器
│   └── reporter/     # 数据上报器
├── main.go           # 程序入口
└── go.mod            # Go依赖

开发流程

1. 克隆项目

git clone https://github.com/zaunist/xugou.git
cd xugou

2. 前端开发

# 进入前端目录
cd frontend

# 安装依赖
pnpm install

# 配置环境变量
cp .env.local.example .env.local
# 编辑.env.local，设置后端API地址

# 启动开发服务器
pnpm run dev

前端开发服务器将在 http://localhost:5173 启动。

3. 后端开发

# 进入后端目录
cd backend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm run dev

后端开发服务器将在本地启动，通常在控制台输出中会显示地址。

4. 客户端开发

# 进入客户端目录
cd agent

# 构建客户端
go build -o xugou-agent

# 运行客户端（控制台输出模式）
./xugou-agent --server console start

代码提交规范

为保持代码库的一致性和可维护性，请遵循以下代码提交规范：

1. 分支管理：

   • main：主分支，只接受稳定版本的合并
   • dev：开发分支，日常开发在此分支上进行
   • 功能分支：以feature/为前缀，例如feature/dashboard
   • 修复分支：以fix/为前缀，例如fix/memory-leak

2. 提交信息：

   • 格式：类型: 描述，例如feat: 添加用户认证功能
   • 类型包括：
     • feat：新功能
     • fix：修复bug
     • docs：文档更新
     • style：代码风格修改（不影响代码功能）
     • refactor：重构代码
     • test：添加或修改测试
     • chore：构建过程或工具变动

3. 代码审查：所有代码合并到主分支前需要通过代码审查