---
title: Docker Compose
description: 使用 Docker Compose 在单台主机上运行 Human Plugin,并连接到您的 PostgreSQL 数据库。
canonical: https://developer.unico.io/zh-CN/human-plugin/self-hosting/docker-compose
locale: zh-CN
generated_by: markdown-export
---

# Docker Compose

在一台主机上运行一个 Human Plugin 容器,并连接到您的 PostgreSQL 数据库。

<a id="prerequisites"></a>

## 前提条件

- Docker Engine 24 或更高版本,以及 Docker Compose v2。
- 一个专供 Human Plugin 使用、且可从该主机访问的 PostgreSQL 数据库。请参阅[前提条件与访问权限](/zh-CN/human-plugin/get-started/prerequisites)。
- 由 Unico 提供的镜像仓库凭据和访问密钥。

<a id="1-log-in-to-the-registry"></a>

## 1. 登录镜像仓库

每台主机只需执行一次。Docker 会将凭据保存在 `~/.docker/config.json` 中。

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

<a id="2-write-the-settings"></a>

## 2. 编写设置

为 Human Plugin 创建一个目录,并创建仅所有者可读的 `.env` 文件:

```bash
mkdir -p /opt/human-plugin && cd /opt/human-plugin
```

```bash title=".env"
HUMAN_API_ACCESS_KEY=<your access key>
POSTGRES_ADDRESS_HOST=<database host>
POSTGRES_USER=human_plugin
POSTGRES_PASSWORD=<database password>
```

```bash
chmod 600 .env
```

仅当您的数据库与[配置](/zh-CN/human-plugin/self-hosting/configuration)中的默认值不同时,才添加 `POSTGRES_ADDRESS_PORT`、`POSTGRES_DATABASE` 或 `POSTGRES_SSL_MODE`。切勿提交 `.env` 文件。

<a id="3-write-composeyaml"></a>

## 3. 编写 `compose.yaml`

```yaml title="compose.yaml"
services:
  human-plugin:
    image: pkg.unico.run/human-plugin-api:latest
    pull_policy: always
    restart: unless-stopped
    stop_grace_period: 60s
    env_file: .env
    ports:
      - "127.0.0.1:8080:8080"
```

- **`ports`:** 仅在 `127.0.0.1` 或私有网络接口上发布,切勿使用 `0.0.0.0`。Human Plugin 自身没有身份验证:请参阅[网络与安全](/zh-CN/human-plugin/self-hosting/networking-and-security)。
- **`stop_grace_period: 60s`:** Human Plugin 在停止时最多会等待 55 秒,以处理正在进行的请求。更短的宽限期可能会中断一次创建操作。
- **`pull_policy: always`:** 每次执行 `up` 都会检查最新镜像,因此您始终运行最新版本。

<a id="4-start"></a>

## 4. 启动

```bash
docker compose up -d
```

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

只有在 `/health/ready` 返回 `200` 之后,才将流量路由到 Human Plugin。然后针对它运行[快速入门](/zh-CN/human-plugin/get-started/quickstart#3-create-a-process)中的创建请求。

<a id="logs-and-status"></a>

## 日志与状态

```bash
docker compose ps
```

```bash
docker compose logs -f human-plugin
```

正常启动会以 `human plugin listening` 这一行结束。完整的启动日志请参阅[健康检查与监控](/zh-CN/human-plugin/self-hosting/health-and-monitoring#logs)。如果容器陷入循环重启,日志会说明原因:请参阅[故障排查](/zh-CN/human-plugin/additional-resources/troubleshooting)。

<a id="update"></a>

## 更新

```bash
docker compose pull && docker compose up -d
```

仅当镜像发生变化时,Compose 才会替换容器。更新后需要检查的内容,请参阅[运维](/zh-CN/human-plugin/self-hosting/operations)。

<a id="stop"></a>

## 停止

```bash
docker compose down
```

您的数据保存在您的 PostgreSQL 数据库中,因此停止或删除容器不会丢失任何数据。