# 安全性

> PentAGI 安裝執行個體的憑證、HTTPS、登入與網路暴露設定。

## [變更預設值](https://pentagi.com/zh-tw/docs/configuration/security/#change-the-defaults)

全新安裝會建立本機管理員 `admin@pentagi.com`，密碼為 `admin`，您必須在首次登入時變更。若遺失密碼，只要該帳戶仍使用 `admin@pentagi.com` 位址，即可透過安裝程式的維護選單重設。

請在首次啟動前於 `.env` 中設定這些值；安裝程式會為您產生 salt 與密碼。PostgreSQL 和 Neo4j 僅在建立資料卷時讀取憑證，因此後續變更將導致連線中斷：

| 變數                                                  | 用途                                                                                       |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `COOKIE_SIGNING_SALT`                               | 簽署工作階段 Cookie 與 API 權杖 — 請設定隨機值                                                          |
| `PENTAGI_POSTGRES_USER`、`PENTAGI_POSTGRES_PASSWORD` | PostgreSQL 憑證                                                                            |
| `NEO4J_PASSWORD`                                    | [Knowledge graph](https://pentagi.com/zh-tw/docs/glossary/#knowledge-graph) 的 Neo4j 密碼；`NEO4J_USER` 必須保持為 `neo4j` |
| `PUBLIC_URL`                                        | 使用者存取的 URL，例如 `https://pentagi.example.com`                                              |

在已運行的安裝環境中，請先於 PostgreSQL 或 Neo4j 內部變更資料庫密碼，然後再於 `.env` 中進行變更。

## [HTTPS](https://pentagi.com/zh-tw/docs/configuration/security/#https)

PentAGI 在連接埠 8443 上提供 HTTPS 服務，並使用自簽憑證。若要使用您自己的憑證，請設定 `SERVER_SSL_CRT` 與 `SERVER_SSL_KEY`，並將檔案掛載於 `docker-compose.yml`。

## [使用者與登入](https://pentagi.com/zh-tw/docs/configuration/security/#users-and-sign-in)

系統未提供註冊表單。管理員需從已登入的瀏覽器工作階段透過 Users API (`/api/v1/users/`) 管理本機使用者（API token 在此會收到 403），並由角色限制每位使用者的存取與變更權限。本機使用者可在 **Settings → Account** 下變更自己的電子郵件與密碼。

若已設定 GitHub 或 Google 登入，當登入所使用的電子郵件經提供者驗證後與現有帳號（包含本機帳號）相符時，系統將以該帳號及其角色進行登入；其他登入則會建立具備預設使用者角色的新帳號。每個安裝作業皆從管理員 `admin@pentagi.com` 開始，因此請在啟用登入功能前，前往 **Settings → Account** 將其移至您控制的位址，並僅在可接受新增帳號的情境下啟用此功能，例如將 Google Workspace 應用程式限定於您的網域內。

GitHub 與 Google 登入可透過 OAuth 使用。請註冊應用程式並將回呼網址設為 `${PUBLIC_URL}/api/v1/auth/login-callback`，然後新增其憑證：

```bash
PUBLIC_URL=https://pentagi.example.com
OAUTH_GITHUB_CLIENT_ID=your_github_client_id
OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
```

## [網路存取範圍](https://pentagi.com/zh-tw/docs/configuration/security/#network-exposure)

預設情況下，PentAGI 網頁介面僅監聽 `127.0.0.1`。若要從其他機器存取：

```bash
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443
PUBLIC_URL=https://192.168.1.100:8443
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443
```

請在 `PUBLIC_URL` 與 `CORS_ORIGINS` 中使用實際位址，切勿使用 `0.0.0.0`。請以 `docker compose up -d --force-recreate` 重新建立容器，並在防火牆中開啟連接埠 8443。

在反向代理後方，請將 `TRUSTED_PROXIES` 設定為代理伺服器的位址或 CIDR，以逗號分隔。否則，每個請求看起來都來自該代理伺服器，導致每位位址的登入限制（五分鐘內 30 次失敗嘗試，隨後鎖定 15 分鐘）由所有使用者共用。

每個 [flow](https://pentagi.com/zh-tw/docs/glossary/#flow) 的 [sandbox](https://pentagi.com/zh-tw/docs/glossary/#sandbox) 容器也會發布兩個埠，用於帶外回呼（例如反向 shell）。這些埠來自從 `DOCKER_PORTS_BASE` 開始的 2000 個埠（預設為 `28000`），並綁定至 `DOCKER_PUBLIC_IP`，此地址也是 [agent](https://pentagi.com/zh-tw/docs/glossary/#agent) 提供給目標用於回呼的地址。

預設情況下 `DOCKER_PUBLIC_IP` 為 `0.0.0.0`：連接埠會監聽 Docker 主機上的所有介面，而 agent 會自行查詢其公開位址。僅在主機擁有該位址且目標能夠連線至該位址時，才將其設定為特定位址；在 NAT 後方時，請維持預設值。Docker 發佈的連接埠會繞過主機上的 ufw 和 firewalld 規則，因此請透過主機前方的防火牆（例如雲端安全性群組）或 Docker 的 `DOCKER-USER` 鏈中的規則來限制範圍。

`PROXY_URL` 會透過代理伺服器路由後端對模型提供者、嵌入提供者、搜尋 API 及更新檢查的呼叫，這有助於將安裝環境與外部網路隔離。自託管端點（例如 Ollama、vLLM 或 SearXNG）也會經過此代理伺服器，因為沒有 `NO_PROXY` 例外設定，所以代理伺服器必須能夠連線至這些端點。flow 的 sandbox 容器（agent 在其中執行命令）、為瀏覽器工具開啟網頁的爬蟲，以及 Graphiti 服務並不會使用此代理伺服器，因此請在網路層級限制它們的出站流量。使用 GitHub 或 Google 登入，以及對捆綁堆疊之外的 Langfuse 或 OpenTelemetry 端點的呼叫，也不會使用此代理伺服器；Docker daemon 則會使用其自身的代理設定來拉取映像檔。

## [更新檢查](https://pentagi.com/zh-tw/docs/configuration/security/#update-check)

伺服器在啟動後兩分鐘內，以及之後每三小時，會向 `update.pentagi.com` 查詢是否有更新的建置版本可用。該請求會攜帶安裝 ID、若已設定則包含授權金鑰、版本與平台，以及安裝環境的摘要資訊：設定的 provider 與登入類型、數個功能開關、使用者、flow、[task](https://pentagi.com/zh-tw/docs/glossary/#task)、容器、提示詞、API token 與 [tool call](https://pentagi.com/zh-tw/docs/glossary/#tool-call) 的數量，以及各 provider type 的 token 與成本總計——不包含任何名稱、地址、提示詞或 flow 內容。`UPDATE_CHECK_INTERVAL=0` 可將其關閉。安裝程式每次啟動時，以及在執行每個動作（例如 Apply Changes、Update、Start 或 Stop）之後，都會傳送已安裝的映像檔與每個 stack 的狀態；當 PentAGI 正在執行時，也會傳送相同的摘要；`UPDATE_CHECK_INTERVAL` 不會影響此行為。

> [!WARNING]
> `pentagi` 容器以 root 身分執行，因為它需透過 Docker socket 管理容器。若要加強隔離性，請在獨立的 [worker node](https://pentagi.com/zh-tw/docs/deployment/worker-node/) 上執行 [tools](https://pentagi.com/zh-tw/docs/glossary/#tool)。