feat(camofox): 添加 camofox 反检测浏览器部署栈

- 新增 stack.yml 编排、env.cfg.example 模板、readme.md 文档
- 支持认证模式、代理配置、健康检查
- 复用旧 docker run 容器的命名卷 camofox-data

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

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

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}`。

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