diff --git a/camofox/.env.example b/camofox/.env.example new file mode 100644 index 0000000..c325ace --- /dev/null +++ b/camofox/.env.example @@ -0,0 +1,22 @@ +# ============================================================ +# Camofox 部署变量模板 +# 复制为 .env 后按需修改: cp .env.example .env +# compose 自动读取同目录 .env，无需额外 source +# ============================================================ + +# 认证模式: disabled(仅本机回环) | required(需配 CAMOFOX_API_KEY) +CAMOFOX_AUTH_MODE=disabled + +# required 模式密钥（openssl rand -hex 32 生成） +CAMOFOX_API_KEY= + +# ===== 可选代理（可省，留空即直连）===== +# 支持 http://host:port 或 socks5://host:port 对应格式 +# 例: PROXY_HOST=192.168.1.10 PROXY_PORT=7890 +PROXY_HOST= +PROXY_PORT= +PROXY_USERNAME= +PROXY_PASSWORD= + +# ⚠️ 启用代理时此项必须 true（非 loopback 绑定 + 代理 = fail-closed 强制） +CAMOFOX_ALLOW_PRIVATE_NETWORK=false \ No newline at end of file diff --git a/camofox/env.cfg.example b/camofox/env.cfg.example new file mode 100644 index 0000000..5e2dc0d --- /dev/null +++ b/camofox/env.cfg.example @@ -0,0 +1,41 @@ +# ============================================================ +# camofox 部署 — 公共环境变量模板（不含敏感信息） +# 复制为 env.cfg 后填入真实值，env.cfg 已在 .gitignore 中忽略 +# ============================================================ +# +# 使用方式： +# cp env.cfg.example env.cfg +# $EDITOR env.cfg +# docker compose -p camofox --env-file ./env.cfg -f ./stack.yml up -d +# + +# ---------- 镜像 ---------- +# Camofox 版本号（上游镜像 redf0x1/camofox-browser） +IMAGE_TAG_VER=2.4.7 +# 完整镜像引用 +IMAGE_TAG=redf0x1/camofox-browser:${IMAGE_TAG_VER} + +# ---------- 容器内监听（与端口映射右侧需对齐）---------- +# 容器内绑定地址：必须 0.0.0.0；loopback (127.0.0.1) 会导致端口映射不通 +CAMOFOX_HOST=0.0.0.0 +# 容器内监听端口（与宿主机映射端口右侧对齐） +CAMOFOX_PORT=9377 + +# ---------- 认证 ---------- +# disabled = 无鉴权（仅限本机回环使用） +# required = 需要 CAMOFOX_API_KEY（多客户端/远程场景） +CAMOFOX_AUTH_MODE=disabled +# required 模式下的 API 密钥（disabled 模式留空） +CAMOFOX_API_KEY= + +# ---------- 代理（可选，治境外站加载挂死 / 提升反检测）---------- +# 启用后浏览器加载境外站点不再直连，所有页面流量走代理 +# 支持 http:// 和 socks5:// 格式；住宅/家宽 IP 代理反检测效果显著 +# 取消下方注释并填入真实值启用： +#PROXY_HOST= +#PROXY_PORT= +#PROXY_USERNAME= +#PROXY_PASSWORD= + +# 启用代理 + CAMOFOX_HOST 非 loopback 时必须设为 true，否则服务拒绝启动 +CAMOFOX_ALLOW_PRIVATE_NETWORK=false \ No newline at end of file diff --git a/camofox/readme.md b/camofox/readme.md new file mode 100644 index 0000000..6bd9e70 --- /dev/null +++ b/camofox/readme.md @@ -0,0 +1,72 @@ +# Camofox 部署 + +反检测浏览器服务，Hermes browser 工具后端（Camoufox 引擎，C++ 层指纹伪装）。 +镜像 `redf0x1/camofox-browser`（`2.4.7`）预装引擎与版本元数据，零下载直跑。 + +## 快速开始 + +```bash +cp env.cfg.example env.cfg # 按需配置（默认 disabled 认证即可用） +docker compose -p camofox --env-file ./env.cfg -f ./stack.yml up -d +docker compose -p camofox --env-file ./env.cfg -f ./stack.yml ps # 期望 healthy +curl -s http://localhost:9377/health +# {"ok":true,"running":true,"engine":"camoufox","version":"2.4.7",...} +``` + +## 从 docker run 容器迁移（本次部署场景） + +之前直接 `docker run` 跑过同名容器，切换到 compose： + +```bash +docker rm -f camofox # 删掉旧容器（卷 camofox-data 保留复用） +docker compose -p camofox --env-file ./env.cfg -f ./stack.yml up -d +``` + +## Hermes 接入（已配置，无需改动） + +`~/.hermes/.env` 已有 `CAMOFOX_URL=http://localhost:9377`，browser 工具自动走 camofox。 +验证：Hermes 中调用 browser 工具 → camofox 容器日志出现 `/tabs` 请求、health 中 +`browserConnected` 变 true。 + +## 代理（可选，治境外站加载挂死 / 提升反检测） + +编辑 `env.cfg` 取消注释并填值： + +```cfg +PROXY_HOST=<代理IP或域名> +PROXY_PORT=<端口> +PROXY_USERNAME=<可选> +PROXY_PASSWORD=<可选> +CAMOFOX_ALLOW_PRIVATE_NETWORK=true # 必须 true，否则服务拒绝启动 +``` + +然后重建容器： + +```bash +docker compose -p camofox --env-file ./env.cfg -f ./stack.yml up -d +``` + +代理是引擎级（Camoufox context proxy），页面所有流量走代理；支持 http 与 socks5 格式。 +住宅/家宽 IP 代理能显著提高 Cloudflare 等验证码通过率（数据中心 IP 天然低信任）。 + +## 常见问题 + +| 现象 | 处理 | +|---|---| +| 启动即退 | 容器内 `CAMOFOX_HOST` 必须 `0.0.0.0`（默认 127.0.0.1 映射不通）；AUTH disabled 时不能设 CAMOFOX_API_KEY | +| 启用代理后拒启 | 需 `CAMOFOX_ALLOW_PRIVATE_NETWORK=true` | +| 重型境外页 30s 超时 | 直连资源慢/挂；配代理；或换轻量目标 | +| 端口被占用 | 修改 `stack.yml` 端口映射 + `env.cfg` 中 `CAMOFOX_PORT` 同步对齐 | + +## 目录 + +``` +camofox/ +├── stack.yml # Docker Compose 编排 +├── env.cfg.example # 变量模板 → 复制为 env.cfg +├── readme.md +└── env.cfg # 真实变量（gitignore，部署时手工创建） +``` + +数据持久化：docker managed named volume `camofox-data` 挂载到 `/home/node/.camofox` +（profiles、引擎缓存、cookie）。复用旧 `docker run` 创建的同名卷；全新部署可改为 bind mount 到 `${Volumes_Path}`。 \ No newline at end of file diff --git a/camofox/stack.yml b/camofox/stack.yml new file mode 100644 index 0000000..bd08b52 --- /dev/null +++ b/camofox/stack.yml @@ -0,0 +1,57 @@ +# pull:: docker compose -p camofox --env-file ./camofox/env.cfg -f ./camofox/stack.yml pull +# run:: docker compose -p camofox --env-file ./camofox/env.cfg -f ./camofox/stack.yml up -d +# +# disc:: 数据卷使用 docker managed named volume `camofox-data` +# （复用旧 docker run 容器同名卷；全新部署可改为 bind mount 到 ${Volumes_Path}） + +services: + camofox: + image: ${IMAGE_TAG} + container_name: camofox + restart: unless-stopped + + # 只暴露宿主机回环，外部不可达（Hermes 同机访问） + ports: + - "127.0.0.1:9377:9377" + # VNC 可视化调试端口（可选，headless 排障用）： + # - "127.0.0.1:6080:6080" + + environment: + - TZ=Asia/Shanghai + # 容器内必须绑 0.0.0.0，否则 docker 端口映射转发不到（实测坑） + - CAMOFOX_HOST=${CAMOFOX_HOST} + - CAMOFOX_PORT=${CAMOFOX_PORT} + - CAMOFOX_AUTH_MODE=${CAMOFOX_AUTH_MODE} + - CAMOFOX_API_KEY=${CAMOFOX_API_KEY} + # 代理（PROXY_* 默认空 = 不启用；启用时取消 env.cfg 中注释并配合 CAMOFOX_ALLOW_PRIVATE_NETWORK=true） + - PROXY_HOST=${PROXY_HOST:-} + - PROXY_PORT=${PROXY_PORT:-} + - PROXY_USERNAME=${PROXY_USERNAME:-} + - PROXY_PASSWORD=${PROXY_PASSWORD:-} + - CAMOFOX_ALLOW_PRIVATE_NETWORK=${CAMOFOX_ALLOW_PRIVATE_NETWORK} + + # profiles / 引擎数据持久化（docker managed named volume，复用同名旧卷） + volumes: + - camofox-data:/home/node/.camofox + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + + # 镜像自带 HEALTHCHECK（docker ps 显示 healthy），此处仅为显式化 + healthcheck: + test: ["CMD", "curl", "-fsS", "http://localhost:${CAMOFOX_PORT}/health"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 15s + + logging: + driver: json-file + options: + max-size: "20m" + max-file: "3" + +volumes: + camofox-data: + # 复用已有同名 named volume（容器 camofox 之前 create 的） + # 全新部署可删掉 name: 或改为 bind mount 到 ${Volumes_Path}/data + name: camofox-data \ No newline at end of file