Strix 部署与配置指南（Ubuntu + GPUStack）

本指南适用于在 Ubuntu 系统上部署开源 AI 渗透测试工具 Strix，并使用本地部署的 GPUStack 服务作为 LLM 后端。所有敏感信息均以占位符表示，请根据实际环境替换。

1. 前置条件

• 操作系统：Ubuntu 20.04 或更高版本
• 硬件：建议 8GB 以上内存，如有 GPU 加速效果更佳
• 软件：
  • Docker（已安装并运行）
  • Python 3.12+
  • 网络访问（可能需配置镜像加速）
• GPUStack 服务：已部署并运行，具有有效的 API Key

2. 安装 Docker（如未安装）

如果 Docker 尚未安装，可使用国内镜像源快速安装：

# 安装依赖

sudo apt update

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# 添加阿里云 Docker 镜像源

curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg –dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg –print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io

# 启动并设置开机自启

sudo systemctl start docker

sudo systemctl enable docker

# 将当前用户加入 docker 组（需要重新登录生效）

sudo usermod -aG docker $USER

验证：docker –version 和 docker run hello-world。

3. 安装 Strix

Strix 可通过 pipx 安装，避免污染系统 Python 环境。

# 安装 pipx（系统包）

sudo apt install -y pipx

pipx ensurepath

# 重新加载 shell 或 source ~/.bashrc

source ~/.bashrc

# 使用国内镜像安装 strix-agent

pipx install strix-agent –index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 如清华镜像慢，可改用阿里云（注意 http）

# pipx install strix-agent –index-url http://mirrors.aliyun.com/pypi/simple/ –trusted-host mirrors.aliyun.com

验证：strix –version 应显示版本号。

4. 配置 GPUStack 连接信息

从 GPUStack 控制台获取以下信息：

• API Base URL：如 http://YOUR_GPU_STACK_IP:YOUR_PORT/v1
• API Key：如 gpustack_xxxxxxxxxxxxxxxx
• 模型名称：如 gpt-oss-20b 或 deepseek-r1-distill-qwen-14b

推荐优先使用 gpt-oss-20b，它对工具调用的支持可能更稳定。

4.1 临时环境变量测试（推荐先用此方法）

在终端执行以下命令（替换占位符）：

export STRIX_LLM="openai/YOUR_MODEL_NAME"

export LLM_API_KEY="YOUR_GPU_STACK_API_KEY"

export LLM_API_BASE="http://YOUR_GPU_STACK_IP:YOUR_PORT/v1"

export STRIX_MAX_TOKENS=8192          # 避免负数错误

export STRIX_MODEL_CONTEXT_LENGTH=8192 # 手动指定上下文长度

export LITELLM_DROP_PARAMS=true       # 忽略不支持的参数

然后运行一次测试扫描：

strix –target ./test-scan

如果成功，可将这些变量持久化。

4.2 持久化配置

方法 A：写入 ~/.strix/cli-config.json

Strix 在首次运行后会自动生成此文件，可手动编辑：

nano ~/.strix/cli-config.json

填入以下内容（使用占位符）：

json

{

  "env": {

    "STRIX_LLM": "openai/YOUR_MODEL_NAME",

    "LLM_API_KEY": "YOUR_GPU_STACK_API_KEY",

    "LLM_API_BASE": "http://YOUR_GPU_STACK_IP:YOUR_PORT/v1",

    "STRIX_MAX_TOKENS": "8192",

    "STRIX_MODEL_CONTEXT_LENGTH": "8192",

    "LITELLM_DROP_PARAMS": "true"

  }

}

保存后，每次执行 strix 将自动使用该配置。

方法 B：写入 ~/.bashrc（环境变量）

若配置文件不生效，可将环境变量加入 ~/.bashrc：

echo 'export STRIX_LLM="openai/YOUR_MODEL_NAME"' >> ~/.bashrc

echo 'export LLM_API_KEY="YOUR_GPU_STACK_API_KEY"' >> ~/.bashrc

echo 'export LLM_API_BASE="http://YOUR_GPU_STACK_IP:YOUR_PORT/v1"' >> ~/.bashrc

echo 'export STRIX_MAX_TOKENS=8192' >> ~/.bashrc

echo 'export STRIX_MODEL_CONTEXT_LENGTH=8192' >> ~/.bashrc

echo 'export LITELLM_DROP_PARAMS=true' >> ~/.bashrc

source ~/.bashrc

5. 常见错误及解决方法

5.1 错误：max_tokens must be at least 1, got -6100

原因：Strix 计算 max_tokens 时使用了错误的上下文长度（可能为 0），导致负数。

解决：

• 设置环境变量 STRIX_MAX_TOKENS=8192（或更大）强制指定输出 token 上限。
• 同时设置 STRIX_MODEL_CONTEXT_LENGTH=8192 告知模型上下文总长，让 Strix 正确计算剩余 token。

5.2 错误："auto" tool choice requires –enable-auto-tool-choice …

原因：GPUStack 后端（如 vLLM/llama.cpp）未开启工具调用（Function Calling）支持。

解决：

• 尝试设置 LITELLM_DROP_PARAMS=true，让 LiteLLM 丢弃 tool_choice 参数（可能影响功能）。
• 切换至对工具调用兼容性更好的模型，如 gpt-oss-20b。
• 若有权限，在 GPUStack 启动参数中添加 –enable-auto-tool-choice 和 –tool-call-parser（具体取决于后端）。

5.3 错误：Unexpected token 13 while expecting start token 200006

原因：模型后端对请求格式不兼容，通常与 tools 参数有关。

解决：

• 同 5.2，尝试 LITELLM_DROP_PARAMS=true。
• 更换为 gpt-oss-20b 模型。
• 如仍失败，考虑使用完全兼容 OpenAI API 的推理服务器（如 text-generation-webui 的 OpenAI 扩展）。

5.4 警告：openai/xxx is not a recommended frontier model

说明：只是警告，不影响使用。本地开源模型能力通常弱于前沿闭源模型，但若追求隐私或离线，可以接受。

6. 执行扫描

# 扫描本地代码目录

strix –target /path/to/your/app

# 扫描在线网站（需授权）

strix –target https://example.com

# 查看结果（自动生成在 strix_runs/ 目录）

strix view

7. 附：验证 GPUStack 连通性

可用 curl 测试工具调用是否支持：

curl -X POST http://YOUR_GPU_STACK_IP:YOUR_PORT/v1/chat/completions \\

  -H "Authorization: Bearer YOUR_API_KEY" \\

  -H "Content-Type: application/json" \\

  -d '{

    "model": "YOUR_MODEL_NAME",

    "messages": [{"role": "user", "content": "Hello"}],

    "tool_choice": "auto",

    "tools": [{"type": "function", "function": {"name": "test"}}]

  }'

若返回正常，说明支持工具调用；若返回错误，请按第 5 节处理。

8. 注意事项

• 所有测试目标必须获得合法授权，否则请勿使用。
• 首次运行会拉取 Strix 的 Docker 沙箱镜像，可能需要耐心等待或配置 Docker 镜像加速。
• 若网络受限，可提前配置 Docker 镜像加速器（如阿里云容器镜像服务）。

9. 获取帮助

• 官方文档：docs.strix.ai
• Discord 社区：discord.gg/strix-ai