> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 本地开发

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

# 本地开发

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

```bash theme={null}
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](/zh/hub/quickstart)。完整流程：

```bash theme={null}
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` 覆盖文件：

```bash theme={null}
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 的（或自备实例）：

```bash theme={null}
cd quickstart && docker compose up -d mysql && cd ..
```

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

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

```bash theme={null}
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
```

按需追加可选变量：

```bash theme={null}
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_*` 变量。各变量的完整说明见 [配置](/zh/hub/configuration)。

**启动前端**：

```bash theme={null}
cd frontend
npm install
npm run dev    # 默认端口 7002；/api 与 /auth 按 vite.config.ts 代理
```

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

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

## 构建产物

<CodeGroup>
  ```bash 前端 theme={null}
  cd frontend && npm run build   # 输出在 frontend/dist
  ```

  ```bash 后端 theme={null}
  go build -o bin/server ./cmd/server   # 自动内嵌前端 dist
  ```
</CodeGroup>

## 测试

前端使用 Vitest + Testing Library + MSW：

```bash theme={null}
cd frontend
npm test          # watch 模式
npm run test:run  # 单次运行
```

后端：

```bash theme={null}
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` 通过。