快速入门

从一台空主机到您第一个创建并获取的流程，只需几分钟。

Markdown

本页会在您的环境中同时运行 Human Plugin 和一个临时的 PostgreSQL 容器，以便快速上手。如需正式部署，请参阅 Docker Compose 或 Kubernetes。

前提条件

• Docker 24 或更高版本，运行于 linux/amd64 或 linux/arm64（macOS 上的 Docker Desktop 同样可用）。
• 来自 Unico 的镜像仓库凭据和访问密钥。请参阅前提条件与访问权限。

1. 获取镜像

使用您的用户名和令牌登录 Unico 的镜像仓库，每台主机只需登录一次：

echo "<token>" | docker login pkg.unico.run -u <username> --password-stdin

docker pull pkg.unico.run/human-plugin-api:latest

2. 启动 PostgreSQL 和 Human Plugin

docker network create human-plugin

docker run -d --name human-plugin-db --network human-plugin \
  -e POSTGRES_USER=human_plugin -e POSTGRES_PASSWORD=human_plugin -e POSTGRES_DB=human_plugin \
  postgres:16

在 shell 中设置您的访问密钥，然后启动 Human Plugin：

export HUMAN_API_ACCESS_KEY='<your access key>'

docker run -d --name human-plugin --network human-plugin --stop-timeout 60 -p 127.0.0.1:8080:8080 \
  -e HUMAN_API_ACCESS_KEY \
  -e POSTGRES_ADDRESS_HOST=human-plugin-db \
  -e POSTGRES_USER=human_plugin \
  -e POSTGRES_PASSWORD=human_plugin \
  -e POSTGRES_SSL_MODE=disable \
  pkg.unico.run/human-plugin-api:latest

POSTGRES_SSL_MODE=disable 仅适用于这个本地数据库。其他任何数据库都请保持默认值 require。请参阅配置。

检查 Human Plugin 是否已就绪：

curl --fail http://127.0.0.1:8080/health/ready

您应该会看到 {"status":"ok"}。如果命令失败，docker logs human-plugin 会说明原因。

3. 创建流程

选择其中一种流程。clientId、correlationId 和 credential 在每种流程中都是相同的。

humantoken（由用户采集）

用户在采集 Journey 中拍摄自拍照。响应中带有指向该 Journey 的 link。

curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "callbackUri": "https://example.com/callback"
  }'

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_CREATED",
  "token": "<SDK token>",
  "link": "https://…"
}

在手机上打开 link 并拍摄自拍照。token 和 link 仅在此处返回：Human Plugin 不会存储它们。

api+humantoken（由您发送自拍照）

您的后端已经有自拍照，并通过 imageBase64 发送。响应即为最终结果，包含 Human Token 和智能洞察。

curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-002",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

{
  "id": "5d1f7c2e-1b8a-4e0f-9a4b-2f6c3d9e8a71",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 1,
      "transactionsCount": 1,
      "firstSeen": "2026-11-03",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id 是 Human Plugin 为该流程生成的 id。请保存好它：这是之后读取该流程的唯一方式。
• correlationId 是您自己的引用，必须唯一。重复使用会返回 409 CORRELATION_ID_ALREADY_USED。
• credential 是用户的证件。没有证件时发送 null。可用的类型见属性目录。
• data.humanToken 表示这个人是谁，data.ndocs 是该用户的智能洞察：此人在您这里做过什么。请参阅智能洞察。
• 使用 Journey 时，已完成的流程还会包含 data.liveness：采集来自真人时为 live，否则为 not_live。请参阅 data 中的结果。

4. 读取结果

将 id 替换为您响应中的 id：

curl -s http://127.0.0.1:8080/v1/processes/b063041c-7529-4e70-a2b4-c71c00f19801

在用户完成采集之前，Journey 会一直保持 PROCESS_STATE_CREATED。之后再次读取：响应会变为 PROCESS_STATE_FINISHED，并包含 data.humanToken、data.liveness 和 data.ndocs。在信任结果之前，请确认 data.liveness.value 为 live。

5. 清理

docker rm -f human-plugin human-plugin-db && docker network rm human-plugin

下一步

• 流程：该使用哪种流程，以及每种流程需要什么。
• 创建流程：所有字段和规则。
• 集成您的后端：需要存储什么，以及如何处理失败。
• Human Token Journey：采集 Journey。
• 适用于 Web、Android、iOS、Ionic、React Native 和 Flutter 的采集指南：采集的前端部分。
• 在您的基础设施中运行 Human Plugin