mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 11:13:43 +08:00
9e33782b7d
* feat(browser): 放开内网服务访问限制，新增局域网部署模式开关 ### 背景 局域网部署时，Agent 用浏览器工具访问 http://192.168.x.x:port 等内网服务会被默认 SSRF 严格模式拦截。 ### 方案 新增两个 .env 开关（默认 false，行为与改动前完全一致）： - PLAYWRIGHT_ALLOW_PRIVATE_NETWORK=true ：放行本地回环和私有 IP，云元数据端点仍拦截 - PLAYWRIGHT_IGNORE_HTTPS_ERRORS=true ：忽略 HTTPS 证书错误（自签证书场景） 顺带修复 IPv6 AWS IMDS 网段 fd00:ec2::/64 在严格模式下漏网的问题。 ### 验证 24 个单元测试全通过（UrlSafetyChecker 21 + BrowserProperties 3），覆盖严格/豁免两模式 + 4 个 check 重载 + IPv6 IMDS 网段。 ### 风险 开关仅作用于浏览器工具；公网部署务必保持 false。 * feat(browser): Playwright 超时可配 + snapshot 智能截断与 selector 作用域 ### 背景 Agent 用浏览器工具访问慢链路或大页面（超大表格）时遇到两类问题： 1. Playwright 默认 30s 超时不够用，且无法配置 2. snapshot 全量抓取页面文本，硬截断在 20000 字符处会切在元素中间，LLM 拿到残缺数据且不知道有截断 ### 方案 新增三个 .env 开关（默认值与改动前完全一致）： 开关 作用 PLAYWRIGHT_DEFAULT_TIMEOUT_SECONDS 单次操作超时（click / fill / waitForLoadState） PLAYWRIGHT_NAVIGATION_TIMEOUT_SECONDS 导航超时（page.navigate / load-state） PLAYWRIGHT_SNAPSHOT_MAX_LENGTH snapshot 文本截断长度 snapshot 改造： - 支持 selector 参数作用域到子树（之前只用于 click/type） - budget 机制按元素边界智能截断，不再切在 <td> 中间 - 返回 truncated:true + hint 引导 LLM 用 selector 重抓 - JSON 字段顺序优化：truncated/hint 放 content 前，确保框架 spill preview（head 800 chars）能切到 ### 验证 - 28 个单元测试全通过（BrowserPropertiesTest 7 + UrlSafetyCheckerTest 21） - IDE 诊断 0 错误 - 覆盖：默认值不变 + setter 往返 + 严格/豁免两模式 ### 兼容性 - 默认值保持 30s / 30s / 20000，行为与改动前完全一致 - selector 参数本就是 @ToolParam(required=false) ，LLM schema 无变化，只是描述更新引导 snapshot 场景也能用 - 不影响 webhook / image download 等其他 SSRF 守卫 ## 改动汇总 文件 改动 BrowserProperties.java +3 字段： defaultTimeoutSeconds / defaultNavigationTimeoutSeconds / snapshotMaxLength （默认 30/30/20000） BrowserLauncher.java 抽 applyContextDefaults(context) 在三处 context 创建点调用；补全 setIgnoreHTTPSErrors 在 wrapLocalBrowser 落地 BrowserUseTool.java 工具描述 + selector 描述引导 LLM 在 snapshot 场景用 selector；doSnapshot 改造支持 selector 参数 + budget 智能截断 + JSON 字段顺序（truncated/hint 放 content 前确保 spill preview 能切到） docker-compose.yml +3 开关： PLAYWRIGHT_DEFAULT_TIMEOUT_SECONDS / PLAYWRIGHT_NAVIGATION_TIMEOUT_SECONDS / PLAYWRIGHT_SNAPSHOT_MAX_LENGTH .env.example +3 开关，简短说明 BrowserPropertiesTest.java +4 测试覆盖新字段默认值和 setter ## 测试结果 ## 数据流论证的关键决策 决策 依据 truncated:true 和 hint 放在 JSON content 字段之前 ToolResultStorage.buildPreview 会把 >8000 chars 的结果截到 head 800 chars，放在前面确保 LLM 看到 selector 参数描述从 "for click/type" 改为明确说 "OPTIONAL for snapshot" LLM 读 JSON schema 时按描述判断参数用途，原描述误导 LLM 不在 snapshot 用 selector 截断从硬 substring(0, N) 改为 JS budget 机制递归累计 避免切在 <td>订单号 ABC 中间，截断发生在 TEXT_NODE 完整段或下一个子元素开始之前 用 ElementHandle.querySelector + evaluate 替代字符串拼接 selector 进 JS 防止 selector 注入（selector 含特殊字符如引号、反斜杠） 三处 context 创建点统一调 applyContextDefaults 确保 CDP / external-CDP / 本地 launch 三条路径都应用配置的 timeout ## 临时改动还原 文件 改动 还原状态 mateclaw-server/pom.xml 临时加 maven-compiler-plugin + Lombok annotation processor ✅ 已删除，恢复原始状态 ## 未测项 项 原因 doSnapshot 的 JS budget 逻辑 需启动真 Playwright + 大页面，单元测试范围外 BrowserLauncher.applyContextDefaults 是否真的影响 page.click 行为 同上，集成测试范围 LLM 是否真的会按 hint 用 selector 重调 取决于 LLM 推理能力，需端到端测试
130 lines
6.8 KiB
Plaintext
130 lines
6.8 KiB
Plaintext
# MateClaw 环境变量配置
|
||
# 复制此文件为 .env 并填写实际值：cp .env.example .env
|
||
#
|
||
# LLM API Key（DashScope、OpenAI 等）无需在此配置，启动后在管理界面「模型管理」中添加。
|
||
#
|
||
# ⚠️ 所有标注「必填」的项若没配置，`docker compose up` 会直接失败退出，避免把默认/示例值带到生产环境。
|
||
|
||
# ==================== 数据库（Docker 模式必填） ====================
|
||
|
||
DB_HOST=localhost
|
||
DB_PORT=3306
|
||
DB_NAME=mateclaw
|
||
DB_USERNAME=mateclaw
|
||
|
||
# ⚠️ 必填且请改成强密码（至少 16 位，含大小写+数字+符号）。
|
||
# docker-compose.yml 会通过 ${DB_PASSWORD:?} 强制要求此项。
|
||
DB_PASSWORD=change-me-strong-user-password
|
||
|
||
# ⚠️ MySQL root 账号密码，仅用于容器内初始化。请改成与 DB_PASSWORD 不同的强密码。
|
||
DB_ROOT_PASSWORD=change-me-strong-root-password
|
||
|
||
# ==================== 安全（强烈建议覆盖） ====================
|
||
|
||
# JWT 签名密钥。若留空，服务器会用内置默认值并在启动日志里 WARN。
|
||
# 生产部署必须设置，至少 32 位随机字符串：openssl rand -base64 48
|
||
JWT_SECRET=
|
||
|
||
# CORS 白名单（逗号分隔，如 https://mateclaw.example.com,https://admin.example.com）。
|
||
# 若留空，服务器会允许所有 origin 并在启动日志里 WARN。生产部署务必设置。
|
||
MATECLAW_CORS_ALLOWED_ORIGINS=
|
||
|
||
# 公开访问基址（如 https://mateclaw.example.com）。用于把智能体生成文件的下载
|
||
# 链接拼成绝对地址，便于在 Web 之外（IM 消息、复制链接、外部下载）直接打开。
|
||
# 留空时回退到当前请求的 host，再退回相对路径。反代后部署建议显式设置。
|
||
MATECLAW_PUBLIC_BASE_URL=
|
||
|
||
# 是否公开 Swagger UI / OpenAPI 文档（/swagger-ui.html、/v3/api-docs）。
|
||
# 生产数据库 profile（mysql/kingbase/postgres）默认 false —— 匿名无法浏览全部
|
||
# 端点结构，需全局管理员（ROLE_ADMIN）。仅在内网/预发临时调试时设为 true。
|
||
MATECLAW_OPENAPI_EXPOSE_UI=
|
||
|
||
# SearXNG 会话密钥（容器内部用，留空会用开发默认值）。生产部署请设成 32+ 位随机串。
|
||
# openssl rand -hex 32
|
||
SEARXNG_SECRET=
|
||
|
||
# ==================== 浏览器工具（可选） ====================
|
||
#
|
||
# Docker 镜像已经把 Chromium 打进去了，默认零配置可用。
|
||
# 只有在下述场景才需要 override：
|
||
#
|
||
# 1) 把浏览器独立部署成 sidecar 容器，通过 CDP 连接：
|
||
# MATECLAW_BROWSER_CDP_URL=http://chrome-sidecar:9222
|
||
#
|
||
# 2) 指定非 Playwright 打包的浏览器（例如宿主机上已装的 Chrome）：
|
||
# MATECLAW_BROWSER_CHROME_PATH=/usr/bin/google-chrome-stable
|
||
#
|
||
# 3) 强制使用 Playwright channel（chrome / msedge / chrome-beta …）：
|
||
# MATECLAW_BROWSER_CHANNEL=chrome
|
||
MATECLAW_BROWSER_CDP_URL=
|
||
MATECLAW_BROWSER_CHROME_PATH=
|
||
MATECLAW_BROWSER_CHANNEL=
|
||
|
||
# ==================== 局域网 部署放开（可选，默认 false 严格模式） ====================
|
||
# 浏览器 SSRF 防护：放行本地回环和私有 IP（127.0.0.1 / 10.x / 192.168.x /
|
||
# 172.16-31.x / IPv6 fc00::/7 等），公网部署务必保持 false，否则 SSRF 防护失效
|
||
PLAYWRIGHT_ALLOW_PRIVATE_NETWORK=false
|
||
# 浏览器忽略 HTTPS 证书错误（自签证书 / IP 直连 HTTPS 场景）
|
||
# 公网部署务必保持 false，否则中间人攻击可绕过证书校验
|
||
PLAYWRIGHT_IGNORE_HTTPS_ERRORS=false
|
||
# Playwright 单次操作超时（秒），慢链路 / 大页面可调高
|
||
PLAYWRIGHT_DEFAULT_TIMEOUT_SECONDS=30
|
||
# Playwright 导航超时（秒），慢网络可调高
|
||
PLAYWRIGHT_NAVIGATION_TIMEOUT_SECONDS=30
|
||
# snapshot 文本截断长度，超出会返回 truncated:true 提示 LLM 用 selector 缩小范围
|
||
PLAYWRIGHT_SNAPSHOT_MAX_LENGTH=20000
|
||
|
||
# ==================== OpenAI OAuth（Docker，可选） ====================
|
||
#
|
||
# OpenAI ChatGPT OAuth 使用 Codex CLI 的 public client + PKCE / device code，
|
||
# 不需要自定义 client secret。
|
||
#
|
||
# 默认留空即可。后端会根据访问 Host 自动选择：
|
||
# - localhost / 127.0.0.1 / ::1 → LOCAL（PKCE 回调）
|
||
# - IP / 域名 / 反向代理访问 → DEVICE_CODE（无缝远程授权）
|
||
#
|
||
# 本机 Docker 若希望像桌面版一样直接通过宿主机浏览器完成
|
||
# http://localhost:1455/auth/callback 回调，可显式开启 LOCAL，并让容器内
|
||
# 临时回调服务监听 0.0.0.0，以便通过 `1455:1455` 端口映射被宿主机访问到：
|
||
# MATECLAW_OAUTH_OPENAI_DEPLOYMENT_MODE=local
|
||
# MATECLAW_OAUTH_OPENAI_CALLBACK_BIND_HOST=0.0.0.0
|
||
#
|
||
# 强制模式调试时也可设为：local / device_code / manual_paste
|
||
MATECLAW_OAUTH_OPENAI_DEPLOYMENT_MODE=
|
||
MATECLAW_OAUTH_OPENAI_CALLBACK_BIND_HOST=
|
||
|
||
# ==================== Wiki 知识库目录白名单（Docker 模式，可选）====================
|
||
#
|
||
# Docker 生产部署开启了路径安全校验（fail-closed）。
|
||
# 知识库使用「目录扫描」功能时，扫描路径必须在此白名单内，否则返回 400 错误。
|
||
# 多个路径用英文逗号分隔；留空则禁止所有目录扫描。
|
||
#
|
||
# 示例：MATE_WIKI_ALLOWED_SOURCE_ROOTS=/data/wiki,/opt/docs
|
||
#
|
||
# 同时在 docker-compose.yml 的 volumes 里把宿主机目录挂进容器，例如：
|
||
# volumes:
|
||
# - /your/host/path:/data/wiki
|
||
MATE_WIKI_ALLOWED_SOURCE_ROOTS=
|
||
|
||
# ── Wiki 知识源自动同步（变更监测）总开关 ────────────────────────
|
||
# 定时扫描各知识库的源目录、自动消化新文件。默认关闭，运维主动开启。
|
||
# AND 语义：全局这个开关开 *且* 某知识库自己的「自动同步」开关也开，
|
||
# 该库才会被定时扫描；手动「立即扫描」不受此开关影响。
|
||
# 间隔单位毫秒，默认 5 分钟（目前为全局，暂不支持按库配置）。
|
||
MATE_WIKI_WATCHER_ENABLED=false
|
||
MATE_WIKI_WATCHER_INTERVAL_MS=300000
|
||
|
||
# ── Skill 工作区目录 ─────────────────────────────────────────────
|
||
# 已安装的 skill、运行时积累的 LESSONS.md、skill 运行产物都落在这个目录。
|
||
# 默认（容器内）已指向 /app/data/skills，由 docker-compose 的 server_data 卷
|
||
# 持久化，容器重启不丢，无需额外挂卷。一般无需修改。
|
||
# 内置 skill 由 JAR classpath 每次启动现场释放，挂空卷也不会丢内置文件。
|
||
# 仅当你想把 skill 目录放到别处（如独立的 bind mount）时才覆盖此项，
|
||
# 并记得在 docker-compose.yml 的 volumes 里把对应宿主机目录挂进容器。
|
||
MATECLAW_SKILL_WORKSPACE_ROOT=
|
||
|
||
# ── Maven 镜像（国内加速）─────────────────────────────────────────
|
||
# 在中国大陆构建时取消注释，将 Aliyun 仓库优先级提前，大幅提速 mvn 拉包。
|
||
# 空值（默认）使用 US Maven Central → Google CDN → Aliyun 的顺序。
|
||
#MAVEN_FLAGS=-Paliyun-first
|