307 lines
12 KiB
Markdown
307 lines
12 KiB
Markdown
# 部署文档
|
||
|
||
本文档覆盖 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 开发运行
|
||
|
||
```powershell
|
||
go run .
|
||
```
|
||
|
||
打开 http://localhost:8080 ，在 Web 设置页填入 API Key（写入 `data/api-config.json`），或提前配置 `.env`。
|
||
|
||
### 4.2 生产运行（Linux + systemd）
|
||
|
||
1. 交叉编译（Windows 上）：
|
||
|
||
```powershell
|
||
$env:GOOS="linux"; $env:GOARCH="amd64"; $env:CGO_ENABLED="0"
|
||
go build -trimpath -ldflags="-s -w" -o agent-linux-amd64 .
|
||
```
|
||
|
||
2. 上传 `agent-linux-amd64` 与 `web/static/` 到服务器 `/opt/agent/`：
|
||
|
||
```
|
||
/opt/agent/agent # 二进制（chmod 755）
|
||
/opt/agent/web/static/ # 前端
|
||
/opt/agent/.env # 配置（可选，也可全部用环境变量）
|
||
```
|
||
|
||
3. systemd 单元 `/etc/systemd/system/agent-web.service`：
|
||
|
||
```ini
|
||
[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
|
||
```
|
||
|
||
```bash
|
||
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（默认引擎，推荐）
|
||
|
||
```bash
|
||
# 仓库根目录，构建上下文为 pi-coop/，无需预编译任何二进制
|
||
docker build -f pi-coop/Dockerfile -t pi-coop pi-coop/
|
||
```
|
||
|
||
镜像内含 node 22 + npm 全局安装的 pi coding agent + 系统/Python 工具。
|
||
运行参数（由 run_coop 自动注入，也可手动测试）：
|
||
|
||
```bash
|
||
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/`）：
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
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 本地验证镜像
|
||
|
||
```bash
|
||
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 健康检查
|
||
|
||
```bash
|
||
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` |
|