andrewgibson-cic/slapenir
GitHub: andrewgibson-cic/slapenir
面向 AI Agent 的零知识安全代理环境，通过凭证隔离、网络隔离和 mTLS 保护，确保自主 AI 代理在调用外部 API 时无法接触真实凭证。
Stars: 0 | Forks: 0
# SLAPENIR
**安全 LLM Agent 代理环境，具备网络隔离与弹性恢复能力 (SLAPENIR)** —— 一款面向 AI Agent 的零知识凭证清洗代理。
## 概述
SLAPENIR 位于 AI Agent 与外部 API 之间，确保 Agent 永远无法看到真实凭证：
- **注入** 真实凭证到出站请求
- **清洗** 入站响应中的敏感信息
- **隔离** Agent 于受控网络环境中
- **监管** Agent 进程并自动重启
## 架构
```
┌──────────────┐
│ Step-CA │ Certificate Authority
└──────────────┘
│ mTLS
↓
┌──────────────┐ ┌──────────────┐
│ Prometheus │────▶│ Grafana │
└──────────────┘ └──────────────┘
↑
│ metrics
┌──────┴───────┐
│ Proxy │ Rust Sanitizing Gateway
│ :3000 │ • Aho-Corasick O(N) pattern matching
│ │ • Zero-knowledge credential handling
│ │ • Memory-safe with Zeroize
└──────┬───────┘
│ mTLS
↓
┌──────────────┐ ┌──────────────┐
│ Agent │────▶│ Memgraph │ Graph Database
│ Python 3.12 │ │ :7687 │ • Code-Graph-RAG
│ │ └──────────────┘ • Knowledge Graphs
│ • s6-overlay │ │
│ • OpenCode │ ↓
│ • MCP Tools │ ┌──────────────┐
│ - Memory │ │ Memgraph Lab │ Visualization
│ - Knowledge│ │ :7688 │
└──────────────┘ └──────────────┘
```
## 目录
1. [前置条件](#prerequisites)
2. [安装](#installation)
- [步骤 1：克隆仓库](#step-1-clone-repository)
- [步骤 2：安装 Docker](#step-2-install-docker)
- [步骤 3：配置环境变量](#step-3-configure-environment-variables)
- [步骤 4：下载并配置 LLM](#step-4-download-and-configure-llm)
- [步骤 5：启动服务](#step-5-start-services)
3. [配置指南](#configuration-guide)
4. [常用操作](#common-operations)
5. [实用命令参考](#useful-commands-reference)
6. [故障排除](#troubleshooting)
7. [安全特性](#security-features)
8. [测试](#testing)
9. [文档](#documentation)
## 前置条件
### 必备软件
| 软件 | 最低版本 | 检查方式 | 安装方式 |
|----------|-----------------|--------------|--------------|
| **Docker Desktop** | v27+ | `docker --version` | [下载 Docker](https://www.docker.com/products/docker-desktop/) |
| **Docker Compose** | v2.24+ | `docker compose version` | 包含在 Docker Desktop 中 |
| **Git** | v2.30+ | `git --version` | [下载 Git](https://git-scm.com/downloads) |
### 系统要求
| 资源 | 最低 | 推荐 |
|----------|---------|-------------|
| RAM | 8 GB | 16 GB+ (用于本地 LLM) |
| CPU | 4 核心 | 8+ 核心 |
| 硬盘 | 20 GB | 50 GB+ (用于 LLM 模型) |
| OS | macOS 12+, Ubuntu 20.04+, Windows 10+ with WSL2 | |
### 本地 LLM 硬件推荐
| 模型大小 | 所需 RAM | GPU (可选) |
|------------|--------------|----------------|
| 7B 参数 | 8 GB | 6 GB VRAM |
| 14B 参数 | 16 GB | 12 GB VRAM |
| 35B 参数 | 32 GB | 24 GB VRAM |
| 70B+ 参数 | 64 GB | 48 GB+ VRAM |
## 安装
### 步骤 1：克隆仓库
打开终端并克隆 SLAPENIR 仓库：
```
# 导航到你的项目目录
cd ~/Projects
# 克隆仓库
git clone https://github.com/andrewgibson-cic/slapenir.git
# 进入项目目录
cd slapenir
```
### 步骤 2：安装 Docker
#### macOS
1. 下载 [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/)
2. 打开下载的 `.dmg` 文件
3. 将 Docker 拖入您的 Applications 文件夹
4. 从 Applications 打开 Docker
5. 等待 Docker 启动（菜单栏中的鲸鱼图标应保持静止）
6. 验证安装：
docker --version
docker compose version
#### Ubuntu Linux
```
# 更新软件包索引
sudo apt-get update
# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# 将你的用户添加到 docker 组（需要注销/登录）
sudo usermod -aG docker $USER
# 安装 Docker Compose
sudo apt-get install docker-compose-plugin
# 验证安装
docker --version
docker compose version
```
#### Windows (使用 WSL2)
1. 安装 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)
2. 安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)
3. 在 Docker Desktop 设置中启用 WSL2 后端
4. 在 WSL2 中按照上述 Ubuntu 说明操作
### 步骤 3：配置环境变量
`.env` 文件包含您的真实 API 凭证。**永远不要将此文件提交到版本控制。**
#### 3.1 创建您的 .env 文件
```
# 复制示例文件以创建你的 .env
cp .env.example .env
```
#### 3.2 编辑 .env 文件
在您喜欢的编辑器中打开 `.env`：
```
# 使用 nano（适合新手）
nano .env
# 使用 VS Code
code .env
# 使用 vim
vim .env
```
#### 3.3 必要配置
**最低必要变量**（您必须设置这些）：
```
# Git 配置（Agent 进行提交所必需）
GIT_USER_NAME="Your Name"
GIT_USER_EMAIL="your.email@example.com"
# GitHub Personal Access Token（GitHub API 访问所必需）
# 生成地址：https://github.com/settings/tokens
# 所需权限范围：repo, read:org, read:user, read:discussion
GITHUB_TOKEN=ghp_your_token_here
```
#### 3.4 关键安全变量
**重要：** 请为生产环境设置这些密码。如果未设置，将使用默认值（生产环境不推荐）：
```
# Step-CA Password（用于证书颁发机构）
STEPCA_PASSWORD=your-strong-stepca-password-here
# PostgreSQL Password
POSTGRES_PASSWORD=your-strong-postgres-password-here
# Grafana Admin Password
GRAFANA_ADMIN_PASSWORD=your-strong-grafana-password-here
```
#### 3.5 可选 API 密钥
添加您的 Agent 将使用的任何 API 密钥。代理将在运行时注入这些密钥：
```
# LLM APIs
OPENAI_API_KEY=sk-proj-real-key-here
ANTHROPIC_API_KEY=sk-ant-real-key-here
# Cloud Providers
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Other Services
STRIPE_SECRET_KEY=sk_live_realKeyHere
# ... 等
```
#### 3.6 理解零知识架构
**SLAPENIR 中的凭证工作原理：**
1. **在您的 `.env` 文件中：** 您设置真实凭证（例如 `OPENAI_API_KEY=sk-proj-real-key-123`）
2. **在 `.env.agent (自动生成) 中：** Agent 看到的是虚拟值（例如 `OPENAI_API_KEY=DUMMY_OPENAI`）
3. **在代理运行时：** 当 Agent 使用 `DUMMY_OPENAI` 发起请求时，代理会将其替换为真实密钥
4. **Agent 永远看不到真实凭证！**
这是自动配置的 —— 您不需要手动创建 `.env.agent`。
### 步骤 4：下载并配置 LLM
SLAPENIR 需要本地 LLM 以进行离线运行。本节介绍下载模型和运行 llama-server。
#### 4.1 选择您的模型
**推荐模型**（已量化以提高效率）：
| 模型 | 大小 | 用途 | 下载 |
|-------|------|----------|----------|
| Qwen2.5-7B-Instruct | 4.4 GB | 快速、轻量级任务 | [HuggingFace](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF) |
| Qwen2.5-14B-Instruct | 8.6 GB | 平衡的性能 | [huggingFace](https://huggingface.co/Qwen/Qwen2.5-14B-Instruct-GGUF) |
| Qwen2.5-32B-Instruct | 19 GB | 复杂推理 | [HuggingFace](https://huggingface.co/Qwen/Qwen2.5-32B-Instruct-GGUF) |
| Qwen3.5-35B-A3B | 18 GB | 高级编码 + 思考 | [HuggingFace](https://huggingface.co/Qwen/Qwen3-35B-A3B-UD-Q4_K_XL) |
| Llama-3.2-3B-Instruct | 2.0 GB | 极快、简单任务 | [HuggingFace](https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct-GGUF) |
#### 4.2 下载模型
```
# 创建 models 目录
mkdir -p ~/models
# 示例：下载 Qwen2.5-14B-Instruct (8.6 GB)
# 选项 A：使用 huggingface-cli（推荐）
pip install huggingface-hub
huggingface-cli download Qwen/Qwen2.5-14B-Instruct-GGUF --local-dir ~/models
# 选项 B：使用 wget 直接下载
cd ~/models
wget https://huggingface.co/qwen/Qwen2.5-14B-Instruct-GGUF/resolve/main/Qwen2.5-14b-instruct-q4_k_m.gguf
```
#### 4.3 安装 llama-server
**选项 A：使用预构建二进制文件**（推荐）：
```
# macOS (Apple Silicon)
curl -L https://github.com/ggerganov/llama.cpp/releases/download/master/llama-server-macos-arm64.zip -o llama-server.zip
unzip llama-server.zip
sudo mv llama-server /usr/local/bin/
# Ubuntu Linux
curl -L https://github.com/ggerganov/llama.cpp/releases/download/master/llama-server-ubuntu-x64.zip -o llama-server.zip
unzip llama-server.zip
sudo mv llama-server /usr/local/bin/
# 验证安装
llama-server --version
```
**选项 B：从源码构建：**
```
# 克隆 llama.cpp
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
# 构建（需要 cmake 和 C++ 编译器）
mkdir build
cd build
cmake ..
cmake --build . --config Release
sudo cp llama-server /usr/local/bin/
```
#### 4.4 启动 llama-server
**基本启动**（简单）：
```
llama-server \
--model ~/models/qwen2.5-14b-instruct-q4_k_m.gguf \
--host 0.0.0.0 \
--port 8080
```
**推荐的生产配置**（包含所有优化）：
```
llama-server \
--model ~/models/Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf \
--ctx-size 200000 \
--temp 0.6 \
--top-p 0.0 \
--top-k 20 \
--min-p 0.00 \
--host 0.0.0.0 \
--port 8080 \
--n-gpu-layers 99 \
--threads 8 \
--jinja \
--cache-type-k q8_0 \
--cache-type-v q8_0 \
--flash-attn on \
--batch-size 256 \
--ubatch-size 128 \
--alias "Qwen3.5-Coding-Thinking" \
--presence-penalty 0.0 \
--repeat-penalty 1.0 \
--chat-template-kwargs '{"enable_thinking": true}' \
--mmproj ~/models/mmproj-F16.gguf
```
**参数说明：**
| 参数 | 值 | 描述 |
|-----------|-------|-------------|
| `--model` | 路径 | GGUF 模型文件的路径 |
| `--ctx-size` | 200000 | 最大上下文窗口 (tokens) |
| `--temp` | 0.0-1.0 | 温度（越低越确定） |
| `--top-p` | 0.0-1.0 | 核采样概率 |
| `--top-k` | 20-100 | Top-k 采样 |
| `--min-p` | 0.0-0.1 | 最小概率阈值 |
| `--host` | 0.0.0.0 | 监听所有接口 |
| `--port` | 8080 | 服务器端口 |
| `--n-gpu-layers` | 99 | GPU 层数（99 = 全部，0 = 仅 CPU） |
| `--threads` | 8 | 用于处理的 CPU 线程 |
| `--jinja` | 标志 | 启用 Jinja2 模板引擎 |
| `--cache-type-k` | q8_0 | 键缓存量化 |
| `--cache-type-v` | q8_0 | 值缓存量化 |
| `--flash-attn` | on | Flash attention 优化 |
| `--batch-size` | 256 | 提示词的最大批次大小 |
| `--ubatch-size` | 128 | 微批次大小 |
| `--mmproj` | 路径 | 多模态投影器（用于视觉模型） |
#### 4.5 作为后台服务运行
**创建 systemd 服务**（Linux）：
```
# 创建服务文件
sudo tee /etc/systemd/system/llama-server.service << EOF
[Unit]
Description=LLaMA Server
After=network.target
[Service]
Type=simple
User=$USER
WorkingDirectory=/home/$USER
ExecStart=/usr/local/bin/llama-server \\
--model /home/$USER/models/qwen2.5-14b-instruct-q4_k_m.gguf \\
--host 0.0.0.0 \\
--port 8080 \\
--ctx-size 32000 \\
--threads 8
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
EOF
# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable llama-server
sudo systemctl start llama-server
# 检查状态
sudo systemctl status llama-server
```
**使用 launchd**（macOS）：
```
# 创建 plist 文件
cat > ~/Library/LaunchAgents/com.llama.server.plist << EOF
Label
com.llama.server
ProgramArguments
/usr/local/bin/llama-server
--model
/Users/$USER/models/qwen2.5-14b-instruct-q4_k_m.gguf
--host
0.0.0.0
--port
8080
--ctx-size
32000
--threads
8
RunAtLoad
KeepAlive
EOF
# 加载服务
launchctl load ~/Library/LaunchAgents/com.llama.server.plist
```
#### 4.6 验证 LLM 服务器
```
# 检查服务器是否正在运行
curl http://localhost:8080/health
# 测试简单的补全
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "local",
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 50
}'
```
### 步骤 5：启动服务
现在 Docker 已运行，环境已配置，LLM 服务器已就绪，启动 SLAPENIR：
#### 5.1 初始启动
```
# 使启动脚本可执行（仅首次）
chmod +x slapenir
# 启动所有服务
./slapenir start
```
此命令将：
1. 生成 mTLS 证书（首次运行约需 30 秒）
2. 构建 Docker 镜像（首次运行需 5-10 分钟）
3. 按正确顺序启动所有服务
4. 等待健康检查通过
5. 显示服务 URL
#### 5.2 验证服务正在运行
```
# 检查服务状态
./slapenir status
# 或手动检查每个服务
docker compose ps
```
预期输出：
```
NAME STATUS PORTS
slapenir-proxy running (healthy) 0.2.3.4:3000->3000/tcp
slapenir-agent running 1.2.3.4:22->22/tcp
slapenir-ca running (healthy) 1.2.3.4:9000->9000/tcp
slapenir-postgres running (healthy) 1.2.3.4:5432->5432/tcp
slapenir-memgraph running (healthy) 1.2.3.4:7687->7687/tcp
```
#### 5.3 访问服务
| 服务 | URL | 用户名 | 密码 | 用途 |
|---------|-----|----------|----------|---------|
| Proxy | http://localhost:3000 | - | - | API 网关，健康检查 |
| Prometheus | http://localhost:9090 | - | - | 指标收集 |
| Grafana | http://localhost:3001 | admin | admin (或您的自定义) | 监控仪表板 |
| Memgraph Lab | http://localhost:7688 | - | - | 图可视化 |
## 配置指南
### 环境变量参考
#### 系统配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ENVIRONMENT` | `development` | 环境名称（development, staging, production） |
| `LOG_LEVEL` | `INFO` | 日志级别（DEBUG, INFO, WARNING, ERROR） |
| `LOG_ENABLED` | `true` | 启用文件日志 |
| `LOG_DIR` | `/var/log/slapenir` | 日志目录路径 |
| `LOG_MAX_BYTES` | `10485760` | 最大日志文件大小 (10MB) |
| `LOG_BACKUP_COUNT` | `5` | 轮转日志文件数量 |
#### 安全配置
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `STEPCA_PASSWORD` | **是** (生产) | Step-CA 根密码 |
| `POSTGRES_PASSWORD` | **是** (生产) | PostgreSQL 数据库密码 |
| `GRAFANA_ADMIN_PASSWORD` | **是** (生产) | Grafana 管理 UI 密码 |
| `MTLS_ENABLED` | `false` | 启用 mTLS 强制执行 |
| `MTLS_ENFORCE` | `false` | 拒绝没有有效证书的连接 |
#### 代理配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `HTTP_PROXY` | `http://proxy:3000` | HTTP 的代理 URL |
| `HTTPS_PROXY` | `http://proxy:3000` | HTTPS 的代理 URL |
| `NO_PROXY` | `localhost,127.0.0.1` | 绕过这些主机的代理 |
| `AUTO_DETECT_ENABLED` | `true` | 启用自动凭证检测 |
| `ALLOW_BUILD` | `false` | 允许在 shell 中使用构建工具 |
#### LLM 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `OPENCODE_DISABLE_CLAUDE_CODE` | `1` | 禁用 Claude Code（使用本地 LLM） |
| `LLAMA_SERVER_HOST` | `host.docker.internal` | LLM 服务器主机名 |
| `LLAMA_SERVER_PORT` | `6666` | LLM 服务器端口 |
#### Code-Graph-RAG 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ORCHESTRATOR_PROVIDER` | `openai` | 提供商类型（openai 用于兼容性） |
| `ORCHESTRATOR_MODEL` | `qwen3.5-35b-a3b-ud-q4_k_xl` | 模型名称（被 llama-server 忽略） |
| `ORCHESTRATOR_ENDPOINT` | `http://host.docker.internal:6666/v1` | LLM 端点 URL |
| `ORCHESTRATOR_API_KEY` | `sk-local` | API 密钥（虚拟，被忽略） |
| `CYPHER_PROVIDER` | `openai` | Cypher 查询提供商类型 |
| `CYPHER_MODEL` | `qwen3.5-35b-a3b-ud-q4_k_xl` | Cypher 查询模型名称 |
| `YPHER_ENDPOINT` | `http://host.docker.internal:6666/v1` | Cypher 查询 LLM 端点 URL |
| `CYPHER_API_KEY` | `sk-local` | Cypher 查询 API 密钥（虚拟，被忽略） |
| `MEMGRAPH_HOST` | `memgraph` | Memgraph 主机名 |
| `MEMGRAPH_PORT` | `7687` | Memgraph 端口 |
### 网络配置
SLAPENIR 使用具有隔离功能的自定义 Docker 网络 (`slape-net`)：
```
networks:
slape-net:
driver: bridge
internal: false # Set to true for full air-gap
ipam:
config:
- subnet: 172.30.0.0/24
```
**网络隔离模式：**
| 模式 | 设置 | Agent 可访问 |
|------|---------|-------------------|
| 开发模式 | `internal: false` | 通过代理访问互联网，本地 LLM |
| 离线模式 | `internal: true` | 仅内部服务 |
要启用完全离线模式，请编辑 `docker-compose.yml`：
```
networks:
slape-net:
internal: true # Change this line
```
### Git 配置
Agent 容器挂载您宿主机的 Git 配置：
```
volumes:
- ~/.gitconfig:/home/agent/.gitconfig:ro
- ~/.ssh/config:/home/agent/.ssh/config.host:ro
- ~/.ssh/known_hosts:/home/agent/.ssh/known_hosts
- ~/.gnupg/pubring.kbx:/home/agent/.gnupg/pubring.kbx:ro
- ~/.gnupg/trustdb.gpg:/home/agent/.gnupg/trustdb.gpg:ro
```
**宿主机上必需的 Git 设置：**
```
# 设置你的 Git 身份（如果尚未设置）
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# 验证 SSH 密钥是否存在
ls -la ~/.ssh/id_rsa # or id_ed25519
# 测试 SSH 连接
ssh -T git@github.com
```
## 常用操作
### 启动服务
```
# 启动所有服务
./slapenir start
# 或使用 make
make up
```
### 停止服务
```
# 停止所有服务
./slapenir stop
# 或使用 Docker Compose
docker compose down
```
### 查看日志
```
# 查看所有日志
./slapenir logs
# 查看特定服务日志
./slapenir logs proxy
./slapenir logs agent
./slapenir logs memgraph
# 实时跟踪日志
docker compose logs -f proxy
```
### 重启服务
```
# 重启所有服务
./slapenir restart
# 重启特定服务
docker compose restart proxy
```
### 检查状态
```
# 检查所有服务
./slapenir status
# 检查特定服务
docker compose ps proxy
```
### 访问 Agent Shell
```
# 安全 Shell（阻止构建）
./slapenir shell
# 或使用 make
make shell
```
### 清理
```
# 停止并移除容器（保留卷）
./slapenir clean
# 移除所有内容包括卷（警告：这将删除所有数据！）
docker compose down -v
# 移除 Docker 镜像
docker compose down --rmi all
```
## 实用命令参考
### 服务管理
```
# 启动服务
./slapenir start # Start all services
make up # Alternative: start with make
docker compose up -d # Direct Docker Compose command
# 停止服务
./slapenir stop # Stop all services
make down # Alternative: stop with make
docker compose down # Direct Docker Compose command
# 重启服务
./slapenir restart # Restart all services
docker compose restart # Restart all containers
docker compose restart proxy # Restart specific service
# 查看状态
./slapenir status # Check service health
docker compose ps # List all containers
docker compose ps proxy # Check specific service
```
### 日志与调试
```
# 查看日志
./slapenir logs # All service logs
./slapenir logs proxy # Proxy logs only
./slapenir logs agent # Agent logs only
docker compose logs # All container logs
docker compose logs -f proxy # Follow proxy logs in real-time
docker compose logs --tail=100 agent # Last 100 lines of agent logs
# 查看带时间戳的日志
docker compose logs -t proxy
# 将日志保存到文件
docker compose logs proxy > proxy-logs.txt
```
### Shell 访问
```
# 安全 Shell（阻止构建工具）
./slapenir shell
make shell
# 直接容器 exec
docker compose exec agent bash
docker compose exec proxy sh
# 在容器中运行命令
docker compose exec agent whoami
docker compose exec agent python3 --version
```
### 数据库操作
```
# 连接到 PostgreSQL
docker compose exec postgres psql -U slapenir -d slapenir
# 连接到 Memgraph
docker compose exec memgraph mgconsole
# 运行 Cypher 查询
docker compose exec memgraph mgconsole \
-c "MATCH (n) RETURN n LIMIT 10;"
# 备份 PostgreSQL
docker compose exec postgres pg_dump -U slapenir slapenir > backup.sql
# 恢复 PostgreSQL
cat backup.sql | docker compose exec -T postgres psql -U slapenir slapenir
```
### 监控与指标
```
# 查看 Prometheus 指标
curl http://localhost:9090/metrics
# 查询特定指标
curl 'http://localhost:9090/api/v1/query?query=slapenir_requests_total'
# 访问 Grafana
open http://localhost:3001
# 检查代理健康状况
curl http://localhost:3000/health
# 查看代理指标
curl http://localhost:3000/metrics
```
### 证书管理
```
# 查看 Step-CA 日志
docker compose logs step-ca
# 检查证书状态
docker compose exec step-ca step ca status
# 列出已颁发的证书
docker compose exec step-ca step ca certificates list
# 撤销证书（如果需要）
docker compose exec step-ca step ca revoke
```
### LLM 服务器管理
```
# 检查 LLM 服务器健康状况
curl http://localhost:8080/health
# 测试补全
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"local","messages":[{"role":"user","content":"test"}],"max_tokens":10}'
# 查看可用模型
curl http://localhost:8080/v1/models
# 检查 GPU 使用情况（如果使用 GPU）
nvidia-smi
# 监控 llama-server 进程
ps aux | grep llama-server
```
### 开发与测试
```
# 运行所有测试
make test
# 仅运行 Rust 测试
cd proxy && cargo test
# 仅运行 Python 测试
pytest agent/tests/ -v
# 运行特定测试文件
cargo test test_sanitizer
# 运行覆盖率测试
pytest agent/tests/ --cov=agent/scripts
# 运行基准测试
cd proxy && cargo bench
# 运行负载测试
cd proxy/tests/load && ./run_all_load_tests.sh
```
### Git 操作
```
# 查看最近的提交
git log --oneline -10
# 检查当前状态
git status
# 拉取最新更改
git pull --rebase
# 创建新分支
git checkout -b feature/my-feature
# 查看远程分支
git branch -r
```
### Docker 清理
```
# 移除已停止的容器
docker container prune
# 移除未使用的镜像
docker image prune
# 移除未使用的卷
docker volume prune
# 清理构建缓存
docker builder prune
# 完整系统清理（警告：移除所有内容！）
docker system prune -a --volumes
```
## 故障排除
### 常见问题与解决方案
#### 服务无法启动
**症状：** `docker compose up` 失败
**解决方案：**
```
# 检查 Docker 是否正在运行
docker info
# 检查端口冲突
lsof -i :3000 # Proxy port
lsof -i :5432 # PostgreSQL port
lsof -i :8080 # LLM server port
# 查看错误日志
docker compose logs
# 重置所有内容
docker compose down -v
./slapenir start
```
#### LLM 服务器无响应
**症状：** Agent 无法连接到 LLM
**解决方案：**
```
# 检查 llama-server 是否正在运行
curl http://localhost:8080/health
# 如果未运行，启动它
llama-server --model ~/models/your-model.gguf --host 0.0.0.0 --port 8080
# 从 Docker 内部检查
docker compose exec agent curl http://host.docker.internal:8080/health
# 检查防火墙（Linux）
sudo ufw allow 8080/tcp
```
#### 证书错误
**症状：** mTLS 证书错误
**解决方案：**
```
# 重新生成证书
docker compose down -v
rm -rf ca-data
./slapenir start
# 检查 Step-CA 日志
docker compose logs step-ca
# 验证证书是否存在
ls -la ca-data/
```
#### 内存不足
**症状：** 容器被杀，OOM 错误
**解决方案：**
```
# 增加 Docker 内存限制（Docker Desktop）
# 设置 → 资源 → 内存：16GB+
# 对于 LLM，使用更小的模型或量化
llama-server --model smaller-model.gguf
# 检查内存使用情况
docker stats
```
#### Agent 无法访问 Git
**症状：** Agent 中 Git 操作失败
**解决方案：**
```
# 验证主机上的 Git 配置
git config --global user.name
git config --global user.email
# 检查 SSH 密钥
ls -la ~/.ssh/id_rsa
# 测试 SSH
ssh -T git@github.com
# 验证容器中的挂载
docker compose exec agent ls -la ~/.ssh
```
#### 网络隔离问题
**症状：** Agent 无法访问外部 API
**解决方案：**
```
# 检查网络模式
docker network inspect slape-net
# 验证代理是否正在运行
curl http://localhost:3000/health
# 检查 Agent 的代理设置
docker compose exec agent env | grep PROXY
# 通过代理测试连接
docker compose exec agent curl http://proxy:3000/health
```
### 获取帮助
```
# 查看 make 目标
make help
# 查看 slapenir 命令
./slapenir help
# 查看 Docker Compose 帮助
docker compose --help
# 查看特定服务帮助
docker compose exec proxy --help
```
## 安全特性
### 零知识架构
**工作原理：**
1. Agent 环境包含虚拟值：`DUMMY_OPENAI`、`DUMMY_GITHUB` 等。
2. 代理维护秘密映射：`DUMMY_* → 真实凭证`
3. 请求拦截：代理将虚拟值替换为真实值
4. 响应清洗：代理在 Agent 看到之前移除真实凭证
5. **Agent 永远不会看到真实凭证**
### 网络隔离
- Docker 网络分段 (`slape-net`)
- iptables 流量强制执行
- DNS 过滤（仅白名单）
- 透明代理重定向
### mTLS 认证
- Step-CA 证书颁发机构
- 24 小时证书轮换
- 所有服务之间的双向 TLS
- 短期证书限制风险暴露
### 内存安全
- Rust 所有权系统防止释放后使用
- Zeroize trait 擦除内存中的秘密
- 无垃圾回收延迟
- 边界检查防止缓冲区溢出
### 审计日志
- 记录所有请求
- 跟踪秘密清洗
- 记录绕过尝试
- 记录证书事件
- 结构化 JSON 日志
欲了解更多详情，请参阅 [安全层级](docs/SECURITY_LAYERS.md)
## 安全工作流程
这是使用 SLAPENIR 进行安全开发工作的推荐工作流程。该流程确保代码永远不会泄露到互联网，凭证永远不会暴露给 AI Agent，并且在合并前所有更改都可完全审计。
### 阶段 1：准备（在宿主机上）
```
# 1. 在主机上克隆目标仓库
git clone https://github.com/org/repo.git ~/Projects/repo
# 2. 将工单导出为 markdown 文件
mkdir -p ~/Projects/tickets
# 将工单 markdown 文件放在此目录中
# 3. 确保主机状态干净
cd ~/Projects/repo && git stash
# 4. 在主机上启动 llama-server
llama-server --host 0.0.0.0 --port 8080 --model ~/models/YourModel.gguf
```
### 阶段 2：环境设置
```
# 5. 启动 SLAPENIR 服务
make up
# 6. 将仓库和工单复制到容器中
make copy-in REPO=/path/to/repo TICKETS=/path/to/tickets
# 7. 验证连接性
make shell
# 在容器内：
ls workspace/ && curl http://host.docker.internal:8080/health
# 8. 运行飞行前安全验证
make verify
```
### 阶段 3：会话隔离
在任务之间运行此命令以防止状态泄漏：
```
# 9. 重置工作区以进行新会话（第一个工单时跳过）
make session-reset
```
### 阶段 4：AI 工作（在容器内）
```
# 10. 打开 Agent Shell
make shell
# 11. 启动 Code-Graph-RAG 并等待索引
cgr start
# 12. 创建功能分支（优雅处理现有分支）
git checkout -b fix/TICKET-123 2>/dev/null || git checkout fix/TICKET-123
# 13. 启动 OpenCode（默认禁用 YOLO 模式以确保安全）
opencode
# 或根据需要启用自动批准：OPENCODE_YOLO=true opencode
# 14. 提供带有上下文文件和特定工单的结构化提示
```
### 阶段 5：提取与审查
```
# 15. 完成后退出 OpenCode
# 在容器内审查更改
git diff && git log --oneline
# 16. 扫描意外注入的机密信息（在容器内）
grep -rnE "(sk-|ghp_|AKIA|-----BEGIN)" --include="*.py" --include="*.ts" --include="*.js" --include="*.go" --include="*.rs" .
# 17. 将仓库复制回主机并备份（防止失败时数据丢失）
make copy-out-safe REPO=/path/to/repo
# 18. 在主机上：扫描机密信息并审查 diff
cd /path/to/repo
gitleaks detect --source=. --no-git # or: trufflehog filesystem .
git diff HEAD
git log --oneline
# 19. 推送或拒绝
git push origin fix/TICKET-123
# 如果拒绝，重试：make copy-in REPO=/path/to/repo 并从第 4 阶段重复
```
### 此流程中的安全特性
| 特性 | 命令 | 用途 |
|---------|---------|---------|
| 复制出之前备份 | `make copy-out-safe` | 防止传输中途失败导致数据丢失 |
| 预飞安全检查 | `make verify` | 验证零知识架构 + 网络隔离 |
| 会话隔离 | `make session-reset` | 在任务之间清除工作区/MCP |
| YOLO 模式门控 | `OPENCODE_YOLO` 环境变量 | 默认禁用自动批准；需选择性启用 |
| 分支安全 | `\|\| git checkout` 后备 | 处理重试时已存在的分支 |
| 秘密扫描 | `grep` + `gitleaks` | 在推送前捕获凭证泄漏 |
### Make 命令参考
| 命令 | 描述 |
|---------|-------------|
| `make up` | 启动所有服务 |
| `make down` | 停止所有服务 |
| `make status` | 显示服务状态 |
| `make shell` | 打开 agent shell（构建被阻止） |
| `make copy-in REPO=... TICKETS=...` | 将 repo 和 tickets 复制到容器中 |
| `make copy-out REPO=...` | 复制 repo 并进行完整性检查 |
| `make copy-out-safe REPO=...` | 与 copy-out 相同，但会先备份宿主机副本 |
| `make session-reset` | 清除工作区、MCP 内存和知识库 |
| `make verify` | 运行预飞安全验证 |
| `make test` | 运行所有测试 |
| `make rebuild` | 从头重新构建 |
| `make clean` | 移除容器和卷 |
| `make logs [SERVICE=proxy]` | 跟踪服务日志 |
## 测试
### 运行测试
```
# 所有测试（381+ 项测试，82% 覆盖率）
make test
# Rust 测试
cd proxy
cargo test --all
cargo test --all -- --nocapture
cargo bench
# Python 测试
pytest agent/tests/ -v
# 负载测试（需要运行服务）
cd proxy/tests/load
./run_all_load_tests.sh
```
### 测试覆盖范围
- **单元测试**：381 个测试
- **集成测试**：覆盖所有模块的综合套件
- **属性测试**：用于生成式测试的 Proptest
- **安全测试**：授权边界测试，绕过预防
- **混沌测试**：故障注入和弹性验证
- **基准测试**：Criterion 性能测试
- **负载测试**：k6 负载测试套件
- API 负载测试（100 rps，2分钟）
- 代理清洗测试（8分钟）
- 压力测试（14分钟）
- 稳定性测试（30分钟）
- **变异测试**：每周 cargo-mutants 分析
## 文档
### 架构与设计
- [架构概述](docs/SLAPENIR_Architecture.md) - 系统设计
- [安全层级](docs/SECURITY_LAYERS.md) - 深度防御分析
- [mTLS 设置](docs/mTLS_Setup.md) - 证书管理
- [MCP 知识服务器](docs/SLAPENIR_Architecture.md) - Embedding 和知识图谱配置
- [备份策略](docs/BACKUP-STRATEGY.md) - 备份和灾难恢复
- [监控栈](monitoring/README.md) - Prometheus 和 Grafana
- [Agent 环境](agent/README.md) - Agent 配置
- [代理配置](proxy/README.md) - 代理设置
- [性能目标](proxy/PERFORMANCE.md) - SLA 和指标
- [负载测试](proxy/tests/load/README.md) - k6 负载测试套件
- [变异测试](proxy/MUTATION_TESTING.md) - 变异测试指南
### 贡献
- [贡献指南](CONTRIBUTING.md) - 开发指南
- [安全策略](SECURITY.md) - 漏洞报告
## 状态
**生产就绪** - 所有开发阶段已完成：
- 381 个测试通过（82% 覆盖率）
- 零编译器警告
- 混沌测试验证通过
- 安全审查通过
- 性能基准达标
- 集成自主开发工作流
- MCP 工具（Memory, Knowledge, Code-Graph-RAG）已运行
- 具备会话隔离的安全工作流程
**版本**：1.9.1
**最后更新**：2026-03-29
## 许可证
MIT 许可证 - 详情请见 [LICENSE](LICENSE) 文件。
## 支持
- **GitHub Issues**: https://github.com/andrewgibson-cic/slapenir/issues
- **文档**：参见 `docs/` 目录
- **安全问题**：security@slapenir.dev（仅针对安全漏洞）
标签：AI智能体, API安全, DNS 反向解析, Grafana, JSON输出, LLM代理, Memgraph, mTLS, Prometheus监控, Python, RAG, Rust, 中间人防护, 代码分析, 企业安全, 内存安全, 凭证清洗, 凭证管理, 可视化界面, 大语言模型安全, 安全网关, 敏感数据屏蔽, 无后门, 机密管理, 沙箱隔离, 流量代理, 测试用例, 版权保护, 纵深防御, 网络安全, 网络弹性, 网络流量审计, 网络资产管理, 网络隔离, 自动重启, 自定义请求头, 请求拦截, 通知系统, 隐私保护, 零信任架构, 零知识证明