1. 项目概述ClawGuard Web 安全平台如果你在 OpenClaw 生态里开发或使用技能那你肯定遇到过这样的问题从 ClawHub 或者 GitHub 上找到一个看起来很酷的技能但心里总有点打鼓——这代码安全吗会不会偷偷挖矿、窃取我的 API 密钥或者干点别的什么坏事ClawGuard Web 就是为了解决这个信任问题而生的。它是一个基于 Next.js 构建的 Web 应用核心功能是作为一个公开的“技能安全注册表”为整个 OpenClaw 加固分支fortified fork提供前置的安全检查和信任背书。简单来说ClawGuard Web 干了三件核心事第一它提供了一个公开的网站 clawguard.sh 让所有用户都能浏览、搜索已经被扫描过的技能查看它们的安全评分和详细检测报告。第二它对外提供了一套 REST API特别是那个速度极快的/api/v1/check端点专门服务于加固版 OpenClaw 的“预安装门禁”——在你安装任何技能之前它会先问一下 ClawGuard“这玩意儿安全吗”得到放行信号才会继续。第三它内置了一套完整的扫描工作流从提交 URL 到异步扫描、结果入库、生成报告全部自动化。这个项目非常适合几类人如果你是 OpenClaw 的用户想安全地探索新技能那这个公开注册表就是你的“避坑指南”。如果你是技能开发者想证明自己代码的清白可以主动提交扫描获取一个可嵌入的信任徽章SVG Badge。如果你是对应用安全、DevSecOps 或者如何构建一个带审计功能的平台感兴趣的后端或全栈开发者那么 ClawGuard Web 的架构设计、基于 Makefile 的一键化开发体验、以及扫描器集成方案都值得你仔细研究一番。接下来我会带你深入这个项目的每一个核心环节。2. 核心架构与设计思路拆解2.1 为什么选择这样的技术栈ClawGuard Web 的技术选型非常务实核心目标是快速构建一个可靠、可维护且易于部署的全栈应用。我们一层层来看。前端与框架层Next.js 16 (App Router)选择 Next.js 而不是纯 React 或其他元框架主要基于几个考量。首先Next.js 的 App Router 提供了优秀的服务端组件RSC和服务器操作Server Actions支持这对于一个内容驱动、需要频繁查询数据库并渲染动态页面的应用如技能详情页、仪表盘来说能极大地简化数据获取逻辑并提升性能。我们不需要在客户端写一堆useEffect和fetch直接在服务端组件里调用数据库查询函数就行。其次Next.js 内置的 API Routes 功能让我们能在一个项目里无缝地同时开发前端页面和后端接口如/api/v1/*部署和管理都极其方便。最后项目部署在 Vercel 上Next.js 能获得最佳的原生支持和性能优化从开发到上线链路最短。数据库与 ORM 层Drizzle ORM PostgreSQL (Neon)数据库是核心存储着所有技能、扫描结果和用户数据。PostgreSQL 是关系型数据库的可靠选择其 JSONB 类型非常适合存储结构化的扫描结果Findings。生产环境使用 Neon是因为它提供了无缝的 Serverless PostgreSQL 体验并且与 Vercel 集成良好解决了数据库连接池管理等问题。选用 Drizzle ORM 而非 Prisma 或 TypeORM是一个值得细说的决策。Drizzle 是一个“类型安全优先”的 SQL 查询构建器它更接近原生 SQL没有 Prisma 那样的运行时 schema 解析和代码生成器因此冷启动速度更快包体积更小。这对于部署在 Serverless 环境如 Vercel Functions的 API 端点至关重要能有效降低冷启动延迟和成本。同时Drizzle 的 TypeScript 支持非常出色我们能在src/lib/schema.ts中定义表结构并立刻获得完全类型安全的查询体验。这种在类型安全和性能之间的平衡是经过实际权衡后的选择。身份认证与授权Clerk可选认证是一个复杂且容易出错的部分Clerk 作为专业的 B2C 认证服务帮我们省去了自己处理 OAuth、会话管理、多因素认证等一大堆麻烦事。它的“可选”设计非常巧妙在本地开发时如果不配置 Clerk 环境变量系统会自动绕过认证并将所有用户视为管理员。这极大简化了开发前期的流程我们可以专注于业务逻辑而不必先搭建一套完整的认证系统。在生产环境中只需配置几个环境变量就能无缝切换到完整的、基于角色的访问控制RBAC其中管理员权限通过ADMIN_USER_IDS环境变量灵活配置。安全扫描核心本地集成扫描器这是 ClawGuard 的“心脏”。它没有选择调用某个远程的 SaaS 扫描服务而是将gitleaks秘密检测和semgrep静态应用安全测试SAST等命令行工具直接集成到项目中。扫描工作器Worker作为一个独立的进程或 Docker 容器运行拉取待扫描的代码仓库在本地运行这些扫描器然后解析结果并回传。这种设计的优势在于数据隐私代码无需离开你的基础设施符合内部安全审计要求。规则可控可以自定义和扩展 gitleaks 的规则集和 semgrep 的规则精准匹配 OpenClaw 技能生态的常见风险模式。成本与延迟避免了网络调用延迟和潜在的 API 调用费用。整个架构体现了“关注点分离”和“渐进式复杂度”的思想。开发初期一个make setup就能拉起所有服务随着项目增长每个模块Web 服务器、数据库、扫描工作器都可以独立扩展和部署。2.2 项目结构清晰的功能模块划分看一下项目的目录结构能很好地理解其模块化设计思想clawguard-web/ ├── Makefile # 项目入口所有开发命令的抽象 ├── registry.yaml # 核心数据默认技能注册表 ├── banlist.yaml # 核心安全策略封禁列表 ├── src/ │ ├── app/ # Next.js App Router页面和API路由 │ │ ├── api/v1/... # REST API 端点 │ │ ├── skills/[author]/[name]/page.tsx # 技能详情页 │ │ ├── dashboard/page.tsx # 数据仪表盘 │ │ └── ... │ ├── components/ # 可复用的React UI组件 │ └── lib/ # 核心业务逻辑库 │ ├── schema.ts # 数据库表结构定义 (Drizzle) │ ├── db.ts # 数据库连接池自动处理SSL │ ├── queries.ts # 所有数据库查询函数 │ ├── auth.ts # 认证授权辅助函数如 requireAdmin │ ├── registry.ts # 加载和解析 registry.yaml/banlist.yaml │ ├── security.ts # 速率限制、URL验证、HMAC签名等 │ └── scanner-client.ts # 与扫描器引擎通信的客户端 └── scripts/ ├── seed.ts # 数据库种子脚本 └── scan-worker.ts # 后台扫描工作器主逻辑这种结构的好处是显而易见的。lib目录集中了所有纯逻辑代码与 Next.js 的app路由框架解耦。这意味着这些逻辑可以很容易地被单元测试覆盖也方便在未来如果前端框架变更虽然可能性不大时进行迁移。scripts目录存放需要独立运行的 Node.js 脚本比如种子脚本和扫描工作器它们通常通过package.json中的脚本命令或 Makefile 来调用。注意关于file:依赖的特别说明。package.json中引用了yourclaw/clawguard-scanner和yourclaw/clawguard-rules这两个本地包通过file:../clawguard-scanner等方式链接。在 Vercel 上构建时必须使用--webpack配置因为 Turbopack 目前无法正确处理这种本地 symlink 依赖。这是项目Makefile和package.json中已经预设好的如果你自己部署到其他平台也需要留意这一点。3. 从零开始的本地开发环境搭建3.1 环境准备与一键初始化开始动手前你需要准备三样东西Node.js 18、Docker和Git。Node.js 是运行 Next.js 的基础Docker 用于在本地快速启动一个 PostgreSQL 数据库避免你在本机安装和配置数据库的麻烦Git 则是克隆代码仓库所必需的。拿到代码后真正的魔法始于项目根目录的Makefile。这是整个项目的“指挥中心”它用一系列简单的命令封装了所有复杂的操作。让我们运行那个神奇的初始化命令make setup这个命令背后依次执行了以下操作你可以打开Makefile对照查看安装依赖运行pnpm install项目使用 pnpm 作为包管理器安装所有 Node.js 依赖。安装扫描器运行make setup-scanners这是一个子命令它会检查并尝试安装gitleaks和semgrep的 CLI 工具。如果系统未安装它会给出提示或尝试通过包管理器如brew安装。启动数据库运行make db-start。这会启动一个名为clawguard-db的 Docker 容器运行 PostgreSQL 15并将主机的 5432 端口映射到容器的 5432 端口。数据会持久化保存在一个 Docker 卷里即使容器停止数据也不会丢失。数据库迁移运行make db-migrate。这会执行 Drizzle Kit 的db:push命令根据src/lib/schema.ts中定义的表结构在刚启动的数据库中创建所有表。数据种子运行make seed。这是最关键的一步种子脚本会做两件事扫描测试夹具Fixtures项目fixtures/目录下有一些预设的代码仓库例如包含已知漏洞的示例技能。种子脚本会调用扫描器对这些仓库进行扫描并将结果技能信息、发现的问题插入数据库。这为你提供了一个立即可见的、带有扫描数据的前端界面。导入注册表技能读取根目录的registry.yaml文件将其中的技能 URL 加入到扫描队列。注意这里只是“加入队列”实际的扫描会由后台工作器异步处理。所以刚初始化完这些技能的状态可能是“排队中”或“扫描中”。整个过程完成后你的本地环境就已经是一个功能完整的 ClawGuard 实例了包含了数据库、表结构、示例数据。接下来只需要在一个新终端运行make devNext.js 开发服务器就会在http://localhost:3000启动。打开浏览器你就能看到 ClawGuard 的首页、技能注册表并且因为本地开发默认绕过 Clerk 认证你自动拥有管理员权限可以在技能详情页看到“标记为已验证”、“屏蔽技能”等管理工具栏。3.2 数据库配置详解本地、共享与生产ClawGuard Web 在设计上就考虑到了多环境数据库的平滑切换核心秘诀在于那个DATABASE_URL环境变量。本地 Docker默认这是开发时的标准配置。make db-start命令启动的容器其连接字符串就是postgresql://postgres:postgreslocalhost:5432/clawguard。项目代码src/lib/db.ts中有一个智能判断如果DATABASE_URL的主机名是localhost或127.0.0.1则自动禁用 SSL 连接sslmode: disable否则会启用 SSL。这样你无需任何额外配置本地开发就能直连。共享 Neon 开发数据库当你需要测试涉及多用户认证、团队协作的功能时可能需要一个团队共享的数据库。Neon 提供了免费的 Serverless Postgres 分支。拿到共享的DATABASE_URL形如postgresql://user:passep-cool-breeze-123456.us-east-2.aws.neon.tech/dbname后你有两种方式使用它临时覆盖在命令行中前置环境变量来运行迁移NEON_DATABASE_URL你的连接串 make db-migrate-neon。这不会影响你本地的.env.local文件。持久化配置直接将DATABASE_URL写入你的.env.local文件。但要注意此时你需要停止本地的 Docker 数据库make db-stop因为端口 5432 可能被占用或冲突。生产环境Vercel Neon部署到 Vercel 时只需在 Vercel 项目的环境变量设置中填入从 Neon 控制台获取的生产数据库连接字符串作为DATABASE_URL。代码会自动识别这是远程连接并启用 SSL。这种“零代码修改仅换连接串”的体验得益于前期良好的抽象。实操心得数据库重置的两种姿势开发过程中经常需要清空数据库重来。记住两个命令make db-reset这是“温和重置”。它会停止并移除当前的 Docker 容器及其数据卷然后重新启动一个新容器并运行迁移。你的.env.local文件和其他项目文件不受影响。适合在数据库 schema 变更或种子数据混乱时使用。make clean-all这是“核弹重置”。它会删除node_modules、.next构建缓存、以及 Docker 数据库容器和卷。相当于把项目恢复到刚克隆时的状态除了你的代码改动。之后你需要重新运行make setup来安装一切。当你遇到非常棘手的依赖或环境问题时可以用这招。4. 核心功能实现深度解析4.1 技能注册表与封禁列表安全的第一道防线registry.yaml和banlist.yaml是两个位于项目根目录的静态 YAML 文件它们是平台安全策略的“配置文件”通过代码src/lib/registry.ts动态加载。registry.yaml公开的技能白名单这个文件定义了哪些技能会被自动加入到平台的扫描队列中相当于一个“推荐列表”或“默认关注列表”。格式非常简单skills: - url: https://clawhub.ai/author/skill-slug name: 友好的显示名称 - url: https://github.com/username/repo name: 另一个技能当运行make seed时种子脚本会读取这个文件为每个 URL 在数据库中创建一条初始的skill记录状态为unscanned并同时向scan_queue表插入一个任务。后台工作器会定时消费这个队列进行扫描。任何人都可以通过提交 Pull Request 来修改这个文件添加新的技能这体现了项目的开放性和社区驱动理念。banlist.yaml核心安全规则如果说注册表是欢迎名单那么封禁列表就是黑名单是安全审查的核心规则集。它在两个关键环节起作用用户通过网页或 API 提交扫描请求时。管理员通过管理工具将技能加入队列时。系统会实时检查提交的 URL 是否匹配封禁规则如果匹配则直接拒绝请求并可能返回一个警告信息。这实现了主动防御。封禁规则支持三种匹配策略设计得非常灵活# 1. 精确URL匹配封禁特定的、已知的恶意技能仓库。 urls: - https://github.com/evil-org/malware-skill - https://clawhub.ai/bad-actor/dangerous-skill # 2. 作者匹配不区分大小写封禁某个已知恶意作者的所有技能。 authors: - known-bad-actor - crypto-scammer # 3. 全局模式匹配Glob Pattern封禁符合某一类特征的技能。 slugs: - */crypto-miner-* # 封禁所有slug中包含‘crypto-miner-’的技能 - *-hack-* # 封禁所有slug中包含‘-hack-’的技能注意事项Glob 模式的使用这里的*匹配任意数量字符?匹配单个字符。例如*/crypto-miner-*可以匹配https://clawhub.ai/some-author/crypto-miner-v1和https://clawhub.ai/another/crypto-miner-super。规则的设计需要平衡安全性和误杀率过于宽泛的规则如*miner*可能会阻挡合法的技能。建议在添加新规则时先在测试环境用一些边缘案例验证一下。4.2 扫描工作流从提交到报告的全链路这是 ClawGuard 最核心的异步处理流程。理解它就理解了整个平台如何运转。步骤一任务提交与队列化当用户在前端/scan页面提交一个技能 URL或者registry.yaml中的技能被种子脚本处理时系统不会立即开始扫描因为扫描可能耗时较长。相反它会调用POST /api/v1/scan/queueAPI。安全检查API 首先调用isBanned(url)函数根据banlist.yaml检查该 URL 是否被封禁。如果被封禁立即返回 403 错误。创建技能记录在skills表中创建一条新记录包含作者、技能名、源 URL 等初始trust_level设为unscanned。创建队列任务在scan_queue表中插入一条新任务状态为pending并关联到刚创建的技能 ID。步骤二工作器消费与扫描扫描工作器scripts/scan-worker.ts是一个独立进程通过make workerDocker 方式或make worker-local主机方式启动。它在一个无限循环中工作每次循环称为一个“扫描周期”。声明任务工作器向 ClawGuard 实例的POST /api/v1/worker端点发送claim动作并携带WORKER_API_KEY进行认证。服务器会从scan_queue中分配一批数量由SCAN_BATCH_SIZE控制默认10个pending任务给这个工作器并将状态更新为processing。执行扫描对于每个认领的任务工作器克隆或拉取目标 Git 仓库到临时目录。依次运行集成的扫描器如gitleaks detect --source . --no-git扫描硬编码密钥semgrep scan --config auto .进行基础 SAST 扫描。解析扫描器的 JSON 输出将其标准化为 ClawGuard 内部的Finding数据结构包含类型、描述、文件路径、行号、严重等级等。提交结果工作器将扫描结果Findings 列表通过POST /api/v1/worker的complete动作回传给服务器。服务器处理结果服务器接收到结果后在skill_versions表中创建一条新的版本记录记录本次扫描的哈希、时间戳等。将所有的Finding存入findings表并关联到对应的技能版本 ID。根据预定义的规则例如存在高危漏洞则扣分无问题则加分计算该版本的安全评分并更新技能的总评分和trust_level如clean,risky,blocked。将scan_queue中对应任务的状态更新为completed。步骤三结果展示与信任决策前端页面会实时反映这些变化。技能列表页 (/skills) 会根据信任等级和评分进行排序和过滤。技能详情页 (/skills/[author]/[name]) 会展示所有历史版本的扫描结果、每个发现的问题详情以及一个可视化的安全评分趋势图。管理员可以基于这些详实的报告做出“标记为已验证”或“屏蔽技能”的决策。避坑技巧扫描器的版本与规则管理安全扫描的效果严重依赖于扫描器版本和规则集。gitleaks和semgrep都在快速迭代。建议在项目的Dockerfile或Makefile中固定扫描器的具体版本号而不是使用latest标签以确保扫描结果的可复现性。同时可以考虑将自定义的 semgrep 规则文件也纳入版本控制放在项目rules/目录下并在扫描命令中通过--config /path/to/rules指定从而实现规则集的集中管理和更新。4.3 管理员系统轻量而高效的权限控制管理员系统的设计哲学是“配置即权限”无需复杂的数据库角色表。实现的核心在于环境变量ADMIN_USER_IDS和运行时鉴权函数。配置管理员在.env.local或 Vercel 环境变量中设置ADMIN_USER_IDSuser_39RaoJP9CyG715rxbL3Gw77XzQ5,user_abc123def456这是一个用逗号分隔的 Clerk User ID 列表。要找到你的 User ID你需要在配置了 Clerk 的应用中登录。打开 Clerk Dashboard 进入 “Users” 页面。点击你的用户在详情页中复制 “User ID” 字段通常以user_开头。鉴权逻辑在src/lib/auth.ts中有一个requireAdmin函数或类似的高阶函数/中间件它被用在管理员 API 路由如PATCH /api/v1/admin/skills和前端组件如管理员工具栏中。获取当前用户通过 Clerk 的auth()或getAuth()获取当前会话用户。检查环境变量读取ADMIN_USER_IDS按逗号分割成数组。进行比对检查当前用户的 ID 是否存在于管理员 ID 数组中。逻辑降级关键点来了如果NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY或CLERK_SECRET_KEY未设置即本地开发默认情况auth()会返回一个模拟的“匿名用户”并且requireAdmin函数会直接返回true授予所有人管理员权限。这保证了开发体验的流畅。管理员操作管理员在技能详情页会看到一个额外的工具栏包含三个核心操作这些操作都调用同一个PATCH /api/v1/admin/skills端点只是action参数不同verify将技能的trust_level设置为verified。这通常用于经过人工复核确认安全的优秀技能会在 UI 上给予特殊标识如徽章。block将技能的trust_level设置为blocked。被屏蔽的技能会从公开注册表列表中隐藏并且其信任徽章会显示为“已屏蔽”。这不会自动加入banlist.yaml后者是全局的代码级规则。unblock将技能的trust_level重置为unscanned并同时将其重新加入扫描队列scan_queue。这用于对已屏蔽技能进行重新评估。5. API 设计与关键端点剖析ClawGuard Web 的 API 设计遵循 RESTful 原则所有端点都位于/api/v1/路径下返回 JSON 格式数据。这里重点剖析几个关键端点。5.1 快速信任检查端点GET /api/v1/check这是为 OpenClaw 加固分支的“预安装门禁”量身定制的高性能、低延迟端点。设计目标在用户尝试安装一个技能时OpenClaw 客户端会同步调用此接口。安装流程需要等待响应因此这个端点的响应时间必须极短目标 200ms不能进行任何耗时的操作如排队、扫描。查询参数name(必需): 技能的完整标识通常是author/skill-name格式。version(可选): 技能的具体版本号或 Git 提交哈希。如果提供则检查该特定版本否则检查该技能的最新扫描版本。实现逻辑输入验证验证name格式解析出作者和技能名。数据库查询执行一个高度优化的 SQL 查询。首先根据作者和技能名查找skills表。如果提供了version则关联skill_versions表找到该特定版本的记录否则获取最新版本的记录。决策与响应查询结果会包含技能的trust_level和score。后端根据预设的策略例如trust_level为blocked则拒绝为verified则放行为risky且分数低于阈值则警告等做出决策。响应格式{ trusted: true, // 或 false level: verified, // trust_level score: 95, reason: 技能已验证安全评分高, // 当 trustedfalse 时提供原因 last_scanned_at: 2024-01-01T00:00:00.000Z }性能优化点数据库查询必须使用索引。确保skills表在(author, name)上有复合索引skill_versions表在(skill_id, scanned_at)上有索引。避免在请求处理函数中进行任何复杂的计算或外部调用。可以考虑对高频查询的技能结果进行短期缓存例如使用 Redis 或内存缓存缓存 5-10 分钟但要注意缓存失效问题当技能被重新扫描或管理员操作后需清除缓存。5.2 扫描队列与工作器通信端点POST /api/v1/worker这是一个“内部”API专供扫描工作器使用实现了简单的作业队列协议。它使用WORKER_API_KEY进行认证确保只有授权的扫描器才能调用。支持的action:ping: 工作器启动时调用用于检查与服务器的连通性和认证是否正常。claim: 工作器请求认领一批待处理任务。服务器返回一个任务列表包含技能 URL、仓库信息等。complete: 工作器上报扫描成功完成并提交findings数据。fail: 工作器上报扫描失败并提交错误信息。stale: 服务器端可以调用或由定时任务触发用于将长时间处于processing状态的任务标记为“陈旧”可能因为工作器崩溃并将其状态重置为pending以便其他工作器重试。关键实现细节以claim为例:// 伪代码位于 API 路由处理函数中 if (action claim) { const batchSize parseInt(req.query.batchSize) || 10; // 使用事务确保并发安全 const tasks await db.transaction(async (tx) { const pendingTasks await tx.select().from(scanQueue) .where(eq(scanQueue.status, pending)) .limit(batchSize) .forUpdate(); // 行级锁防止被其他工作器同时认领 const taskIds pendingTasks.map(t t.id); if (taskIds.length 0) { await tx.update(scanQueue) .set({ status: processing, claimedBy: workerId, claimedAt: new Date() }) .where(inArray(scanQueue.id, taskIds)); } return pendingTasks; }); return NextResponse.json({ tasks }); }这里使用了SELECT ... FOR UPDATE或类似的行锁机制和事务这是实现可靠分布式任务队列的经典模式能防止多个工作器同时认领同一个任务。5.3 信任徽章端点GET /api/v1/badge/:slug这个端点生成动态的 SVG 图像允许技能开发者将 ClawGuard 的信任状态嵌入到他们的 GitHub README 或 ClawHub 技能页面中提升透明度。实现原理根据:slug参数通常是author/skill-name格式查询数据库获取技能的trust_level和score。根据信任等级选择对应的颜色和文本标签。例如verified: 绿色 (#34D399)“Verified”clean: 蓝色 (#60A5FA)“Clean”risky: 橙色 (#FBBF24)“Risky”blocked: 红色 (#F87171)“Blocked”unscanned: 灰色 (#9CA3AF)“Unscanned”使用一个 SVG 模板库如badge-makerNPM 包或直接拼接 SVG 字符串生成一个包含颜色、文本和分数的盾牌样式徽章。设置正确的 HTTP 头Content-Type: image/svgxml和适当的缓存头如Cache-Control: public, max-age300因为徽章状态不会频繁变化缓存可以减轻服务器压力。使用方式 开发者只需在 Markdown 中插入徽章就会自动显示该技能当前的安全状态。这是一个非常有效的“安全状态可视化”和“社区信誉”工具。6. 部署指南与生产环境考量6.1 Vercel 部署详解项目已经为 Vercel 部署做了充分优化。部署流程非常标准连接仓库在 Vercel 控制台导入你的 GitHub/GitLab 仓库。配置环境变量这是最关键的一步。在 Vercel 项目的Environment Variables设置中添加所有必要的变量DATABASE_URL: 你的 Neon 生产数据库连接字符串。NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY: 来自 Clerk 生产环境的应用密钥。ADMIN_USER_IDS: 生产环境管理员的 Clerk User ID。WORKER_API_KEY: 一个高强度的随机字符串用于扫描工作器认证。务必保密。CRON_SECRET: 如果你使用了 Vercel Cron Jobs 来触发定期任务如清理陈旧扫描任务需要设置此密钥进行端点保护。ANTHROPIC_API_KEY可选如果启用了 AI 辅助审查功能需要提供。构建配置项目package.json中的build脚本已经是next build --webpack确保了本地file:依赖能被正确解析。Vercel 会自动使用此脚本。自定义域名按照 Vercel 的指引将你的域名如clawguard.sh指向 Vercel 提供的 DNS 记录。6.2 扫描工作器的生产部署扫描工作器 (scripts/scan-worker.ts) 是一个长期运行的后台进程不能部署在 Serverless 函数上因为函数有执行时长限制。你需要为其准备一个常驻的运行环境。方案一专用服务器或 VPS这是最直接的方式。在一台云服务器上克隆代码运行make setup安装依赖和扫描器 CLI。配置环境变量文件.env.production设置CLAWGUARD_URL指向你的生产实例 URL和WORKER_API_KEY。使用进程管理工具如systemd,pm2,supervisor来运行pnpm run worker或make worker-local并配置日志轮转和故障重启。方案二Docker 容器化部署项目已经提供了Dockerfile和make worker命令这为容器化部署铺平了道路。构建 Docker 镜像docker build -t clawguard-worker .运行容器并通过-e传递环境变量docker run -d \ --name clawguard-worker \ -e CLAWGUARD_URLhttps://your-production-domain.com \ -e WORKER_API_KEYyour-secure-api-key \ -e SCAN_INTERVAL_MS300000 \ clawguard-worker使用 Docker Compose 或 Kubernetes 来管理容器的生命周期、健康检查和滚动更新。方案三托管容器服务如果你不想管理服务器可以考虑使用 Google Cloud Run、AWS Fargate 或 Fly.io 等托管容器服务。它们可以运行 Docker 容器并根据负载自动伸缩。你需要将构建好的镜像推送到容器注册表如 Docker Hub、GHCR然后在这些服务中配置运行。生产环境安全加固建议密钥管理切勿将WORKER_API_KEY、CLERK_SECRET_KEY、数据库密码等硬编码在代码或镜像中。使用 Vercel Secrets、AWS Secrets Manager、HashiCorp Vault 或环境变量注入。网络隔离如果扫描的代码仓库涉及内部私有库确保扫描工作器运行在可以访问这些仓库的网络环境中同时其对外访问应受到限制。资源限制为扫描工作器容器设置 CPU 和内存限制防止恶意或异常代码仓库耗尽资源。日志与监控确保工作器的日志被收集可输出到stdout/stderr并由 Docker 或系统收集并设置监控告警当工作器长时间未拉取到任务或失败率过高时通知管理员。7. 常见问题排查与实战技巧在实际开发和运维中你可能会遇到以下问题。这里记录了我踩过的一些坑和解决方法。7.1 数据库连接问题问题运行make dev或访问页面时出现Database connection failed或relation \skills\ does not exist错误。排查步骤检查 Docker 容器运行docker ps确认clawguard-db容器正在运行。如果没有运行make db-start。检查端口冲突PostgreSQL 默认使用 5432 端口。运行lsof -i :5432查看是否被其他程序占用。如果占用可以修改Makefile中db-start命令的端口映射如-p 5433:5432并同步更新.env.local中的DATABASE_URL。检查迁移状态容器可能启动了但表没创建。运行make db-migrate来应用 schema。如果失败查看 Drizzle 输出的错误信息。重置数据库如果表结构混乱最简单的方法是make db-reset它会清理并重建一切。7.2 扫描器相关故障问题种子脚本或工作器扫描失败日志显示Command failed: gitleaks或semgrep: command not found。排查步骤验证安装运行make setup-check它会检查gitleaks和semgrep是否在系统路径中。手动安装如果缺失根据make setup-scanners里的逻辑或参考官方文档手动安装。例如在 macOS 上可以用brew install gitleaks semgrep。Docker 工作器如果使用make workerDocker 方式扫描器是预装在镜像里的。如果失败检查 Docker 镜像是否构建正确或者尝试docker run --entrypoint sh your-image -c \which gitleaks\来验证。权限问题确保扫描器二进制文件有可执行权限。问题扫描结果为空或不符合预期。排查步骤检查规则gitleaks和semgrep的检测能力取决于规则集。默认的semgrep --config auto使用的是通用规则。对于 OpenClaw 技能特有的风险模式如特定的恶意 API 调用你需要编写或引入自定义规则。检查项目是否在clawguard-rules包中提供了自定义规则并确保扫描命令正确引用了它们。查看详细日志修改scripts/scan-worker.ts或扫描器调用代码增加调试日志打印出扫描器的完整命令和原始输出以确定是扫描器没发现问题还是结果解析出了问题。测试已知漏洞使用fixtures/目录下的测试用例进行扫描确认扫描器能正确检测出预设的问题。7.3 认证与管理员权限问题问题在生产环境或配置了 Clerk 的本地环境管理员操作按钮不显示或 API 返回 403。排查步骤确认 Clerk 配置检查浏览器控制台是否有 Clerk 相关的错误。确保NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY已正确设置且匹配开发/生产环境不要混用。检查用户 ID在 Clerk Dashboard 中确认你登录的用户 ID并与ADMIN_USER_IDS环境变量中的值进行精确比对包括大小写和所有字符。最好直接从 Dashboard 复制粘贴。环境变量加载确保环境变量已正确加载。在 Next.js 中以NEXT_PUBLIC_开头的变量会在前端可用其他的只在服务端可用。ADMIN_USER_IDS只在服务端使用所以修改后需要重启开发服务器 (make dev)。查看服务端日志在 API 路由的requireAdmin函数中添加console.log打印出当前用户 ID 和配置的管理员 ID进行比对调试。7.4 性能优化与监控随着技能数量增长一些端点可能会变慢。/skills列表页加载慢原因可能一次性查询了所有技能及其最新版本、评分并进行了复杂的排序和过滤。优化分页API 实现limit和offset或cursor参数前端实现无限滚动或分页器。数据库索引确保skills表在trust_level、score、updated_at等常用过滤和排序字段上建立了索引。选择性加载列表页可能不需要加载每个技能的完整findings只查询skills和skill_versions表的基本信息即可。/api/v1/check端点延迟高原因数据库查询或网络延迟。优化查询优化使用EXPLAIN ANALYZE分析查询计划确保使用了索引。引入缓存如前所述对查询结果进行短期内存缓存。可以使用lru-cache这样的库键为技能名版本值为信任决策结果设置 5-10 分钟的 TTL。注意在技能被重新扫描或管理员操作后手动使缓存失效。扫描队列积压原因提交的扫描任务多于工作器的处理能力。监控与扩容监控队列长度可以创建一个简单的管理仪表盘或者定期查询SELECT COUNT(*) FROM scan_queue WHERE status pending。增加工作器实例如果使用容器化部署可以轻松增加工作器容器的副本数。确保你的任务认领逻辑 (claimaction) 能支持多个工作器并发工作使用行锁是安全的。调整扫描策略对于来自公开注册表 (registry.yaml) 的技能可以降低扫描优先级或频率。对于用户主动提交的扫描可以优先处理。7.5 开发与调试技巧使用make worker-local进行调试make worker在 Docker 容器内运行查看日志和调试不太方便。在开发扫描逻辑或规则时使用make worker-local在主机上直接运行工作器。你可以在scripts/scan-worker.ts中任意位置添加console.log或使用 Node.js 调试器。直接修改扫描命令或参数快速测试。观察工作器对单个任务的处理全过程。利用测试夹具Fixturesfixtures/目录是你的“安全漏洞实验室”。里面应该包含各种典型的“坏代码”示例如硬编码的密钥、危险的eval调用、可疑的网络请求等。在修改扫描规则或解析逻辑后运行make seed-force它会强制重新扫描所有夹具来验证你的修改是否能正确检测出这些已知问题。这是确保扫描能力不退化的重要回归测试手段。模拟极端情况尝试向封禁列表 (banlist.yaml) 添加一些规则然后通过网页或 API 提交匹配的 URL测试封禁逻辑是否立即生效。尝试提交一个非常大的 Git 仓库观察工作器的内存和超时处理。这些测试能帮助你发现架构中的潜在弱点。