Yliken/BlackBean

Fork 0

Files

T

Yliken 086803a8dd first commit

2026-08-14 23:41:57 +08:00

12 KiB

Raw Blame History

部署文档

本文档覆盖 Local Agent 的全部部署方式：本地运行、Docker 协作引擎镜像、Tsecbench 托管模式镜像，以及完整的配置项说明与常见问题排障。

1. 架构概览

┌────────────────────────────────────────────────┐
│  控制层 agent（Go 二进制，本项目根目录）          │
│  - HTTP/WS 服务（Gin），serve web/static 前端    │
│  - 多轮工具调用循环（LLM 驱动）                  │
│  - run_coop 工具：调起协作容器异步执行子任务       │
└──────────────┬─────────────────────────────────┘
               │ docker run / 子进程
   ┌───────────┼─────────────┬───────────────┐
   ▼           ▼             ▼               ▼
 pi-coop    pigo-coop    claude-coop    supervisor.sh
（pi 引擎） （pigo 引擎） （Claude Code）  （本地子进程模式，
  默认                                   Tsecbench 托管用）

组件	目录	说明
控制层	`main.go` + `internal/`	Agent 核心、HTTP/WS 服务、工具实现
前端	`web/static/`	由控制层直接 serve，无需单独部署
pi 引擎	`pi-coop/`	默认协作引擎，基于 npm 包 `@earendil-works/pi-coding-agent`
pigo 引擎	`pigo/`	Go 自研引擎，需交叉编译二进制后构建镜像
claude 引擎	`claude code/`	包装 Claude Code CLI，仅支持 anthropic 协议
托管镜像	`tencent/`	Tsecbench 平台一体化镜像（控制层 + worker 本地子进程模式）

2. 环境要求

依赖	版本	用途
Go	≥ 1.22（以 go.mod 为准）	编译控制层 / pigo
Docker	任意现代版本	构建协作镜像 / run_coop 工具
Node	≥ 22.19	pi 引擎运行时（仅容器内需要，宿主机不用装）
WSL（Windows）	—	在 Windows 上构建 Linux 镜像时使用
Python 3 + paramiko	可选	仅 `deploy_*.py` 远程部署脚本需要

3. 配置说明

3.1 配置优先级

环境变量  >  .env 文件  >  data/api-config.json  >  内置默认值

.env 放在程序工作目录，启动时自动加载（已存在的环境变量优先）。
api-config.json 由 Web 设置页写入，存于数据目录（AGENT_DATA_DIR）。
容器部署时通过 docker run -e 注入的环境变量具有最高优先级。

3.2 LLM 配置（协作引擎共用）

环境变量	必填	默认	说明
`LLM_API_KEY`	✅	—	LLM API 密钥
`LLM_BASE_URL`	✅	—	接口地址。anthropic 协议会自动剥离 `/v1`、`/v1/messages`、`/messages` 后缀
`LLM_MODEL`	✅	—	模型名，需与供应商支持的格式完全一致（如 `deepseek-v4-pro` / `deepseek-v4-flash`）
`LLM_PROVIDER`	✅	`openai`	`openai` / `anthropic`
`LLM_ENGINE`	否	`pi`	协作引擎：`pi` / `pigo` / `claude`
`COOP_MODE`	否	`local`	协作模式（`local` 为本地子进程模式）

DeepSeek Anthropic 端点示例：

LLM_BASE_URL=https://api.deepseek.com/anthropic
LLM_PROVIDER=anthropic
LLM_MODEL=deepseek-v4-flash

3.3 控制层运行配置

环境变量	内置默认	说明
`AGENT_PORT`	`8080`	Web 服务端口
`AGENT_WORKSPACE`	当前目录	Agent 可读写的根目录
`AGENT_DATA_DIR`	`<workspace>/data`	会话与配置存储目录
`AGENT_AUTH_CODE`	空（关闭）	访问授权码，云端部署强烈建议设置
`AGENT_MAX_CONTEXT_TOKENS`	`1000000`	超过该估算值触发历史压缩
`AGENT_KEEP_RECENT_MESSAGES`	`50`	压缩时保留的最近消息数
`AGENT_MAX_TOOL_RESULT_CHARS`	`100000`	单次工具结果最大字符数
`AGENT_MAX_ITERATIONS`	`50`	单轮最多工具调用次数
`AGENT_TOOL_TIMEOUT_SECONDS`	`600`	单次工具执行超时
`AGENT_REQUEST_TIMEOUT_SECONDS`	`600`	单次 LLM 请求超时
`AGENT_STREAM_OUTPUT_TOKENS`	`65536`	流式输出 max_tokens（防截断关键项）
`AGENT_COMPACTION_TOKENS`	`16384`	压缩摘要最大输出 token
`AGENT_TEMPERATURE`	`0.3`	采样温度
`AGENT_DOCKER_SOCKET`	平台默认	Docker 连接地址（本地 unix socket / npipe / 远程）

