SafePaw Gateway：为自托管AI助手构建开箱即用的安全边界

1. 项目概述：为自托管AI助手构建安全边界

如果你正在本地运行像OpenClaw这样的AI助手后端，并且已经意识到它默认暴露在网络上，没有任何身份验证或防护措施，那么SafePaw Gateway就是你一直在寻找的解决方案。这不是一个简单的反向代理，而是一个开箱即用的、经过深度加固的安全网关。它解决了自托管AI应用中最棘手的问题：如何在不成为安全专家的前提下，为你的AI服务套上一套完整的安全盔甲。

大多数自托管AI后端，包括OpenClaw，其设计初衷是功能优先，安全特性往往是可选的，并且分散在各种配置文档中。这意味着你需要手动设置身份验证、配置速率限制、研究如何防御SSRF（服务器端请求伪造）和暴力破解攻击。现实情况是，绝大多数个人开发者和小团队都会跳过这些繁琐的步骤，直接让服务暴露在风险中。SafePaw的核心设计哲学就是让安全成为默认路径。它通过一个用Go编写的、经过534次测试验证的反向代理网关，以及一个用于管理和监控的React向导界面，将你的AI后端包裹在一个坚固的本地安全边界内。所有组件都通过Docker Compose一键部署，安全特性全部默认开启。

你可以把它想象成为你家的AI服务栈安装的一套“智能门锁系统”。它预装了门锁（HMAC身份验证）、门禁记录（审计日志）、防撬警报（暴力破解防护）和包裹扫描仪（提示词注入检测）。你不需要自己去研究锁芯结构、购买报警器再组装调试，SafePaw已经为你配置、测试好了一切，拧上螺丝就能用。这并不是说你的AI后端本身不安全，而是因为从头开始加固它，需要大多数人不具备的专业知识，以及没人愿意花费的大量时间。

2. 核心架构与设计思路拆解

2.1 为什么选择“网关+向导”的架构？

SafePaw采用了经典的“控制平面”与“数据平面”分离的架构思想，这在高性能网络和安全系统中非常常见。网关（Gateway）作为数据平面，专注于高性能、低延迟地处理所有进出AI后端的HTTP/WebSocket流量，并执行核心的安全策略，如认证、限流和扫描。它被设计成无状态的（状态存储在Redis中），这使其易于水平扩展，并且故障恢复迅速。

向导（Wizard）则作为控制平面，为管理员提供了一个集中式的管理界面。它的职责不是处理用户请求，而是配置网关、查看监控指标、管理审计日志和进行系统设置。这种分离带来了几个关键优势：首先，它将管理流量与业务流量隔离，避免了管理操作影响核心服务的性能或安全性；其次，即使向导服务暂时不可用，网关也能继续安全地转发流量，保证了业务的高可用性；最后，这种架构使得每个组件的职责单一，代码更清晰，也更容易进行独立的安全审计和测试。

2.2 深度防御策略：从边界到内核

SafePaw的威胁模型基于STRIDE方法论，识别了48种潜在威胁，并围绕“深度防御”原则构建了多层安全机制。这就像一座城堡的防御体系：

1. 外围护城河（网络层隔离）：通过Docker Compose的默认配置，只有网关（端口8080）和向导（端口3000）被暴露在127.0.0.1（即本机回环地址）。你的AI后端（如OpenClaw）、Redis和Postgres数据库都运行在内部的Docker网络中，外部网络根本无法直接访问。这是第一道也是最基础的物理隔离防线。

2. 城门守卫（身份验证与授权）：所有到达网关的请求必须携带有效的HMAC-SHA256签名。这比简单的API密钥或JWT（JSON Web Token）更安全，因为它能防止请求在传输过程中被篡改。网关会校验签名、检查令牌是否在Redis的撤销列表中、并验证请求的时效性（防止重放攻击）。对于向导的管理登录，除了密码外，还支持可选的TOTP（基于时间的一次性密码）双因素认证。

3. 城内巡逻（速率限制与暴力破解防护）：网关对每个源IP地址实施请求速率限制。当某个IP在短时间内发起大量失败的身份验证请求时，系统会将其识别为暴力破解攻击，并自动将该IP加入临时或永久的禁令列表。这一切都通过Redis实现，响应迅速且可以跨多个网关实例共享状态（如果未来需要扩展）。

