企业官网建设流程全解析

PentAGI 安装与配置实战指南：从环境变量到 LLM / Embedding / 搜索提供商验证

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi

本篇指南是 PentAGI（Penetration Testing Artificial General Intelligence，自动化渗透测试系统）"安装完成"与"正式使用"之间的桥梁：它按顺序带你完成首次部署全流程——选择安装方式、设置核心服务端变量、配置并通过ctester/etester验证至少一个 LLM 提供商与 Embedding 提供商、按需接入搜索与可观测性，最后启动整个栈并完成首次登录。读完本文，你将掌握一套可复现、可验证的 PentAGI 上线操作清单，并能读懂.env中每个关键变量的作用与底层实现。本文以仓库内 安装与配置指南 为主体，结合 .env.example、ctester、etester 等源码补充实现细节。

开始之前：前置条件

在动手之前，请确认运行环境满足以下最低要求（与仓库 README.md 中的 System Requirements 一致）：

• Docker 与 Docker Compose（或 Podman，rootless 模式需按 README 的 Podman 章节调整 scraper 端口）；
• 2+ vCPU、4+ GB RAM、20+ GB 可用磁盘；
• 可访问外网：用于拉取镜像以及连接 LLM 提供商；
• 至少一个可完成认证的 LLM 提供商：OpenAI、Anthropic、Gemini、AWS Bedrock，或本地 / Ollama / OpenAI 兼容后端。PentAGI 没有 LLM 提供商就无法运行（README 明确要求 "You have to set at least one Language Model provider ... to use PentAGI"）；
• 决定安装方式：交互式安装器（推荐）或手动 Docker Compose 部署。

提示：交互式安装器可以带你完成下文步骤 2–6 的大部分操作，本文依然可以作为核对清单使用。

第一步：选择安装方式

方式 A：交互式安装器（推荐）

安装器是一个终端 UI 程序，执行系统检查、生成合理的.env、协助配置 LLM 与搜索提供商、加固凭据并自动启动整个栈。其实现位于 backend/cmd/installer，涵盖 checker（系统检查）、hardening（凭据加固）、processor（compose 处理）等模块。

安装器的典型执行流程（对应 README.md 的 "Using Installer" 章节）：

mkdir -p pentagi && cd pentagi wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip unzip installer.zip ./installer

安装器通过/var/run/docker.sock与 Docker API 交互，需要相应权限：

• 生产环境推荐：sudo ./installer；
• 开发环境：将用户加入docker组（sudo usermod -aG docker $USER后重新登录或执行newgrp docker）。注意：加入docker组等同于授予 root 级权限，仅在受控环境使用。

安装器会依次完成：系统检查（Docker、网络、资源）→ 生成.env→ 配置 LLM 提供商 → 配置搜索引擎 → 安全加固与 SSL → 通过 docker-compose 启动。

方式 B：手动 Docker Compose 部署

创建工作目录并把.env.example复制为.env，填入密钥后启动栈。完整序列（含示例 provider 配置文件和docker compose up -d命令）见 README.md 的 "Manual Installation" 章节。仓库根目录的 .env.example 就是可复制的变量模板，示例 provider 配置存放在 examples/configs（例如 custom-openai.provider.yml、ollama-llama318b.provider.yml）。

第二步：设置核心服务端变量

无论采用哪种方式，在把实例暴露到 localhost 之外前，请务必在.env中确认以下变量（对应.env.example的 "PentAGI security settings" 区块）：

外部访问场景下，修改后需重建容器使配置生效（见 README.md "Accessing PentAGI from External Networks" 章节）：

docker compose down docker compose up -d --force-recreate

随后用docker ps | grep pentagi验证端口绑定为0.0.0.0:8443->8443/tcp（若仍显示127.0.0.1，需直接在 docker-compose.yml 中把ports改为"0.0.0.0:8443:8443"后重建），并在防火墙上放行 8443 端口（UFW：sudo ufw allow 8443/tcp；firewalld：sudo firewall-cmd --permanent --add-port=8443/tcp后 reload）。通过 IP 访问时会遇到自签名证书告警，属预期现象。

第三步：配置并测试 LLM 提供商

在.env中为至少一个提供商设置凭据。.env.example中完整定义了以下提供商的变量（每个提供商还可在 examples/configs 找到带注释的示例配置文件）：

AWS Bedrock 支持三种认证方式（在 ctester 源码 的createProvider中有对应校验）：BEDROCK_DEFAULT_AUTH=true（AWS SDK 默认凭据链，推荐 EC2/ECS 场景）、BEDROCK_BEARER_TOKEN（Bearer Token）、或BEDROCK_ACCESS_KEY_ID+BEDROCK_SECRET_ACCESS_KEY（静态凭据），三者至少配置其一。

用 ctester 验证提供商

在启动完整流程之前，先确认提供商能正确应答并支持 PentAGI 所需的 Agent 行为，运行ctester（Provider Configuration Tester）：

# 本地 Go 环境（在 backend 目录内运行） go run ./cmd/ctester -verbose # 或在运行中的容器内 docker exec -it pentagi /opt/pentagi/bin/ctester -verbose