注：.env.example 中的数值是保守示例。复杂任务（长思考、大输出）请参照上表默认值，尤其是 AGENT_STREAM_OUTPUT_TOKENS——过低会导致 LLM 思考阶段耗尽配额、工具调用被截断。

3.4 托管模式开关

环境变量	说明
`BENCHMARK_TOKEN`	非空时进入 Tsecbench 托管模式：启动即自动开跑评测，无需外部触发；为空则是普通本地/云部署

3.5 遗留变量

SILICONFLOW_API_KEY / SILICONFLOW_BASE_URL / AGENT_MODEL 为早期硅基流动专用配置，仍向后兼容；新部署统一使用 LLM_* 系列。

4. 部署方式一：本地直接运行

4.1 开发运行

go run .

打开 http://localhost:8080 ，在 Web 设置页填入 API Key（写入 data/api-config.json），或提前配置 .env。

4.2 生产运行（Linux + systemd）

交叉编译（Windows 上）：

$env:GOOS="linux"; $env:GOARCH="amd64"; $env:CGO_ENABLED="0"
go build -trimpath -ldflags="-s -w" -o agent-linux-amd64 .

上传 agent-linux-amd64 与 web/static/ 到服务器 /opt/agent/：

/opt/agent/agent                # 二进制（chmod 755）
/opt/agent/web/static/          # 前端
/opt/agent/.env                 # 配置（可选，也可全部用环境变量）

systemd 单元 /etc/systemd/system/agent-web.service：

[Unit]
Description=Local Agent Web
After=network.target

[Service]
WorkingDirectory=/opt/agent
Environment=LLM_API_KEY=sk-xxxx
Environment=LLM_BASE_URL=https://api.deepseek.com/anthropic
Environment=LLM_MODEL=deepseek-v4-flash
Environment=LLM_PROVIDER=anthropic
ExecStart=/opt/agent/agent
Restart=always

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now agent-web
curl -s http://localhost:8080/api/v1/health   # 验证

5. 部署方式二：Docker 协作引擎

控制层通过 run_coop 工具调起协作容器。镜像名与容器名前缀是代码内置约定，不可更改：

引擎	镜像名	容器名前缀
pi（默认）	`pi-coop`	`pi-coop-`
pigo	`pigo-coop`	`pigo-coop-`
claude	`claude-coop`	`claude-coop-`

5.1 构建 pi-coop（默认引擎，推荐）

# 仓库根目录，构建上下文为 pi-coop/，无需预编译任何二进制
docker build -f pi-coop/Dockerfile -t pi-coop pi-coop/

镜像内含 node 22 + npm 全局安装的 pi coding agent + 系统/Python 工具。运行参数（由 run_coop 自动注入，也可手动测试）：

docker run --rm \
  -e MODEL=deepseek-v4-flash \
  -e BASE_URL=https://api.deepseek.com/anthropic \
  -e API_KEY=<your-key> \
  -e PROTOCOL=anthropic \
  -e TASK="任务描述" \
  -e ROUND_MAX=6 \
  pi-coop

5.2 构建 pigo-coop

需先交叉编译 pigo 二进制（构建上下文为 pigo/）：

cd pigo
GOOS=linux CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" \
  -o coop/tmp/pigo-linux-amd64 ./cmd/pigo
docker build -f coop/Dockerfile -t pigo-coop .

5.3 构建 claude-coop

docker build -f "claude code/Dockerfile" -t claude-coop "claude code/"

仅支持 anthropic 协议；openai 协议请求会被拒绝，请切换引擎或更换端点。

5.4 切换引擎