4. 货物检查（输入/输出内容扫描）：这是针对AI应用特有的安全层。输入扫描器会检查HTTP请求体，使用14种预定义的正则表达式模式来探测常见的提示词注入（Prompt Injection）攻击模式，例如试图让AI忽略之前指令的语句。输出扫描器则检查HTTP响应，尝试剥离可能存在的跨站脚本（XSS）攻击代码或意外泄露的敏感信息（如密钥）。需要特别注意的是，出于技术限制（修改WebSocket二进制帧的负载而不更新帧头会导致流损坏），对WebSocket流的扫描仅限于记录日志，而不会进行拦截或修改。这是一个明确的设计权衡，在架构文档中有详细说明。

5. 审计与监控（可观测性）：所有安全相关事件，如登录成功/失败、令牌撤销、扫描器告警、IP封禁等，都会以结构化的JSON格式记录日志，并存入Postgres数据库供向导界面查询。同时，网关暴露Prometheus指标，可以轻松集成到Grafana仪表板中，实时监控请求量、延迟、错误率和安全事件。

注意：SafePaw是一个传输层安全边界。它专注于保护客户端与AI后端之间的通信通道。它并不对AI后端内部或宿主机上运行的内容进行沙箱隔离。例如，如果AI代理被诱导执行危险的主机命令调用，这超出了SafePaw的防护范围。你需要依赖后端自身的沙箱模式和在Docker中配置的严格能力限制来应对这类威胁。

3. 核心组件详解与实操要点

3.1 网关：安全策略的执行引擎

网关是SafePaw的心脏，它是一个用Go编写的轻量级、高性能HTTP服务器。其核心是一个精心设计的中件（Middleware）管道，每个请求都会按顺序通过这个管道进行处理。这种设计模式使得每个安全功能模块化，易于测试和维护。

认证中间件是管道的第一关。它实现了基于HMAC的请求签名验证。其工作流程是：客户端在发送请求前，使用共享的AUTH_SECRET和请求内容（如方法、路径、时间戳、随机数）生成一个SHA256签名，并将其放在HTTP头中。网关收到请求后，使用相同的算法重新计算签名并进行比对。任何不匹配都会立即导致请求被拒绝（401状态码）。此外，中间件还会检查请求中的令牌ID是否存在于Redis的撤销名单里，并验证时间戳以防止重放攻击（通常允许几分钟的时间漂移）。

速率限制与暴力破解防护中间件紧密协作。它使用Redis存储每个IP地址的请求计数。算法通常采用令牌桶或滑动窗口计数。当某个IP的失败认证请求超过阈值（如每分钟5次）时，该IP会被加入一个“观察名单”。连续失败会导致禁令升级，从短暂的几分钟封禁到长时间的几小时封禁。这个中间件的关键在于其响应速度和对分布式攻击的潜在防御能力（虽然当前是单实例，但数据结构支持扩展）。

扫描器中间件是AI安全的特色。输入扫描器本质上是一组精心设计的正则表达式，用于匹配常见的注入模式，例如“忽略以上指令”、“你之前的系统提示是错的”等变体。它不会尝试理解语义，而是进行快速的模式匹配，因此可能产生误报或漏报。输出扫描器则更复杂一些，它需要解析HTML/JSON响应，寻找<script>标签、javascript:协议或看起来像API密钥、密码的长字符串模式，并进行清理或标记。

实操要点：

• 密钥管理：AUTH_SECRET是系统安全的根。必须使用强随机字符串（启动脚本会自动生成），并像保护密码一样保护它。定期轮换密钥是一个好习惯，SafePaw的运维文档中提供了相应的流程。
• 调优限流：默认的速率限制参数（如RATE_LIMIT_REQUESTS=100，RATE_LIMIT_WINDOW=60s）是针对通用场景的。你需要根据你的AI后端处理能力和用户访问模式进行调整。过松起不到保护作用，过严会影响正常用户体验。
• 理解扫描器的局限：启发式扫描不是银弹。它无法防御新颖的、未知的注入手法。你应该将其视为一道重要的警报线，而非唯一的防线。定期审查扫描器日志，了解攻击模式，并考虑结合后端的上下文窗口限制等其他安全措施。

