HomeBox 贡献指南：从开发环境搭建到发布流程的完整上手实践-开发者社区

后端
前端

【免费下载链接】homebox

A continuation of HomeBox the inventory and organization system built for the Home User

项目地址：https://gitcode.com/gh_mirrors/home/homebox

本文以仓库根目录的 CONTRIBUTING.md 为骨架，面向想要为 HomeBox（面向家庭用户的库存与组织管理系统）贡献代码的开发者，系统讲解分支协作规范、开发环境搭建、前后端开发工作流与版本发布流水线。读完本文，你将能够独立完成一次从main分支拉取特性分支、编写测试、跑通 lint 与 CI 检查、提交 PR，并理解维护者如何通过打标签触发自动化发布的全过程。文中所涉命令、依赖版本与配置均以当前仓库实际内容为准。

一、项目概览与协作模型

HomeBox 是一个面向家庭用户的库存（Inventory）与组织（Organization）管理系统，仓库采用Go（后端 API） + Vue 3 / Nuxt（前端）的经典前后端分离结构：

后端：位于 backend 目录，Go 模块声明见 backend/go.mod（当前要求 Go 1.26.0），使用 ent 作为 ORM、chi 作为 HTTP 路由框架，数据层支持 SQLite 与 PostgreSQL；
前端：位于 frontend 目录，是基于 Vue 3 与 Nuxt 的应用（当前 Nuxt 版本为 4.4.7，包管理器为 pnpm，见 frontend/package.json），使用 Tailwind 与 shadcn-vue 组件体系。

在贡献代码之前，需要先理解两条最基本的协作约定：

以 GitHub 作为协作枢纽：代码托管、Issue 与功能请求跟踪、Pull Request 接收都围绕 GitHub 展开；
main分支是唯一开发主线：所有 PR 都必须从特性分支合并到main，禁止直接在main上开发。

从源码结构看，CI 流水线（.github/workflows/pull-requests.yaml）还同时监听main与vnext分支的 PR，后者是预留给下一大版本迭代的分支。日常贡献者只需聚焦main。

二、分支流程：一次标准 PR 的五步走

CONTRIBUTING.md 给出了提交 PR 的五个标准步骤，逐条结合仓库实际说明如下：

Fork 仓库并从main创建新分支。在自己的 Fork 中执行git checkout -b feature/my-change main，保持特性分支命名语义化（如feature/xxx、fix/xxx、docs/xxx），便于维护者审阅；
新增代码必须补测试。后端 Go 测试与前端 TypeScript 测试的组织方式见后文「开发注意事项」，仓库中已有大量可参照的测试基座，例如后端 backend/internal/core/services/service_entities_test.go、前端 frontend/test/e2e/login.browser.spec.ts；
API 变更必须同步更新文档。HomeBox 的 API 文档由 Swagger 注解自动生成，修改后端接口后需要重新生成文档（task swag），产出的 OpenAPI/Swagger 文档见 docs/public/api/；
确保测试套件与 linters 全部通过。合并前 CI 会并行跑后端单测、前端测试与 Playwright 端到端测试（见 .github/workflows/pull-requests.yaml 中引用的三个 partial workflow），本地可用task pr一次性预演全部检查（详见第六节）；
发起 Pull Request。PR 目标分支为main，GitHub 会自动挂载 CI 检查状态，全部通过后等待维护者 review 与 merge。

三、开发环境搭建

3.1 前置依赖清单

官方推荐优先使用项目自带的devcontainer（.devcontainer/目录），使用 VSCode 打开仓库时会提示在容器内重新打开，容器已预装 Go 1.26 特性并执行task setup（见 .devcontainer/devcontainer.json 的features与postCreateCommand），开发者无需手工安装任何工具。

如果不用 devcontainer，则需要在宿主机安装以下工具（括号内为当前仓库实际使用的版本依据）：

