# 手動安裝

> 使用 Docker Compose 手動部署 PentAGI — 建立工作目錄、填寫 .env 檔案、新增 LLM provider 並啟動堆疊。

當您需要完全掌控設定，或無法執行互動式安裝程式時，請採用手動安裝方式。

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

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

## [2. 下載環境檔案](https://pentagi.com/zh-tw/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-tw/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-tw/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-tw/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-tw/docs/configuration/llm-providers/)。[Search engines](https://pentagi.com/zh-tw/docs/glossary/#search-engine) 為選用項目；DuckDuckGo 與 Sploitus 無需金鑰：

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

## [4. 啟動堆疊](https://pentagi.com/zh-tw/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` 登入並變更密碼。

網頁介面與其他服務皆綁定在 localhost，但每個 [flow](https://pentagi.com/zh-tw/docs/glossary/#flow) 的 [sandbox](https://pentagi.com/zh-tw/docs/glossary/#sandbox) 會在 Docker 主機的每個介面上發布兩個回呼埠，預設範圍為 `28000`–`29999`，且 ufw 不會過濾這些埠。若其他使用者可以存取該主機，請先限制該範圍 — 請參閱 [網路暴露](https://pentagi.com/zh-tw/docs/configuration/security/#network-exposure)。若要稍後更新安裝，請遵循 [升級](https://pentagi.com/zh-tw/docs/deployment/upgrade/)。

## [選用堆疊](https://pentagi.com/zh-tw/docs/getting-started/manual-installation/#optional-stacks)

每個選用服務皆以獨立的 Compose 檔案提供，您可將其疊加於基礎堆疊之上：

| 堆疊                                                 | Compose 檔案                                                                                         | 新增功能                                              |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| LLM 可觀測性                                           | [`docker-compose-langfuse.yml`](https://pentagi.com/zh-tw/docs/configuration/observability/#langfuse)                       | Langfuse 搭配 ClickHouse、Redis 與 MinIO              |
| [Knowledge graph](https://pentagi.com/zh-tw/docs/glossary/#knowledge-graph) | [`docker-compose-graphiti.yml`](https://pentagi.com/zh-tw/docs/concepts/memory/#knowledge-graph-optional)                   | Graphiti 與 Neo4j                                  |
| 系統可觀測性                                             | [`docker-compose-observability.yml`](https://pentagi.com/zh-tw/docs/configuration/observability/#grafana-and-opentelemetry) | Grafana、OpenTelemetry、VictoriaMetrics、Jaeger、Loki |

> [!WARNING]
> 在生產環境或任何執行不受信任程式碼的環境中，請將 [tool](https://pentagi.com/zh-tw/docs/glossary/#tool) 容器隔離於專屬的 [worker node](https://pentagi.com/zh-tw/docs/deployment/worker-node/) 上。