快速开始

从克隆仓库到第一个 authenticated 请求。技术栈:Next.js 16 + Prisma 6 + PostgreSQL,Node.js 22+,MIT 许可。

Node >= 22 PostgreSQL 16 包管理 npm 10+ 许可 MIT

前置要求

  • 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。请为每个环境使用独立的高熵值,并定期轮换。

环境变量

复制 .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/mcpMCP 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 / passwordDocker Compose 中 PostgreSQL 的覆盖项

本地开发

克隆仓库、安装依赖、推送数据库结构,然后启动开发服务器:

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。

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 按顺序执行:

  1. 启动 PostgreSQL 16 并等待健康检查通过;
  2. 一次性运行 prisma migrate deploy;
  3. migration 成功后启动非 root 的 Next.js 容器(restart: unless-stopped,健康检查指向 /api/ready);
  4. 映射 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。

验证服务

先用公开探针确认进程与数据库,再带 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。

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 相同的值"
      }
    }
  }
}
args 必须使用绝对路径;HUMANAPI_API_KEY 与服务端 API_KEY 保持一致。12 个工具的完整参数见 MCP 工具参考。

生产部署要点

不使用 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、幂等事件与独立支付账本。

下一步

服务跑起来之后,按这些顺序把完整链路走一遍:

  1. GET /api/humans — 按技能与位置检索专家;
  2. POST /api/tasks — 创建任务并查看匹配结果;
  3. POST /api/bookings — 抢占专家并创建预约;
  4. POST /api/bookings/:id/:action — confirm / start / complete 全流程;
  5. POST /api/bookings/:id/reviews — 完成后互评。
遇到问题?先看 状态码与错误 与 限流与安全响应头,再到 GitHub Issues 反馈。