Getting Started — 环境准备与本地运行

本页是根 README.md 的「快速开始」拆分页，覆盖从零到跑通后端的完整步骤、数据库引导、鉴权配置与常见排障。 顶层任务速记见根 Makefile；权威环境说明见 AGENTS.md §Cursor Cloud specific instructions。

---

一、前置依赖

工具	版本	说明
Python	>=3.14.5,<3.15	禁用 3.14.0–3.14.4（分代 GC 隐患）；uv python install 3.14
uv	最新	唯一后端包管理器：curl -LsSf https://astral.sh/uv/install.sh | sh
Node.js	24.x LTS	前端 workspace
pnpm	10.x	前端包管理器
Docker + Compose	最新	本地依赖（PostgreSQL / Valkey 等）

---

二、一次性安装

# 仓库根目录
export PATH="$HOME/.local/bin:$PATH"

# 后端依赖
make install          # = cd backend && uv sync

# 前端依赖（web-builder / web-ops / web-starter / miniprogram / shared / ui / web-saas-template）
cd frontend && pnpm install && pnpm run build:libs && cd ..   # build:libs 先建 @agent-hub/shared + @agent-hub/ui，web 应用依赖两者

---

三、启动本地依赖

推荐使用 Docker Compose 一键拉起 PostgreSQL（pgvector）、Valkey 等：

make compose-up       # = docker compose -f deploy/compose/docker-compose.yml up -d --wait
make compose-down     # 停止

在 Cursor Cloud VM 上，基底镜像已原生烤入 PostgreSQL 17 + pgvector 与 Redis，无需 Docker；详见 AGENTS.md 的自动 bootstrap 说明。若在普通机器上 docker 需要 sudo，则使用 sudo docker ...。

数据库连接默认暴露在 127.0.0.1:5432，缓存在 127.0.0.1:6379。

---

四、数据库引导（集成测试 / 参考 E2E 必需）

容器随 deploy/compose/initdb/ 卷启动时会自动执行初始化 SQL。若容器未挂载该卷，手动执行一次：

docker exec -i postgres psql -U agenthub -d agenthub < deploy/compose/initdb/001_extensions.sql
docker exec -i postgres psql -U agenthub -d agenthub < deploy/compose/initdb/002_agenthub_nosuper.sql
cd backend && uv run alembic upgrade head

• 001_extensions.sql：启用 pgvector 等扩展。
• 002_agenthub_nosuper.sql：创建 RLS 测试所需的 agenthub_nosuper 角色（超级用户 agenthub 会绕过 FORCE ROW LEVEL SECURITY）。
• alembic upgrade head：迁移到最新 head。

---

五、运行测试与开发服务器

# 全量测试
make test                 # = cd backend && uv run pytest

# 仅跑某一层
cd backend && uv run pytest tests/unit
cd backend && uv run pytest tests/integration

# 开发服务器
make dev                  # → http://127.0.0.1:8000/docs
curl http://127.0.0.1:8000/health/live   # → {"status":"alive"}

---

六、测试 / 开发鉴权（TM-H01）

后端存在两条鉴权路径，本地测试时需区分：

• FastAPI 依赖 (get_current_user)：当 AUTH_JWT_ALGORITHMS=HS256 时默认走 HS256（本地 / 回归）。
• HTTP 中间件 (AuthMiddleware)：经 Keycloak JWKS 校验 RS256，会拒绝 HS256 测试 JWT。

针对仅依赖注入的本地 pytest，导出：

export AUTH_JWT_ALGORITHMS=HS256
export JWT_SECRET_KEY=agenthub-tm0.3-test-secret-key

针对会命中中间件的真实 HTTP 路径，优先使用 RS256 / Keycloak，或 mock validator。

---

七、常见坑

1. 分支基线：开发基线是 ai_develop，不是 main（main 落后开发线）。
2. redis 依赖：redis 必须留在运行时依赖（非 dev group），否则生产 uv sync --no-dev 会漏装，导致运行时 ImportError 与 /health/ready 503。
3. make verify vs make test：make verify 只做脚手架 / 版本自检；完整后端门禁是 make lint / make typecheck / make importlinter / make test。
4. 前端：frontend/packages/* 已全部实现（非空壳）。任何 web 应用的 type-check / build / vitest 之前，必须先 cd frontend && pnpm run build:libs（构建 @agent-hub/shared + @agent-hub/ui）；单个 Vite 应用用 VITE_USE_MOCKS=true pnpm --filter @agent-hub/web-builder dev 可脱离后端离线运行（mock 模式直接进入已登录控制台，不跳 Keycloak）。workspace 钉 engines.node >=24 <25，Node 22 下引擎告警非致命但非预期工具链。会话 Agent 的无 Keycloak 冒烟（X-AgentHub-Api-Key 直连 /api/v1/app/conversations*）见 docs/guides/saas-integration-cookbook.md。
5. 重型集成 / 部署级测试：优先推到持久的 ECS-B 测试机（走 scripts/deploy-from-cloud-agent.sh → verify-testbed.sh → logs-testbed.sh），VM 内本地 PG/Valkey 仅用于单测与 Alembic 自检。

---

八、相关页

• 架构总览 → architecture.md
• 仓库结构 → project-structure.md
• 开发流程与分支约束 → development.md
• 基于 AgentHub 构建 SaaS（对外指南入口）→ docs/guides/README.md