# 手动安装

> 使用 Docker Compose 手动部署 PentAGI — 创建工作目录，填写 .env 文件，添加 LLM provider 并启动堆栈。

当您希望完全控制配置或无法运行交互式安装程序时，请使用手动方式。

## [1. 创建工作目录](https://pentagi.com/zh-cn/docs/getting-started/manual-installation/#1-create-a-working-directory)

```bash
mkdir -p ~/pentagi && cd ~/pentagi
```

## [2. 下载环境文件](https://pentagi.com/zh-cn/docs/getting-started/manual-installation/#2-download-the-environment-file)

```bash
test -f .env || curl -fo .env.new https://raw.githubusercontent.com/vxcontrol/pentagi/main/.env.example
test -f .env.new && openssl rand -hex 32 | xargs -I VALUE sed -E -i.bak 's/^COOKIE_SIGNING_SALT=salt( .*)?$/COOKIE_SIGNING_SALT=VALUE/' .env.new
test -f .env.new && openssl rand -hex 16 | xargs -I VALUE sed -E -i.bak 's/^PENTAGI_POSTGRES_PASSWORD=postgres( .*)?$/PENTAGI_POSTGRES_PASSWORD=VALUE/' .env.new
test -f .env || mv .env.new .env
```

Compose 文件会挂载三个 [provider](https://pentagi.com/zh-cn/docs/glossary/#provider) 配置文件，因此请创建它们——空文件即可：

```bash
touch example.custom.provider.yml example.ollama.provider.yml example.bedrock.provider.yml
```

如果您计划使用自定义的 OpenAI 兼容端点或 Ollama，请获取示例配置而非空文件，并将 `.env` 中的 `LLM_SERVER_CONFIG_PATH` 或 `OLLAMA_SERVER_CONFIG_PATH` 指向 `/opt/pentagi/conf/custom.provider.yml` 或 `/opt/pentagi/conf/ollama.provider.yml`。该自定义示例命名了 OpenAI 模型，其中包括 `o3-mini`（OpenAI 将于 2026 年 10 月 23 日停用该模型）——请将每个 [agent](https://pentagi.com/zh-cn/docs/glossary/#agent) 的 `model` 设置为您的端点所支持的模型：

```bash
curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/main/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/main/examples/configs/ollama-llama318b.provider.yml
```

## [3. 添加至少一个 LLM provider](https://pentagi.com/zh-cn/docs/getting-started/manual-installation/#3-add-at-least-one-llm-provider)

编辑 `.env` 并设置至少一个 provider 的密钥：

```bash
OPEN_AI_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
```

其他 providers——AWS Bedrock、Ollama、DeepSeek、GLM、Kimi、Qwen、MiniMax、Mistral、xAI 以及自定义端点——在 [LLM providers](https://pentagi.com/zh-cn/docs/configuration/llm-providers/) 中有详细说明。[Search engines](https://pentagi.com/zh-cn/docs/glossary/#search-engine) 为可选项；DuckDuckGo 和 Sploitus 无需密钥：

```bash
DUCKDUCKGO_ENABLED=true
SPLOITUS_ENABLED=true
TAVILY_API_KEY=your_tavily_key
```

## [4. 启动服务栈](https://pentagi.com/zh-cn/docs/getting-started/manual-installation/#4-start-the-stack)

```bash
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose.yml
test -f .env && docker compose up -d
```

Web UI 的访问地址为 `https://localhost:8443`。请使用 `admin@pentagi.com` / `admin` 登录并更改密码。

Web UI 和其他服务均绑定到 localhost，但每个 [flow](https://pentagi.com/zh-cn/docs/glossary/#flow) 的 [sandbox](https://pentagi.com/zh-cn/docs/glossary/#sandbox) 会在 Docker 主机的所有网络接口上发布两个回调端口，默认范围为 `28000`–`29999`，且 ufw 不会过滤这些端口。如果其他用户可以访问该主机，请首先限制该端口范围——请参阅[网络暴露](https://pentagi.com/zh-cn/docs/configuration/security/#network-exposure)。如需稍后更新安装，请遵循[升级](https://pentagi.com/zh-cn/docs/deployment/upgrade/)。

## [可选服务栈](https://pentagi.com/zh-cn/docs/getting-started/manual-installation/#optional-stacks)

每个可选服务都作为独立的 Compose 文件提供，您可以将其叠加在基础服务之上：

| 服务栈                                                | Compose 文件                                                                                         | 新增内容                                              |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| LLM 可观测性                                           | [`docker-compose-langfuse.yml`](https://pentagi.com/zh-cn/docs/configuration/observability/#langfuse)                       | Langfuse 及 ClickHouse、Redis 和 MinIO               |
| [Knowledge graph](https://pentagi.com/zh-cn/docs/glossary/#knowledge-graph) | [`docker-compose-graphiti.yml`](https://pentagi.com/zh-cn/docs/concepts/memory/#knowledge-graph-optional)                   | Graphiti 和 Neo4j                                  |
| 系统可观测性                                             | [`docker-compose-observability.yml`](https://pentagi.com/zh-cn/docs/configuration/observability/#grafana-and-opentelemetry) | Grafana、OpenTelemetry、VictoriaMetrics、Jaeger、Loki |

> [!WARNING]
> 对于生产环境及任何运行不受信任代码的环境，请在专用的 [worker node](https://pentagi.com/zh-cn/docs/deployment/worker-node/) 上隔离 [tool](https://pentagi.com/zh-cn/docs/glossary/#tool) 容器。