Guide / Setup
快速开始
从克隆仓库到第一个 authenticated 请求。技术栈:Next.js 16 + Prisma 6 + PostgreSQL,Node.js 22+,MIT 许可。
Node >= 22
PostgreSQL 16
包管理 npm 10+
许可 MIT
01 / Prerequisites
前置要求
- Node.js 22 或更高版本(
engines.node >= 22),npm 10+ - PostgreSQL 16,或直接使用 Docker / Docker Compose
- 一个长随机 API Key:
openssl rand -hex 32
API Key 是服务级凭证:所有私有 REST 与 MCP 端点都要求
Authorization: Bearer <API_KEY> 或 x-api-key。请为每个环境使用独立的高熵值,并定期轮换。02 / Environment
环境变量
复制 .env.example 为 .env 后按需修改。必需项只有两个:DATABASE_URL 与 API_KEY。
| 变量 | 必需 | 默认 | 说明 |
|---|---|---|---|
DATABASE_URL | 是 | — | PostgreSQL 连接串 |
API_KEY | 是 | — | 服务级凭证,私有端点校验用 |
APP_URL | 否 | http://localhost:3000 | 公开源,用于返回 baseUrl |
NODE_ENV | 否 | development | 运行环境 |
HUMANAPI_API_URL | 否 | http://localhost:3000/api/mcp | MCP stdio 客户端请求的地址 |
HUMANAPI_API_KEY | 否 | — | MCP 客户端使用的 Key,须与 API_KEY 相同 |
RATE_LIMIT_MAX | 否 | 120 | 窗口内最大请求数(每 API Key) |
RATE_LIMIT_WINDOW_MS | 否 | 60000 | 限流窗口长度(毫秒) |
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD | 否 | humanapi / user / password | Docker Compose 中 PostgreSQL 的覆盖项 |
03 / Local
本地开发
克隆仓库、安装依赖、推送数据库结构,然后启动开发服务器:
bash · local dev
git clone https://github.com/bit-cook/HumanAPI.git
cd HumanAPI
npm ci
cp .env.example .env
# 编辑 .env:设置 API_KEY 与 DATABASE_URL
npx prisma generate
npx prisma migrate dev
npm run dev
# 开发服务器监听 http://localhost:3000
npx prisma migrate dev会创建并应用初始 migration,同时生成 Prisma Client。npm run dev启动 Next.js 开发服务器;接口文档见 REST API 参考。- 修改 Prisma 模型后,重新运行
npx prisma migrate dev生成新的 migration。
04 / Docker
Docker Compose
不想本地装 PostgreSQL 时,用 Compose 一键拉起完整链路:
bash · docker compose
cp .env.example .env
# 编辑 .env:API_KEY 与 HUMANAPI_API_KEY 设为同一个长随机值
docker compose up --build -d
docker compose logs -f migrate app
Compose 按顺序执行:
- 启动 PostgreSQL 16 并等待健康检查通过;
- 一次性运行
prisma migrate deploy; - migration 成功后启动非 root 的 Next.js 容器(
restart: unless-stopped,健康检查指向/api/ready); - 映射
3000:3000,用/api/ready验证数据库就绪。
常用命令:
bash · compose ops
docker compose ps
docker compose logs -f app
curl http://localhost:3000/api/health
curl http://localhost:3000/api/ready
docker compose down
数据库默认值(
humanapi / user / password)为兼容早期 Compose volume 而保留。生产环境必须通过 secret 管理覆盖,并在反向代理处终止 HTTPS。05 / Verify
验证服务
先用公开探针确认进程与数据库,再带 API Key 请求私有端点:
bash · curl
# 公开端点:无需认证
curl http://localhost:3000/api
curl http://localhost:3000/api/health
curl http://localhost:3000/api/ready
# 私有端点:携带 API Key(两种写法等价)
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/humans
curl -H "x-api-key: $API_KEY" "http://localhost:3000/api/humans?ratingMin=4&limit=5"
/api/health返回status: ok表示进程存活;/api/ready返回status: ready表示 PostgreSQL 可连接,失败时为503;- 漏带或写错 Key 会得到
401 Authentication required。
06 / MCP
MCP 客户端
仓库内置 MCP stdio Server。先构建,再按客户端要求配置:
bash · mcp server
npm run mcp:build
HUMANAPI_API_URL='http://localhost:3000/api/mcp' \
HUMANAPI_API_KEY='与服务端 API_KEY 相同' \
node mcp-server/dist/index.js
在 MCP 客户端(如 Claude Desktop、Cursor 等)的配置文件中添加:
json · mcp client config
{
"mcpServers": {
"humanapi": {
"command": "node",
"args": ["/absolute/path/to/HumanAPI/mcp-server/dist/index.js"],
"env": {
"HUMANAPI_API_URL": "http://localhost:3000/api/mcp",
"HUMANAPI_API_KEY": "与 API_KEY 相同的值"
}
}
}
}
07 / Deploy
生产部署要点
不使用 Compose 时的手动部署流程:
bash · manual deploy
npm ci
cp .env.example .env
npx prisma migrate deploy
API_KEY='your-secret' DATABASE_URL='postgresql://user:pass@host:5432/humanapi' npm run build
API_KEY='your-secret' DATABASE_URL='postgresql://user:pass@host:5432/humanapi' npm start
上线前检查清单:
- 使用高熵 API Key 并定期轮换;Key 只存放在服务端环境,不进入浏览器 bundle;
- HTTPS 在反向代理处终止,数据库启用备份与网络隔离;
- 当前限流为单进程内存实现,多副本部署前需替换为共享存储;
- 多租户场景前,先补充最终用户身份、资源级授权与审计;
- 接入真实支付前,实现签名 webhook、幂等事件与独立支付账本。
08 / Next
下一步
服务跑起来之后,按这些顺序把完整链路走一遍:
- GET /api/humans — 按技能与位置检索专家;
- POST /api/tasks — 创建任务并查看匹配结果;
- POST /api/bookings — 抢占专家并创建预约;
- POST /api/bookings/:id/:action — confirm / start / complete 全流程;
- POST /api/bookings/:id/reviews — 完成后互评。