---
title: 快速入门
description: 使用 Docker 运行 Human Plugin 和 PostgreSQL 数据库，创建 Human Token 流程，并用 curl 读取结果。
canonical: https://developer.unico.io/zh-CN/human-plugin/get-started/quickstart
locale: zh-CN
generated_by: markdown-export
---

# 快速入门

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

本页会在您的环境中同时运行 Human Plugin 和一个临时的 PostgreSQL 容器，以便快速上手。如需正式部署，请参阅 [Docker Compose](/zh-CN/human-plugin/self-hosting/docker-compose) 或 [Kubernetes](/zh-CN/human-plugin/self-hosting/kubernetes)。

## 前提条件

- Docker 24 或更高版本，运行于 `linux/amd64` 或 `linux/arm64`（macOS 上的 Docker Desktop 同样可用）。
- 来自 Unico 的镜像仓库凭据和访问密钥。请参阅[前提条件与访问权限](/zh-CN/human-plugin/get-started/prerequisites)。

## 1. 获取镜像

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

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

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

## 2. 启动 PostgreSQL 和 Human Plugin

```bash
docker network create human-plugin
```

```bash
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：

```bash
export HUMAN_API_ACCESS_KEY='<your access key>'
```

```bash
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`。请参阅[配置](/zh-CN/human-plugin/self-hosting/configuration)。

检查 Human Plugin 是否已就绪：

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

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

<a id="3-create-a-process"></a>

## 3. 创建流程

选择其中一种[流程](/zh-CN/human-plugin/api-reference/create-process#flows)。`clientId`、`correlationId` 和 `credential` 在每种流程中都是相同的。

### humantoken（由用户采集）

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

```bash
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"
  }'
```

```json
{
  "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 和智能洞察。

```bash
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>"
  }'
```

```json
{
  "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`。可用的类型见[属性目录](/zh-CN/human-plugin/additional-resources/attribute-catalog)。
- `data.humanToken` 表示这个人是谁，`data.ndocs` 是该用户的智能洞察：此人在您这里做过什么。请参阅[智能洞察](/zh-CN/human-plugin/get-started/intelligence)。
- 使用 Journey 时，已完成的流程还会包含 `data.liveness`：采集来自真人时为 `live`，否则为 `not_live`。请参阅 [`data` 中的结果](/zh-CN/human-plugin/api-reference/create-process#result)。

## 4. 读取结果

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

```bash
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. 清理

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

## 下一步

- [流程](/zh-CN/human-plugin/api-reference/create-process#flows)：该使用哪种流程，以及每种流程需要什么。
- [创建流程](/zh-CN/human-plugin/api-reference/create-process)：所有字段和规则。
- [集成您的后端](/zh-CN/human-plugin/integrations/backend)：需要存储什么，以及如何处理失败。
- [Human Token Journey](/zh-CN/human-plugin/integrations/human-token-journey)：采集 Journey。
- 适用于 [Web](/zh-CN/human-plugin/integrations/web)、[Android](/zh-CN/human-plugin/integrations/android)、[iOS](/zh-CN/human-plugin/integrations/ios)、[Ionic](/zh-CN/human-plugin/integrations/ionic)、[React Native](/zh-CN/human-plugin/integrations/react-native) 和 [Flutter](/zh-CN/human-plugin/integrations/flutter) 的采集指南：采集的前端部分。
- [在您的基础设施中运行 Human Plugin](/zh-CN/human-plugin/self-hosting/overview)