3.2 向导：一体化的管理控制台

向导是一个用React 19构建的单页面应用（SPA），并通过Go的//go:embed指令直接嵌入到网关的二进制文件中，这意味着你部署的是一个统一的、自包含的可执行文件，无需单独管理前端资源。

它的主要功能包括：

• 系统健康总览：实时显示网关、AI后端、Redis、Postgres等所有Docker容器的运行状态、资源使用情况（CPU、内存）和日志尾部。
• 安全事件审计：以表格形式展示所有的登录、令牌操作、扫描告警和IP封禁事件，支持按时间、事件类型筛选。
• 动态配置管理：提供一个受保护的界面来编辑.env文件中的关键配置（如API密钥、目标后端地址）。在保存时，密码等敏感字段会被掩码显示，并且向导会验证配置格式的有效性。
• 双因素认证管理：如果启用了TOTP，管理员可以在此界面查看绑定状态或重新生成二维码。

一个关键的设计细节是身份验证的分离：用户访问AI服务使用HMAC签名认证，而管理员登录向导使用独立的密码（和可选的TOTP）。这两套凭证体系完全分开，避免了权限混淆。向导的会话通过HTTP-only的Cookie来维护，有效防止了客户端JavaScript的XSS攻击窃取会话。

3.3 Docker Compose栈：可复现的隔离环境

SafePaw通过一个docker-compose.yml文件定义了完整的五服务栈，这是实现“一键部署”和“环境一致性”的基石。

version: '3.8' services: wizard: build: ./services/wizard ports: - "127.0.0.1:3000:3000" env_file: .env depends_on: gateway: condition: service_healthy # ... 其他配置如健康检查、资源限制 gateway: build: ./services/gateway ports: - "127.0.0.1:8080:8080" env_file: .env depends_on: redis: condition: service_healthy postgres: condition: service_healthy # ... 其他配置 openclaw: # 或你的自定义后端 image: your-ai-backend-image # 注意：没有ports映射，仅内部网络访问 networks: - safepaw_internal redis: image: redis:7-alpine # 仅内部网络，启用持久化 volumes: - redis_data:/data postgres: image: postgres:15-alpine # 仅内部网络，初始化脚本 volumes: - postgres_data:/var/lib/postgresql/data - ./init.sql:/docker-entrypoint-initdb.d/init.sql networks: safepaw_internal: internal: true # 关键！禁止外部访问 volumes: redis_data: postgres_data:

这个配置的精髓在于网络隔离。我们创建了一个名为safepaw_internal的Docker网络，并将其标记为internal: true。这意味着只有同样连接到此网络的容器（即本Compose文件中的服务）可以相互通信，而宿主机或其他外部网络无法访问它。然后，我们只将wizard和gateway服务的端口映射到宿主的127.0.0.1。这样，从外部看，只有这两个端口是开放的，并且只对本机可见。openclaw、redis、postgres则安全地隐藏在内网中，网关通过服务名（如openclaw:18789）在内部网络中访问它们。

实操要点：

• 资源限制：Compose文件为每个服务定义了CPU和内存限制（如deploy.resources.limits），防止某个容器失控拖垮整个宿主。启动脚本会根据你系统的总内存自动选择“small”、“medium”等预设配置。
• 健康检查：每个服务都配置了HTTP或命令式的健康检查。Docker会据此判断容器是否就绪，depends_on中的condition: service_healthy确保了依赖服务的启动顺序和可用性。
• 数据持久化：Redis和Postgres的数据通过Docker命名卷（redis_data,postgres_data）持久化，即使容器重建，数据也不会丢失。备份和恢复流程在BACKUP-RECOVERY.md中有详细说明。

4. 从零开始的完整部署与配置实战

4.1 环境准备与一键启动

部署SafePaw的前提非常简单：一台安装了Docker和Docker Compose V2的机器（Windows, macOS, Linux均可），并且确保本机的3000和8080端口未被占用。

最快速的体验方式是使用项目提供的启动脚本。它会自动处理所有繁琐的初始化工作。

