panel/.github/copilot-instructions.md

项目描述

本项目是基于 Go 语言的 Fiber 框架和 wire 依赖注入开发的 AcePanel Linux 服务器运维管理面板，目前正在进行 v3 版本重构。

v3 版本需要完成以下重构任务：

1. 使用 Fiber v3 替换目前的 go-chi 路由
2. 全新的项目模块，支持运行 Java/Go/Python 等项目
3. 网站模块重构，支持多 Web 服务器（Apache/OLS/Kangle）
4. 备份模块重构，需要支持 s3 和 ftp/sftp 备份途径
5. 计划任务模块重构，支持管理备份任务和自定义脚本任务等

项目结构

├── cmd/ │ ├── ace/ 面板主程序 │ └── cli/ 面板命令行工具 ├── internal/ │ ├── app/ 应用入口 │ ├── apps/ 面板各子应用的实现 │ ├── biz/ 业务逻辑的接口和数据库模型定义，类似 DDD 的 domain 层，data 类似 DDD 的 repo，而业务接口在这里定义，使用依赖倒置的原则 │ ├── bootstrap/ 各个模块的启动引导 │ ├── data/ 业务数据访问，包含 cache、db 等封装，实现了 biz 的业务接口。我们可能会把 data 与 dao 混淆在一起，data 偏重业务的含义，它所要做的是将领域对象重新拿出来，我们去掉了 DDD 的 infra 层 │ ├── http/ │ │ ├── middleware/ 自定义路由中间件 │ │ ├── request/ 请求结构体 │ │ └── rule/ 自定义验证规则 │ ├── job/ 面板后台任务 │ ├── migration/ 数据库迁移定义 │ ├── queuejob/ 面板任务队列 │ ├── route/ 路由定义 │ └── service/ 实现了路由定义的服务层，类似 DDD 的 application 层，处理 DTO 到 biz 领域实体的转换(DTO -> DO)，同时协同各类 biz 交互，但是不应处理复杂逻辑 ├── mocks/ 模拟数据，目前没有使用 ├── pkg/ 工具函数及包 ├── storage/ 数据存储 └── web/ 前端项目

架构

• 后端：Go 语言，使用 chi 路由（正在迁移至 Fiber v3）+ wire 依赖注入 + GORM
• 前端：Vue 3 + TypeScript + Vite + Naive UI + pnpm
• 数据库：SQLite3
• 配置：基于 YAML 的 config.yml 文件

引导程序和依赖项

• 使用 pnpm 安装 Go 1.24+ 和 Node.js：
• go version -- 验证 Go 1.24+
• npm install -g pnpm -- 安装 pnpm 包管理器
• cd /home/runner/work/panel/panel && cp config.example.yml config.yml -- 复制所需的配置文件
• 下载依赖项：
• go mod download -- 大约需要 30 秒。请勿取消。请将超时设置为 60 分钟以上。
• cd web && pnpm install -- 大约需要 30 秒。请勿取消。请将超时设置为 60 分钟以上。

构建流程

• 构建后端应用：
• go build -o ace ./cmd/ace -- 耗时约 14 秒。请勿取消。请将超时时间设置为 30 分钟以上。
• go build -o cli ./cmd/cli -- 耗时约 1 秒。请勿取消。请将超时时间设置为 30 分钟以上。
• 构建前端应用：
• cd web && cp .env.production .env && cp settings/proxy-config.example.ts settings/proxy-config.ts
• cd web && pnpm run gettext:compile -- 编译翻译，耗时约 1 秒
• cd web && pnpm build -- 耗时约 30 秒。请勿取消。请将超时时间设置为 60 分钟以上。
• 构建工件位置：
• 后端二进制文件：在仓库根目录中构建为 ace 和 cli
• 前端资源：构建到 web/dist/ 并复制到 pkg/embed/frontend/

开发指南

• 使用 github.com/gofiber/fiber/v3 和 gorm.io/gorm 进行开发
• Fiber v3 handler 使用 c fiber.Ctx 而不是 c *fiber.Ctx
• 使用泛型 Bind 助手函数绑定请求，使用 Success 助手函数响应成功，使用 Error/ErrorSystem 助手函数响应错误，泛型 Paginate 助手函数构建各种分页响应
• 遵循项目的 DDD 分层架构：biz → data → service → route
• 使用标准库 slog 进行日志记录
• 编写完整、安全、高效的代码，不留待办事项
• 使用 testify/suite 模式编写测试

开发新需求时的流程

1. 在 route/http 中添加新的路由和注入需要的服务
2. 在 service 中添加新的服务方法，先读取已存在的其他服务方法，以参考它们的实现方式
3. 在 biz 中添加新的业务逻辑需要的接口等，先读取已存在的其他接口，以参考它们的实现方式
4. 在 data 中实现 biz 的接口，先读取已存在的其他实现，以参考它们的实现方式