mirror of https://github.com/Awuqing/BackupX.git synced 2026-08-29 03:57:39 +08:00

Files

T

Wu Qing 9080a47703 chore(repo): 完善仓库维护与自动化 (#108 )

统一 Node.js 24 LTS、CI、文档和发布工作流配置。

完善仓库维护规范、Dependabot 与贡献文档，清理生成产物并统一既有 Go 代码格式。

2026-08-09 21:18:19 +08:00

4.1 KiB

Raw Blame History

Contributing to BackupX

感谢你对 BackupX 的关注！本指南介绍如何搭建开发环境并提交贡献。 Thanks for your interest in contributing to BackupX! This guide covers how to set up your environment and submit changes.

开发环境 / Development Setup

依赖 / Prerequisites

Go 1.25+（见 server/go.mod）
Node.js 24 LTS（见 .node-version，CI 与 Docker 使用同一主版本）
npm 11+

快速开始 / Quick Start

分别在两个终端启动前后端（后端 :8340，前端 Vite HMR）：

git clone https://github.com/Awuqing/BackupX.git && cd BackupX
npm --prefix web ci
npm --prefix docs-site ci

# 终端 1 —— 后端（默认 http://localhost:8340）
make dev-server

# 终端 2 —— 前端（Vite 热更新，/api 代理到 8340）
make dev-web

构建 / Building

make build          # 同时构建后端与前端
make build-server   # 仅后端 → server/bin/backupx
make build-web      # 仅前端 → web/dist
make build-docs     # 仅文档站 → docs-site/build
make docker         # 构建 Docker 镜像
make docker-cn      # 国内镜像源加速构建

后端会自动托管 web/dist（或 server.web_root 指定目录），因此本地裸机部署无需额外的反向代理即可访问控制台。

测试 / Testing

提交前应执行与 CI 一致的完整验证：

make verify         # 格式、依赖、静态检查、测试与三端构建
make test           # 仅后端 + 前端测试
make test-server    # 仅后端：cd server && go test ./...
make test-web       # 仅前端：cd web && npm run test（vitest）
make check-docs     # 文档类型检查 + 中英文站点构建

新增功能或修复缺陷时，请补充对应测试。文档变更也必须通过严格断链检查，不能只依赖合并后的 Pages 部署结果。

提交信息规范 / Commit Messages

本项目采用 Conventional Commits，正文用中文撰写：

<type>(<scope>): <subject>

<body>

type	说明
`feat`	新功能
`fix`	缺陷修复
`docs`	文档变更
`style`	不影响逻辑的格式调整
`refactor`	重构
`perf`	性能优化
`test`	测试相关
`chore`	构建/依赖/工具链

示例：

feat(storage): 新增 Wasabi S3 后端支持
fix(cluster): 修复跨节点恢复的终态处理
docs: 补充 CONTRIBUTING 指南

Pull Request 流程

Fork 仓库并从最新的 main 切出特性分支；
开发功能或修复，必要时补充测试；
自测：确保 make verify 通过；
提交：使用上述 Conventional Commits（中文）；
推送并对着 main 发起 PR。

PR 描述建议

清晰说明本 PR 做了什么；
对新功能/修复，补充动机与背景；
关联相关 Issue（如 Closes #62）；
纯文档 PR 至少应附上 make check-docs 的结果。

请保持分支基于较新的 main：基线过旧的分支容易产生大范围冲突，难以评审与合入。

编码规范 / Coding Conventions

Go：遵循现有 handler → service → repository 分层；避免把连续业务流程拆成大量无复用价值的独立函数。所有错误必须处理，日志使用 zap，禁止 fmt.Println，提交前执行 gofmt 与 go vet。
前端组件：复用并组合现有组件，不在页面内复制同类交互逻辑，不擅自改变共享组件的基础样式，不引入新的 CSS 框架或 UI 库。
前端视觉：不使用 Emoji、渐变和 box-shadow；图标统一使用项目 SVG 图标组件；圆角为 0–4px；不引入独立字体，不用加粗字体制造层级，减少 Card，不使用数据左侧装饰竖线。
包管理：web/ 与 docs-site/ 均使用 npm；依赖变更必须同步提交对应的 package-lock.json。
文档：英文源文件与 zh-CN 翻译应同步维护；新增页面必须加入侧边栏并通过两种语言的生产构建。

License

向 BackupX 贡献即表示你同意你的贡献以 Apache License 2.0 授权。

4.1 KiB Raw Blame History Unescape Escape