# 1. 克隆仓库 git clone https://github.com/beautifulplanet/SafePaw.git cd SafePaw # 2. 运行启动脚本 (Linux/macOS) chmod +x LAUNCH.sh # 首次运行可能需要添加执行权限 ./LAUNCH.sh # 在Windows上，直接双击运行 `LAUNCH.bat`

运行脚本后，你会看到一个交互式菜单。对于首次体验，强烈建议选择选项2（Demo模式）。这个模式会使用一个内置的模拟后端，你不需要准备任何AI API密钥（如OpenAI的密钥），就能完整体验SafePaw的所有管理功能和安全特性。

脚本会依次执行以下操作：

1. 检查依赖：确认Docker和Docker Compose已安装且版本合适。
2. 生成密钥：如果不存在.env文件，脚本会复制.env.example并为其中的所有空白密码（如POSTGRES_PASSWORD、REDIS_PASSWORD、AUTH_SECRET）生成强随机字符串。这是安全默认值的关键一步。
3. 检测系统配置：根据你机器的总内存，自动设置SYSTEM_PROFILE环境变量，以调整Docker容器的资源限制，避免在小内存机器上崩溃。
4. 构建并启动：运行docker compose up -d --build，构建网关和向导的镜像，并启动所有五个服务。
5. 等待与引导：脚本会轮询服务的健康检查端点，直到所有服务就绪。然后，它会在终端打印出向导的登录密码，并自动打开你的默认浏览器，访问http://localhost:3000。

4.2 连接你自己的AI后端

Demo模式很棒，但我们的目标是为自己的AI服务提供保护。假设你已经在本地18789端口运行了一个OpenClaw实例（或者任何其他兼容OpenAI API的服务器）。你需要修改配置，让SafePaw网关将请求转发给它。

步骤一：编辑环境变量停止当前运行的服务（在启动脚本菜单中选择关闭，或运行docker compose down）。然后，编辑项目根目录下的.env文件。最关键的两个变量是：

# .env 文件示例 PROXY_TARGET=http://openclaw:18789 # 这是Docker内部网络地址。如果你的后端是另一个独立容器或进程，需确保它在同一Docker网络或可被网关访问。 # 或者，如果你的后端运行在宿主机的另一个端口（例如 18000），且不在Docker内，你可以使用宿主机的特殊DNS： # PROXY_TARGET=http://host.docker.internal:18000 # 安全相关配置，启动脚本已生成，请务必保存好 AUTH_SECRET=your_super_strong_generated_secret_here WIZARD_PASSWORD=your_admin_password_here # AI服务所需的API密钥（如果需要） OPENAI_API_KEY=sk-... # 或其他LLM供应商的密钥

步骤二：调整Docker Compose配置默认的docker-compose.yml包含一个openclaw服务定义。如果你已经有自己的后端，你有两个选择：

1. 使用自己的服务替换：在docker-compose.yml中，将openclaw服务的image或build指向你的自定义镜像，并确保其网络配置在safepaw_internal网络内。
2. 完全移除该服务：如果你在宿主机或其他地方运行后端，可以注释掉或删除openclaw服务定义，并确保PROXY_TARGET指向正确的可达地址（如http://host.docker.internal:18000）。

步骤三：重新启动保存更改后，再次运行启动脚本（选择“Full”模式），或直接运行docker compose up -d。网关现在会将经过认证和扫描的请求转发到你指定的PROXY_TARGET。

4.3 验证部署与基础测试

服务启动后，如何进行基础的健康和功能验证？

1. 服务健康检查：

# 检查向导服务是否响应 curl -s http://localhost:3000/api/v1/health | jq . # 期望返回：{"status":"ok","version":"..."} # 检查网关服务是否响应 curl -s http://localhost:8080/health | jq . # 期望返回：{"status":"ok","timestamp":"..."}

如果返回正常，说明核心服务已启动。

2. 访问管理向导：打开浏览器，访问http://localhost:3000。使用启动时打印在终端或.env文件中WIZARD_PASSWORD对应的密码登录。登录后，你应该能看到仪表板，上面显示了所有服务的运行状态（绿色为健康）。