Web 设置页修改协作引擎，或设置 LLM_ENGINE=pigo / LLM_ENGINE=claude。切换前确保对应镜像已构建。

6. 部署方式三：Tsecbench 托管模式（tencent/）

一体化镜像 = 控制层 agent + pi worker（本地子进程模式）+ 安全工具集，适合上传到 Tsecbench 评测平台。

6.1 前置准备

镜像构建依赖以下文件，均不在 git 仓库内，需自行准备：

文件	说明
`tencent/agent-linux-amd64`	控制层交叉编译产物（见 4.2 步骤 1）
`tencent/tools/nuclei`	漏洞扫描器静态二进制
`tencent/tools/observer_ward`	指纹识别静态二进制
`tencent/tools/chisel`	内网隧道静态二进制
`tencent/tools/nuclei-templates/`	Nuclei 模板库
`tencent/tools/FingerprintHub-defaultv4/plugins/`	observer_ward 指纹规则库

6.2 构建与导出

在 WSL 中执行（脚本内 PROJECT_ROOT 按实际路径调整）：

bash tencent/build.sh
# 或自定义镜像名：IMAGE_NAME=myagent bash tencent/build.sh

脚本流程：检查二进制 → docker build（上下文为项目根，.dockerignore 排除无关文件）→ docker save | gzip 导出。

产物：tencent/agent.tar.gz（约 350MB），直接上传 Tsecbench 平台即可。

6.3 本地验证镜像

docker run --rm -p 8081:8080 \
  -e LLM_API_KEY=sk-xxxx \
  -e LLM_BASE_URL=https://api.deepseek.com/anthropic \
  -e LLM_MODEL=deepseek-v4-flash \
  -e LLM_PROVIDER=anthropic \
  tsecbench-agent:latest

打开 http://localhost:8081 验证 Web 界面。
平台托管时由运行时注入 BENCHMARK_TOKEN，agent 检测到后自动启动评测流程。
镜像内不含 data/ 目录与任何预置配置，全部由环境变量注入。

7. 验证与排障

7.1 健康检查

curl http://localhost:8080/api/v1/health      # 服务存活（始终放行，不受授权码保护）
curl http://localhost:8080/api/v1/llm/config  # 查看生效的 LLM 配置（需授权码）

7.2 常见问题

现象	原因与解决
侧栏显示「模型未配置」	未设置 `LLM_API_KEY`，也未在 Web 设置页填写。配置后重启或刷新
LLM 请求 404	Base URL 拼接问题。anthropic 协议不要手动加 `/v1`，程序会自动处理后缀；openai 协议填到根地址即可
工具调用 JSON 被截断、任务失败	`AGENT_STREAM_OUTPUT_TOKENS` 过低，LLM 思考阶段耗尽 max_tokens。保持默认 65536
run_coop 报找不到镜像	对应引擎镜像未构建（见第 5 节），或镜像名不符合约定（必须是 `pi-coop` / `pigo-coop` / `claude-coop`）
run_coop 容器秒退	检查 `MODEL` / `BASE_URL` / `API_KEY` 是否有效；`docker logs <容器名>` 看具体报错
长命令超时	`AGENT_TOOL_TIMEOUT_SECONDS` / `AGENT_REQUEST_TIMEOUT_SECONDS` 调大（默认 600s）
Web 界面 401	设置了 `AGENT_AUTH_CODE`，先在弹窗输入授权码
历史压缩后丢上下文	调大 `AGENT_KEEP_RECENT_MESSAGES`（默认 50）与 `AGENT_COMPACTION_TOKENS`（默认 16384）

7.3 安全检查清单

.env 与 API Key 未提交到 git（.gitignore 已包含 .env）
云端公开部署已设置 AGENT_AUTH_CODE
API Key 泄露后立即在供应商侧吊销并轮换
Docker Socket 未暴露给不受信任的网络
AGENT_WORKSPACE 限定在专用目录，避免指向系统根目录

8. 端口与产物速查

场景	端口	产物
本地运行	8080（`AGENT_PORT`）	—
pi/pigo/claude 协作镜像	—	`pi-coop` / `pigo-coop` / `claude-coop` 镜像
Tsecbench 托管	8080（容器内）	`tencent/agent.tar.gz`

12 KiB Raw Blame History Unescape Escape