From b46aaf431384ee016e75c5d59f0a8af5489e5d86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=80=97=E5=AD=90?= <haozi@loli.email>
Date: Wed, 3 Dec 2025 20:10:41 +0800
Subject: [PATCH] chore: add CONTRIBUTING.md

---
 .github/CONTRIBUTING.md | 251 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 251 insertions(+)
 create mode 100644 .github/CONTRIBUTING.md

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 00000000..462288b3
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,251 @@
+# 贡献指南
+
+感谢你考虑为 AcePanel 做出贡献！这份文档将帮助你了解如何参与到项目中来。
+
+## 目录
+
+- [行为准则](#行为准则)
+- [我能做什么贡献？](#我能做什么贡献)
+- [开发环境设置](#开发环境设置)
+- [开发流程](#开发流程)
+- [代码规范](#代码规范)
+- [提交信息规范](#提交信息规范)
+- [Pull Request 流程](#pull-request-流程)
+
+## 行为准则
+
+参与本项目即表示你同意遵守我们的行为准则。请保持友善、尊重和专业。
+
+## 我能做什么贡献？
+
+你可以通过以下方式为 AcePanel 做出贡献：
+
+- 🐛 报告 Bug
+- 💡 提出新功能建议
+- 📝 改进文档
+- 🔧 修复 Bug
+- ✨ 实现新功能
+- 🧪 编写测试
+- 🌍 翻译面板及文档
+
+## 开发环境设置
+
+### 前置要求
+
+- Go 1.25 或更高版本
+- Node.js 22+ 和 pnpm
+- Git
+- 本地开发环境没有特殊要求，但必须在 Linux 上运行和测试
+- 在开发及测试前端项目时，需修改面板配置文件打开 debug 模式或者关闭安全入口
+
+### 克隆仓库
+
+```bash
+git clone https://github.com/acepanel/panel.git
+cd panel
+```
+
+### 后端设置
+
+1. 安装 Go 依赖：
+
+```bash
+go mod download
+```
+
+2. 复制配置文件：
+
+```bash
+cp config.example.yml config.yml # 按需修改配置
+```
+
+3. 构建项目：
+
+```bash
+go build -o ace ./cmd/ace # 主程序
+go build -o cli ./cmd/cli # CLI 工具
+```
+
+### 前端设置
+
+1. 进入前端目录：
+
+```bash
+cd web
+```
+
+2. 安装依赖：
+
+```bash
+pnpm install
+```
+
+3. 配置开发环境：
+
+```bash
+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. 启动开发服务器：
+
+```bash
+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. 创建开发分支
+
+```bash
+git checkout -b your-develop-name
+```
+
+### 3. 进行开发
+
+- 遵循代码规范
+- 中文编写必要的代码注释
+- 添加必要的测试，目前主要针对 pkg 目录下的公共包
+- 若进行大范围的重构/修改，请提前与维护者沟通
+
+### 4. 提交更改
+
+```bash
+git add .
+git commit -m "feat(scope): 描述你的更改"
+```
+
+### 5. 推送到你的 Fork
+
+```bash
+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 标签，维护者将及时进行评审并提供反馈。请及时响应评论并根据需要进行修改。
+
+## 许可证
+
+通过向本项目贡献代码，你同意你的贡献将在与项目相同的许可证下发布。
+
+---
+
+再次感谢你的贡献！🎉