3. 测试网关代理功能：首先，你需要生成一个有效的HMAC签名来调用网关。SafePaw项目通常会在/scripts目录下提供示例客户端代码。这里提供一个概念性的Python示例，展示签名逻辑：

import hashlib import hmac import time import requests def generate_hmac_signature(secret: str, method: str, path: str, body: bytes = b"") -> str: timestamp = str(int(time.time())) nonce = "random123" # 实际应用中应使用随机数 message = f"{method}\n{path}\n{timestamp}\n{nonce}\n".encode() + body signature = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest() return f"HMAC {timestamp}:{nonce}:{signature}" auth_secret = "your_auth_secret_from_env" # 从.env文件的AUTH_SECRET获取 api_url = "http://localhost:8080/v1/chat/completions" # 网关地址 + 后端API路径 headers = { "Authorization": generate_hmac_signature(auth_secret, "POST", "/v1/chat/completions"), "Content-Type": "application/json" } data = { "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello"}] } response = requests.post(api_url, json=data, headers=headers) print(response.status_code, response.json())

一个成功的请求会通过网关，转发到你的AI后端，并将后端的响应返回给你。你可以同时在向导的审计日志中看到这次请求的记录。

5. 运维、监控与故障排查实录

5.1 日常监控与日志分析

SafePaw内置了强大的可观测性工具，帮助你掌握系统状态。

• Grafana仪表板：项目提供了Grafana的仪表板定义文件。你可以部署一个Grafana容器，将其添加到safepaw_internal网络，并配置Prometheus（网关已暴露/metrics端点）作为数据源。这样就能可视化地监控每秒请求数（RPS）、请求延迟分布（P50, P95, P99）、各中间件的处理耗时、以及安全事件（如扫描告警、IP封禁）的触发频率。
• 结构化日志：网关和向导的所有日志都输出为JSON格式，非常便于使用jq命令进行过滤和分析，或者导入到ELK（Elasticsearch, Logstash, Kibana）等日志系统中。

  # 查看网关最近的错误日志 docker compose logs gateway --tail 100 | grep '"level":"error"' | jq . # 统计过去一小时内被封锁的IP地址 docker compose logs gateway --since 1h | grep 'IP banned' | jq -r '.ip' | sort | uniq -c

• 审计日志：所有关键的安全和管理操作都记录在Postgres数据库的audit_logs表中。你可以通过向导界面查看，也可以直接连接数据库进行复杂查询，例如查找某个用户的所有操作，或统计某种类型安全事件的趋势。

5.2 常见问题与排查指南

在实际部署和运行中，你可能会遇到以下典型问题。这里提供一套排查思路。

问题1：启动脚本失败，提示“Docker not running”或“Compose not found”。

• 排查：首先在终端运行docker --version和docker compose version，确认Docker守护进程已启动且Compose插件已安装（Docker Desktop通常自带）。在Linux上，可能需要单独安装docker-compose-plugin包。
• 解决：根据你的操作系统，启动Docker Desktop或相应的服务（如sudo systemctl start docker）。确保当前用户有权限执行Docker命令（通常需要加入docker用户组）。

问题2：服务启动后，向导页面能打开，但网关健康检查失败或AI请求返回502/504错误。

• 排查：
  1. 运行docker compose ps，确认所有服务状态均为“Up (healthy)”。如果有服务不健康，查看其日志：docker compose logs [service_name]。
  2. 最常见的原因是PROXY_TARGET配置错误。进入网关容器内部测试连通性：

     docker compose exec gateway sh # 在容器内执行 apk add curl # 如果容器内没有curl curl -v http://openclaw:18789/health # 替换为你的实际目标地址

  3. 检查网关日志，看是否有连接被拒绝或超时的错误信息。
• 解决：修正PROXY_TARGET的地址。确保目标服务正在运行且监听正确端口。如果目标服务在宿主机，使用host.docker.internal（Mac/Windows）或宿主机的桥接IP（Linux，如172.17.0.1）。

问题3：客户端调用网关API始终返回“401 Unauthorized”。