工具	用途	版本依据
Go	后端编译与单元测试	backend/go.mod 声明`go 1.26.0`，CI 中`actions/setup-go`使用 1.26（见 .github/workflows/binaries-publish.yaml）
Swaggo（`swag`）	从 Go 注解生成 Swagger 文档	`task setup`中执行`go install github.com/swaggo/swag/cmd/swag@latest`
Node.js	前端工具链运行时	前端包管理器要求 pnpm，构建产物为 Nuxt 静态站点
pnpm	前端依赖安装与脚本执行	frontend/package.json 声明`"packageManager": "pnpm@10.28.0"`，CI 使用 pnpm 10
Taskfile（可选但推荐）	统一封装全部开发命令	仓库根目录 Taskfile.yml，`version: "3"`
python3	代码生成辅助	官方说明：大部分系统已预装，用于代码生成环节

版本提示：CONTRIBUTING.md 中写的 "Go 1.19+" 与 "Node.js 16+" 是历史最低要求，当前仓库已演进到 Go 1.26 与 pnpm 10 时代，请以本仓库实际版本为准。

3.2 一键初始化与任务总览

安装 Taskfile 后，先看一眼全部可用命令：

task --list-all

任务清单来自 Taskfile.yml，覆盖依赖安装、代码生成、后端运行、前端开发、测试、CI 模拟与发布预检。随后执行一键初始化：

task setup

该命令实际执行的内容（见 Taskfile.yml 的setup任务）为：

go install github.com/swaggo/swag/cmd/swag@latest go install github.com/pressly/goose/v3/cmd/goose@v3.8.0 # 数据库迁移工具 cd backend && go mod tidy cd frontend && pnpm install

不习惯 Taskfile 的开发者，也可以直接逐条执行上述命令，效果等价。

四、开发注意事项：后端（API）

4.1 启动开发服务器

task go:run

该任务（Taskfile.yml 的go:run）的执行细节值得注意：

前置依赖generate：会先跑一遍完整代码生成（ent 数据库代码 → Swagger 文档 → TypeScript 类型），首次运行耗时较长属正常现象；
环境变量：任务为本地开发预置了HBOX_DEMO=true与UNSAFE_DISABLE_PASSWORD_PROJECTION="yes_i_am_sure"。其中后者是「仅在本地开发服务器上把密码哈希退化为明文」的便利开关，Taskfile 顶部注释特别提醒：这个变量绝不能全局设置——若作用于go:test/go:coverage，Go 测试套件会走明文分支而非 argon2id，导致 CI 中的TestTimingEqualizationHashIsValidArgon2测试失败；
数据库：默认使用 SQLite（HBOX_DATABASE_DRIVER=sqlite3，路径.data/homebox.db，带 WAL、busy_timeout 等 pragma），无需额外部署数据库即可开发。

如需用 PostgreSQL 开发，运行task go:run:postgresql，该任务会覆盖数据库连接相关环境变量（driver=postgres、localhost:5432、用户/密码/库名均为 homebox、禁用 SSL）。

4.2 两条硬性约定

CONTRIBUTING.md 对后端开发明确了两条约定：

API 服务器不会自动热重载。go run进程在代码修改后不会自动重启，每次改动需要手动终止并重新执行task go:run。这与常见的前端 HMR 体验不同，请养成「改完重启」的习惯；
测试语言分工明确：单元测试必须用 Go 编写（与业务代码同目录、以_test.go结尾），端到端/用户故事测试则应使用 TypeScript 编写，并复用前端目录下的 client 库。仓库后端已存在大量 Go 测试可作模板，例如 backend/internal/data/repo/repo_entities_test.go、backend/app/api/middleware_ratelimit_test.go。

运行后端测试与覆盖率：

task go:test # go test ./...，可透传 gotestsum 参数 task go:coverage # -race 竞态检测 + 覆盖率报告（app/internal/pkgs 三个包）

五、开发注意事项：前端

5.1 启动前端开发服务器

task ui:dev

对应命令为pnpm dev --no-fork（Taskfile.yml 的ui:dev）。前端是 Vue 3 + Nuxt 应用，使用 Tailwind 与 shadcn-vue 组件体系，这一技术栈在 frontend/package.json 的依赖中可得到印证（nuxt@4.4.7、vue@3.5.20、tailwindcss@3.4.19、shadcn-nuxt@2.2.0）。

5.2 自动化测试与已知注意点

前端测试使用Vitest，监听模式运行：

task ui:watch # pnpm run test:watch

相关脚本定义在 frontend/package.json：test:watch以监听模式运行，test:ci以--no-file-parallelism串行方式跑完整套件（用于 CI）。

CONTRIBUTING.md 特别提醒一个实测经验：前端测试依赖 API 服务器在运行，且某些场景下首次运行会因竞态条件失败——此时不要慌，直接重跑一次通常即可通过。这与 Taskfile.yml 中test:ci先编译并后台启动backend/api、sleep 15再跑测试的设计互为印证。

前端其他质量门禁：

task ui:check # pnpm run typecheck —— Nuxt 类型检查 task ui:fix # pnpm run lint:fix —— Prettier + ESLint 自动修复

六、提交 PR 前的完整自检：task pr

Taskfile 专门封装了「PR 提交前必须全部通过」的任务链（Taskfile.yml 的pr任务）：

task pr

它依次执行：

task: generate—— 重新生成 ent 数据库代码、Swagger 文档、TypeScript 类型；
task: go:all——go mod tidy+golangci-lint run ./...（lint 规则集见 backend/.golangci.yml，启用了 errcheck、staticcheck、revive、gocritic 等 20+ 个 linter）+ 全量 Go 测试；
task: ui:check—— 前端类型检查；
task: ui:fix—— 前端 Prettier/ESLint 修复；
task: test:ci—— 构建后端、启动服务、串行跑前端 Vitest 套件。

本地把task pr完整跑绿，基本等同于预演了一遍 .github/workflows/pull-requests.yaml 中 PR CI 的检查内容（后端单测、前端测试、Playwright e2e），可以大幅减少提交后才发现 CI 失败的返工。

七、发布流程：打标签即触发全自动流水线

CONTRIBUTING.md 明确指出发布机制：在 GitHub 上创建一个形如vX.X.X的新标签，即可触发一次新的 Release 创建。结合仓库 CI 配置，可以还原这条完整流水线（文档原文：Test -> Goreleaser -> Publish Release -> Trigger Docker Builds -> Deploy Docs + Fly.io Demo）：

Test：PR 合并到main后，CI 的测试工作流已完成验证；
Goreleaser：推送v*.*.*标签触发 .github/workflows/binaries-publish.yaml。该流水线先构建前端静态产物，随后用 GoReleaser 按amd64、arm64、riscv64三种架构矩阵并行构建 Linux/Windows/Darwin/FreeBSD 平台二进制（构建配置见 backend/.goreleaser.yaml 与各架构专属配置）；
Publish Release：合并各架构 checksum，用gh release upload上传二进制压缩包、checksums.txt与 SBOM，并通过 SLSA 生成与校验软件供应链证明（见 binaries-publish 中的binary-provenance与verification-with-slsa-verifier两个 job）；
Trigger Docker Builds：标签推送同时触发 Docker 镜像构建与发布（.github/workflows/docker-publish.yaml、docker-publish-hardened.yaml、docker-publish-rootless.yaml 三个变体，对应仓库根目录的三个 Dockerfile）；
Deploy Docs + Fly.io Demo：文档站点与 Fly.io 演示环境随发布自动部署。

八、仓库速查索引

贡献规范原文：CONTRIBUTING.md
开发任务封装（依赖安装、代码生成、运行、测试、PR 自检、CI 模拟）：Taskfile.yml
devcontainer 配置（Go 1.26、pnpm、task 自动安装）：.devcontainer/devcontainer.json
后端模块与依赖版本：backend/go.mod
后端 lint 规则集：backend/.golangci.yml
前端依赖与脚本（Nuxt 4、Vitest、pnpm 10）：frontend/package.json
PR CI 工作流：.github/workflows/pull-requests.yaml
发布二进制流水线：.github/workflows/binaries-publish.yaml
发布产物文档（OpenAPI/Swagger）：docs/public/api/
后端 Go 测试示例：backend/internal/data/repo/repo_entities_test.go
前端 e2e 测试示例：frontend/test/e2e/login.browser.spec.ts

结语

从main分支出特性分支、补测试、同步文档、跑通task pr、提交 PR，到维护者打vX.X.X标签触发 Goreleaser/Docker/文档全自动发布，HomeBox 的贡献链路完整且自动化程度高。对贡献者而言，最省力的路径是：优先使用 devcontainer + Taskfile，开发阶段记住「后端改完要手动重启」，提交前跑一遍task pr。掌握这套工作流后，你便可以顺畅地参与这个家庭库存管理系统的迭代。