panel/.github/CONTRIBUTING.md

贡献指南

感谢你考虑为 AcePanel 做出贡献！这份文档将帮助你了解如何参与到项目中来。

目录

• 行为准则
• 我能做什么贡献？
• 开发环境设置
• 开发流程
• 代码规范
• 提交信息规范
• Pull Request 流程

行为准则

参与本项目即表示你同意遵守我们的行为准则。请保持友善、尊重和专业。

我能做什么贡献？

你可以通过以下方式为 AcePanel 做出贡献：

• 🐛 报告 Bug
• 💡 提出新功能建议
• 📝 改进文档
• 🔧 修复 Bug
• ✨ 实现新功能
• 🧪 编写测试
• 🌍 翻译面板及文档

开发环境设置

前置要求

• Go 1.25 或更高版本
• Node.js 22+ 和 pnpm
• Git
• 本地开发环境没有特殊要求，但必须在 Linux 上运行和测试
• 在开发及测试前端项目时，需修改面板配置文件打开 debug 模式或者关闭安全入口

克隆仓库

git clone https://github.com/acepanel/panel.git
cd panel

后端设置

1. 安装 Go 依赖：

go mod download

2. 复制配置文件：

cp config.example.yml config.yml # 按需修改配置

3. 构建项目：

go build -o ace ./cmd/ace # 主程序
go build -o cli ./cmd/cli # CLI 工具

前端设置

1. 进入前端目录：

cd web

2. 安装依赖：

pnpm install

3. 配置开发环境：

cp .env.production .env # 按需修改
cp settings/proxy-config.example.ts settings/proxy-config.ts # 配置 Linux 测试服务器信息
pnpm run gen-auto-import # 生成自动导入文件，开发中无需导入 vue alova 等常用包
pnpm run gettext:compile # 预编译翻译文件，否则开发中没有翻译

4. 启动开发服务器：

pnpm dev

开发流程

项目架构

AcePanel 采用类 DDD 分层架构，依赖关系为：route → service → biz ← data

主要目录结构：

• cmd/ - 程序入口（ace 主程序、cli 工具）
• internal/route/ - HTTP 路由定义
• internal/service/ - 服务层（处理 HTTP 请求/响应）
• internal/biz/ - 业务逻辑层（定义业务接口和领域模型）
• internal/data/ - 数据访问层（实现 biz 接口）
• pkg/ - 工具函数和通用包
• web/ - Vue 3 前端项目

开发新功能的标准流程

1. 在 internal/route/ 中添加路由

   • 按需注入需要的服务

2. 在 internal/service/ 中实现服务方法

   • 处理请求验证和响应格式化
   • 使用 Success() 返回成功响应
   • 使用 Error() 返回错误响应
   • 使用 ErrorSystem() 返回系统严重错误

3. 在 internal/biz/ 中定义业务接口

   • 定义 Repository 接口
   • 定义领域模型结构体
   • 保持接口简洁明确

4. 在 internal/data/ 中实现 biz 接口

   • 创建 repo 结构体
   • 实现构造函数
   • 实现所有接口方法

5. 使用 Wire 进行依赖注入

   • 在对应的 包名.go 文件中添加 Provider
   • 运行 go generate ./... 生成依赖注入代码

代码规范

所有代码注释必须使用简体中文

面板基于 Gettext 搭建了自动化国际化流程，所有对用户可见的文本均需支持国际化，原文使用英文。

开发中 Go 代码中注入 *gotext.Locale，前端导入 useGettext 进行翻译。

Go 代码规范

• 遵循 Go 官方代码风格
• 使用 gofmt 格式化代码和 golangci-lint 检查代码质量
• 函数和方法注释必须以函数名开头，复杂逻辑应添加注释说明

前端代码规范

• 使用 Vue 3 Composition API
• 遵循项目已有的组件结构和编码风格
• 使用 TypeScript 进行类型检查
• 运行 pnpm lint 检查代码质量

提交信息规范

我们使用语义化的提交信息，格式为：

<类型>(<范围>): <简短描述>

<详细描述>（可选）

<关联的 Issue>（可选）

类型

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式调整（不影响功能）
• refactor: 代码重构
• perf: 性能优化
• test: 测试相关
• chore: 构建/工具链相关

示例

feat(website): 添加网站备份功能

实现了网站配置和数据的自动备份功能，支持：
- 按计划自动备份
- 手动立即备份
- 备份文件压缩存储

Closes #123

fix(apache): 修复代理配置解析错误

修复了在解析包含特殊字符的代理配置时的崩溃问题

Pull Request 流程

1. Fork 项目

点击 GitHub 页面右上角的 "Fork" 按钮。

2. 创建开发分支

git checkout -b your-develop-name

3. 进行开发

• 遵循代码规范
• 中文编写必要的代码注释
• 添加必要的测试，目前主要针对 pkg 目录下的公共包
• 若进行大范围的重构/修改，请提前与维护者沟通

4. 提交更改

git add .
git commit -m "feat(scope): 描述你的更改"

5. 推送到你的 Fork

git push origin your-develop-name

6. 创建 Pull Request

1. 访问你 Fork 的仓库
2. 点击 "New Pull Request"
3. 选择你的分支
4. 填写 PR 检查单并点击 "Create Pull Request"

7. 等待审查

当 Pull Request 开发完毕后，请为其添加 🚀 Review Ready 标签，维护者将及时进行评审并提供反馈。请及时响应评论并根据需要进行修改。

许可证

通过向本项目贡献代码，你同意你的贡献将在与项目相同的许可证下发布。

---

再次感谢你的贡献！🎉