ctester的可选参数（来自 backend/cmd/ctester/main.go）远不止-verbose：

ctester覆盖 13 类 Agent 的测试（simple、simple_json、primary_agent、assistant、generator、refiner、adviser、reflector、searcher、enricher、coder、installer、pentester），并区分 Basic / Advanced / Capability 测试与成功率、平均延迟统计（见 backend/cmd/ctester/models.go）。若使用 custom、llama.cpp、vLLM、SGLang 后端时报告 tool-call / function-call 问题，通常指向后端本身的 tool-call 解析器而非 PentAGI。完整用法与按 Agent 测试的说明见 README.md 的 "Testing LLM Agents" 章节。

第四步：配置并测试 Embedding 提供商

PentAGI 使用 Embedding 支撑语义搜索、知识存储与记忆系统。相关变量（来自.env.example的 "Embedding" 区块与 config.go 的默认值）：

从 embedder.go 的源码可以确认回退逻辑：当EMBEDDING_PROVIDER=openai且EMBEDDING_URL/EMBEDDING_KEY为空时，客户端自动改用OPEN_AI_SERVER_URL与OPEN_AI_KEY；ollama提供商则使用EMBEDDING_URL作为服务器地址且不支持 Key 认证。

用 etester 验证 Embedding

# 本地 Go 环境 go run ./cmd/etester test -verbose # 运行中的容器 docker exec -it pentagi /opt/pentagi/bin/etester test -verbose

etester是一个子命令式工具（见 backend/cmd/etester/main.go），支持：

etester还遵循TENANT_ID租户模式：启动时会先EnsureTenantSchema并校验search_path，与主服务保持一致（见 etester/main.go 的初始化逻辑）。如果之后更换 Embedding 提供商或模型，需先flush再reindex知识库，完整命令集见 README.md 的 "Embedding Configuration and Testing" 章节。

第五步（可选）：配置搜索提供商

搜索提供商能提升研究质量，但不是必选项。PentAGI 支持以下引擎，对应变量均在.env.example中有定义：

最后一个引擎是web_search工具的免费回退方案：它抓取页面并摘要，替代付费分析 API；需启用开关并配合 scraper 与至少一个链接引擎使用（该引擎在 ftester 的 worker 参数解析 中以internal函数暴露，供调试）。搜索工具的注册与执行逻辑可进一步查看 backend/pkg/tools/search.go 与 backend/pkg/tools/searchers 目录。

第六步（可选）：启用 Graphiti、Langfuse 与可观测性

这三个都是独立可选栈，通过额外的 compose 文件拉起：

顺序要求：必须先运行基础 docker-compose.yml 创建共享 Docker 网络（pentagi-network、observability-network、langfuse-network），再拉起可选栈；否则会报网络不存在的错误。可选栈的具体编排可参考 docker-compose-graphiti.yml、docker-compose-langfuse.yml、docker-compose-observability.yml 及 observability 目录下的配置。

第七步：启动并验证

1. 启动整个栈：docker compose up -d；
2. 观察日志直至后端就绪：docker compose logs -f pentagi；
3. 若修改过任何提供商配置，重新运行ctester与etester；如需对单个 Agent 函数与工具做更深检查，使用ftester（见 README.md 的 "Function Testing with ftester" 章节）；
4. 打开https://localhost:8443（或你的PUBLIC_URL），使用默认账号admin@pentagi.com/admin登录，并立即修改默认密码。

关于登录后的配置边界：Web 控制台的Settings页面管理 Providers（创建、编辑、测试用户定义的 provider 配置，控制各 Agent 的模型选择与运行参数）、Prompts（系统/人类/工具提示词模板）与 PentAGI API tokens；而 LLM 与搜索凭据、Langfuse、Graphiti、MCP 仍属于服务端配置（环境变量 / compose 文件 / 挂载的配置文件），具体划分见 README.md 的 "Current Web Settings Coverage" 与 "Still Server-Managed" 章节。

多用户场景下，PentAGI 不开放自助注册：新实例只有默认本地管理员账号，管理员可通过 Users REST API（/api/v1/users/）管理本地用户，OpenAPI UI 位于https://localhost:8443/api/v1/swagger/index.html。

首次运行配置检查清单

• Docker/Podman、CPU、内存与磁盘满足最低要求
• 已选定安装方式（安装器或手动 Compose）
• PUBLIC_URL与CORS_ORIGINS设置为真实主机名/IP（不是0.0.0.0）
• COOKIE_SIGNING_SALT与数据库密码已从默认值改掉
• 至少一个 LLM 提供商已配置并通过ctester
• Embedding 提供商已配置并通过etester
• 搜索提供商已配置（可选）
• 需要时已启用 Graphiti / Langfuse / 可观测性（可选）
• 栈已启动、日志健康、默认管理员密码已修改

下一步

登录后即可创建第一个 flow、使用提示词模板并查看结果（详见 README.md 的 "How to Use PentAGI After Login" 章节）。如需加固或全本地化部署，请继续阅读 Worker Node 部署指南（双节点隔离架构、Docker-in-Docker 与 TLS 加固）与 vLLM + Qwen3.5-27B-FP8 部署指南（生产级本地 LLM 推理）。

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi