本地开发

准备 Agent Hub 前后端开发环境并运行检查。

​

本地开发

Hub 包含 Go 后端、React 管理界面与 TypeScript CLI。先克隆仓库：

git clone https://github.com/zerone-agents/agent-hub.git
cd agent-hub

​

环境要求

• Go ≥ 1.25
• Node.js ≥ 22
• Docker + Docker Compose

​

启动方式

​

方式一：Docker Compose（推荐）

快速体验优先使用 Docker Compose quickstart。完整流程：

cd quickstart
cp .env.example .env   # 至少设置 AUTH_JWT_SECRET（openssl rand -hex 32）
docker compose up -d   # 默认拉取 zeroneai/agent-hub 镜像

应用监听在 http://localhost:8081/static/，健康检查为 curl http://localhost:8081/health。

要从源码本地构建镜像，叠加 docker-compose.build.yml 覆盖文件：

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

首次启动时会自动：

1. 运行 AutoMigrate 创建全部数据表。
2. 写入 5 个共享 Provider 模板——anthropic-thirdparty / openai-thirdparty（自定义兼容 API 模板，填写 base_url + api_key）/ glm-cn（GLM Coding Plan）/ kimi-cn（Kimi Code）/ bailian（阿里云百炼）——均为共享模板行，不预填任何密钥，各租户首次使用时按 copy-on-write 复制后填写。

默认 builtin 认证模式：首次访问时浏览器会弹出初始化页面创建 admin 账号，无需 Casdoor。

​

方式二：前后端分离（本地开发）

需要热更新和源码调试时使用此方式。仓库根目录没有 compose 文件，MySQL 使用 quickstart 的（或自备实例）：

cd quickstart && docker compose up -d mysql && cd ..

quickstart 的 MySQL 容器默认不向宿主机暴露 3306 端口。本地直连需自行放开端口映射，或另起 MySQL。数据库名默认 agent_hub。

启动后端——默认 builtin 模式的最小环境变量集：

export DATABASE_URL="root:root@tcp(localhost:3306)/agent_hub?charset=utf8mb4&parseTime=True&loc=Local"
export AUTH_JWT_SECRET="$(openssl rand -hex 32)"
export AUTH_MODE=builtin   # 默认值，可省略

go run ./cmd/server

按需追加可选变量：

export PROVIDER_ENCRYPTION_KEY="<64 位十六进制>"            # Provider 密钥加密
export OSS_ENDPOINT="http://localhost:9000"                 # OSS 整体可选，留空即禁用
export OSS_BUCKET="agent-hub" OSS_ACCESS_KEY="minioadmin" OSS_SECRET_KEY="minioadmin" OSS_FORCE_PATH_STYLE="true"
export MULTIRAG_BASE_URL="http://localhost:8000"            # 知识库可选
export MULTIRAG_API_KEY="<multirag 服务 API key>"

如需本地调试 SSO，追加 AUTH_MODE=casdoor 以及 CASDOOR_ENDPOINT / CASDOOR_CLIENT_ID / CASDOOR_CLIENT_SECRET / CASDOOR_CERTIFICATE；正常开发无需任何 CASDOOR_* 变量。各变量的完整说明见 配置。

启动前端：

cd frontend
npm install
npm run dev    # 默认端口 7002；/api 与 /auth 按 vite.config.ts 代理

vite dev server 默认把 /api、/auth 代理到 vite.config.ts 中配置的目标。本地起后端时请把 server.proxy 的 target 改为 http://localhost:8081（按需修改，勿提交）。

开发时跳过登录：在 frontend/.env.local 中设置 VITE_BYPASS_AUTH=true（该文件已被 .gitignore 忽略）。

​

构建产物

前端

cd frontend && npm run build   # 输出在 frontend/dist

​

测试

前端使用 Vitest + Testing Library + MSW：

cd frontend
npm test          # watch 模式
npm run test:run  # 单次运行

后端：

go test ./...

测试位于各包内（internal/handler/*_test.go、internal/application/services/*_test.go 等），新增功能请随代码补充对应测试。

​

开发原则

• 后端修改运行 Go 测试与格式检查。
• 管理界面修改运行对应的 lint、类型检查和测试。
• 数据结构变化必须附带可重复执行的数据库迁移。
• API 变更同步更新 Hub 源仓库的 API 文档。
• 不把本地凭据或 DSN 提交到 Git。

​

团队约定

• Git：Conventional Commits（feat: / fix: / refactor: / chore: / style: / docs:）。
• 错误信息：面向用户的错误用中文，内部错误附英文堆栈。
• 字段命名：数据库字段 snake_case，JSON 字段 camelCase，Go 字段 PascalCase。
• i18n：核心实体同时维护中文（description）与英文（descriptionEn）字段。
• 提交前：gofmt -l . 无输出、go vet 通过、cd frontend && npm run test:run 通过。