• 排查：
  1. 确认客户端使用的AUTH_SECRET与.env文件中的AUTH_SECRET完全一致，包括首尾空格。
  2. 检查签名生成算法。确保签名字符串的组成部分（HTTP方法、路径、时间戳、随机数、请求体）拼接顺序与网关校验逻辑完全一致。一个常见的错误是请求体（body）的编码或空格处理不一致。
  3. 检查请求头中的Authorization格式是否正确，应为HMAC <timestamp>:<nonce>:<signature>。
  4. 查看网关日志，通常会记录认证失败的具体原因，如“invalid signature”、“token revoked”或“timestamp expired”。
• 解决：使用项目提供的标准客户端库或示例代码来生成签名。手动计算时，务必逐字节比对签名字符串。确保客户端和服务器的时间同步（NTP）。

问题4：扫描器频繁误报，拦截了正常请求。

• 排查：在向导的审计日志中查看被拦截的请求详情，特别是触发告警的“匹配模式”。有些正常的用户输入可能偶然包含了与注入模式相似的词语。
• 解决：启发式扫描器必然存在误报率。你可以：
  • 调整模式：对于已知的安全误报，可以修改services/gateway/middleware/input_scanner.go中的正则表达式模式，使其更精确。但这需要谨慎，避免引入漏洞。
  • 豁免路径：如果某个特定的API端点（如文件上传）不需要内容扫描，可以在网关的路由配置中，将该路径排除在扫描中间件之外。
  • 记录而非拦截：在测试阶段，可以将扫描器模式设置为“仅记录（Log Only）”，观察一段时间，了解正常流量的模式，再决定是否开启拦截。

问题5：系统运行一段时间后，响应变慢或内存占用高。

• 排查：
  1. 使用docker stats命令查看各容器的实时资源使用情况。
  2. 检查Redis和Postgres的日志，看是否有慢查询或连接数暴涨。
  3. 查看网关的Prometheus指标，关注请求队列长度、垃圾回收（GC）暂停时间。
• 解决：
  • 调整资源限制：根据docker stats的观察，在docker-compose.yml中适当增加gateway或openclaw服务的mem_limit和cpus。
  • 优化Redis/Postgres：检查是否有大量的密钥未设置过期时间，或审计日志表过大。可以为审计日志表设置自动分区或归档策略。
  • 审视流量：是否遭遇了爬虫或低效的客户端？速率限制和IP封禁日志会给你线索。

5.3 备份、恢复与升级

备份：SafePaw的数据主要存在于两个地方：Postgres数据库和Redis。项目提供的BACKUP-RECOVERY.md文档包含了详细的脚本。

• Postgres：使用pg_dump命令导出数据库。

  docker compose exec postgres pg_dump -U safepaw safepaw_db > backup_$(date +%Y%m%d).sql

• Redis：可以保存RDB或AOF文件，更简单的方式是使用SAVE或BGSAVE命令后，备份Docker卷对应的物理文件（位于/var/lib/docker/volumes/...）。
• 关键配置文件：备份整个项目目录，尤其是.env文件。丢失AUTH_SECRET会导致所有现有客户端令牌失效。

恢复：恢复过程基本上是备份的逆操作。停止服务，替换数据卷或导入SQL文件，然后重新启动。务必在测试环境验证恢复流程。

升级：由于采用容器化部署，升级相对简单。

1. 拉取最新的项目代码：git pull origin main。
2. 备份当前数据和.env文件。
3. 运行docker compose down停止旧服务。
4. 运行docker compose up -d --build重新构建并启动。Docker会使用新的代码构建镜像，并启动新容器。
5. 密切观察启动日志和健康检查，确保新版本平稳运行。

在长达数月的实际使用和测试中，SafePaw展现出了作为自托管AI安全基石的可靠性。它的价值不在于用了多么高深的技术，而在于将一系列最佳安全实践产品化、默认化。它迫使你在享受AI助手便利的同时，不得不考虑安全，而这种“不得不”正是当前许多个人项目所缺乏的。最让我欣赏的是其清晰的边界感：它明确告知你哪些威胁它能防，哪些不能（如WebSocket流的实时修改），这种坦诚让架构师能够准确地评估剩余风险，并在其他层面（如主机安全、AI后端沙箱）进行补充。如果你正严肃地对待自托管AI的安全性，却又苦于没有足够的精力去从头搭建每一道防线，那么将SafePaw作为你的安全起点，无疑是一个高效而明智的选择。